Referência da API de Chamadas

URL base: https://pilotstatus.com.br/v1 Cabeçalhos: Content-Type: application/json, x-api-key: <your_api_key> (ou x-api-key-id).

As chamadas funcionam em dois provedores: números Meta Cloud API e números não oficiais (Pilot Status web) (conectados por QR). Qualquer outro provedor retorna 400 FEATURE_NOT_SUPPORTED. Todos os endpoints exigem uma chave com escopo de número. Veja a visão geral.

Meta exige SDP. No provedor Meta a mídia flui pelo navegador via WebRTC — você fornece uma oferta SDP ao iniciar e uma resposta SDP ao atender. O provedor não oficial não usa SDP: a mídia é tratada no servidor, então sdpOffer/sdpAnswer permanecem null e não há modelo de permissão BIC nem superfície de configurações de chamada.

Endpoints

Os provedores marcados são os que suportam cada endpoint. Chamar um endpoint em um provedor não suportado retorna 400 FEATURE_NOT_SUPPORTED. Se um número não oficial não estiver conectado, os endpoints retornam 409 WHATSAPP_INSTANCE_NOT_CONNECTED.

Método	Endpoint	Provedores	Descrição
`POST`	`/v1/calls`	META, não oficial	Inicia uma chamada iniciada pela empresa (BIC).
`GET`	`/v1/calls`	META, não oficial	Lista as chamadas do número (mais recentes primeiro; `limit` 1–100, `before` cursor ISO 8601).
`GET`	`/v1/calls/{callId}`	META, não oficial	Uma chamada; adicione `?includeSdp=1` para receber `sdpOffer`/`sdpAnswer` (Meta).
`POST`	`/v1/calls/{callId}/accept`	META, não oficial	Atende uma chamada recebida (UIC). No Meta, com resposta SDP; no não oficial, sem SDP.
`POST`	`/v1/calls/{callId}/reject`	META, não oficial	Recusa uma chamada recebida (sem corpo).
`POST`	`/v1/calls/{callId}/terminate`	META, não oficial	Desliga uma chamada ativa (sem corpo).
`POST`	`/v1/calls/{callId}/pre-accept`	Somente META	Resposta SDP antecipada OPCIONAL (reduz cortes no áudio; a chamada só conecta ao aceitar).
`GET`	`/v1/calls/settings`	Somente META	Lê o objeto de configurações `calling` do número.
`PUT`	`/v1/calls/settings`	Somente META	Atualização parcial das configurações `calling`.
`GET`	`/v1/calls/permissions?to=<phone>`	Somente META	Verifica se a empresa pode ligar para `to`.
`POST`	`/v1/calls/permissions/request`	Somente META	Envia a solicitação interativa de permissão de chamada (dentro da janela de 24h).
`POST`	`/v1/calls/{callId}/play`	Somente não oficial	Reproduz um arquivo de áudio na chamada (mídia no servidor); `hangupAfterPlay` opcional.
`POST`	`/v1/calls/{callId}/realtime-session`	Somente não oficial	Abre uma sessão WebSocket full-duplex de áudio PCM16.

{callId} aceita ou o id de chamada do Pilot Status (call_...) ou o id de chamada da Meta (wacid...).

1. Iniciar uma chamada (BIC)

curl -X POST "https://pilotstatus.com.br/v1/calls" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{
    "to": "+5511999999999",
    "sdp": "v=0\r\no=- 4611731400430051336 2 IN IP4 127.0.0.1\r\n...",
    "sdpType": "offer",
    "bizOpaqueCallbackData": "order-42"
  }'

curl -X POST "https://pilotstatus.com.br/v1/calls" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{ "to": "+5511999999999" }'

HTTP 201
{ "id": "call_01HZX...", "externalCallId": "wacid.ABGG...", "status": "INITIATED" }

Meta: sdp é a oferta RFC 8866 produzida pelo SEU cliente WebRTC. O SDP do lado da empresa deve usar a=setup:active. Sem permissão, a Meta retorna 138006 → o endpoint expõe code: "META_CALL_PERMISSION_REQUIRED".
não oficial: não envie sdp — a mídia é tratada no servidor. Não há modelo de permissão BIC.
bizOpaqueCallbackData (opcional, Meta) é devolvido no webhook de encerramento.

2. Atender uma chamada recebida (UIC)

Quando um usuário liga para o seu número, você recebe o webhook call.ringing. Então:

# busca a chamada com a oferta SDP
curl "https://pilotstatus.com.br/v1/calls/wacid.ABGG...?includeSdp=1" \
  -H "x-api-key: ps_your_key_here"

# atende (corpo: sua resposta SDP; sdpType usa "answer" como padrão)
curl -X POST "https://pilotstatus.com.br/v1/calls/wacid.ABGG.../accept" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{ "sdp": "v=0\r\n..." }'

curl -X POST "https://pilotstatus.com.br/v1/calls/call_01HZX.../accept" \
  -H "x-api-key: ps_your_key_here"

# recusa / desliga (sem corpo, ambos provedores)
curl -X POST "https://pilotstatus.com.br/v1/calls/wacid.ABGG.../reject" -H "x-api-key: ps_your_key_here"
curl -X POST "https://pilotstatus.com.br/v1/calls/wacid.ABGG.../terminate" -H "x-api-key: ps_your_key_here"

accept/pre-accept/reject/terminate respondem { "success": true, "id": "call_...", "status": "..." }. O pre-accept (somente Meta) é opcional (resposta SDP antecipada para reduzir cortes); a chamada só conecta no accept.

3. Habilitar chamadas e configurações (somente Meta)

As seções 3 e 4 aplicam-se apenas a números Meta. No provedor não oficial não há superfície de configurações de chamada nem modelo de permissão BIC — chamar esses endpoints retorna 400 FEATURE_NOT_SUPPORTED.

O Pilot Status tenta habilitar chamadas automaticamente quando um número Meta conecta. Leia/ajuste a qualquer momento:

curl "https://pilotstatus.com.br/v1/calls/settings" \
  -H "x-api-key: ps_your_key_here"

curl -X PUT "https://pilotstatus.com.br/v1/calls/settings" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{ "status": "ENABLED", "call_icon_visibility": "DEFAULT" }'

O PUT é parcial: envie apenas status, call_icon_visibility, callback_permission_status, call_hours, voicemail (o objeto sip é rejeitado).
Um call_hours enviado substitui o objeto armazenado por completo (semântica da Meta).
Números com um limite de mensagens abaixo de 2.000/dia ainda não podem habilitar chamadas (erro 138015 da Meta → o Pilot Status marca o número como PENDING_TIER e re-tenta conforme o tier sobe).
Habilitar também exige que a WABA tenha o campo de webhook calls subscrito (ou SIP configurado); sem isso a Meta retorna 138018 e o Pilot Status marca o número como PENDING_WEBHOOK. Subscreva o campo calls na WABA (ou configure SIP) e tente de novo.
Você também pode disparar pelo painel — o botão Habilitar chamada nos detalhes Meta do número (página Números) responde ENABLED, PENDING_TIER ou PENDING_WEBHOOK.
Credenciais SIP nunca são solicitadas nem retornadas.

4. Permissão de chamada (somente Meta, obrigatória antes de uma BIC)

# verificar
curl "https://pilotstatus.com.br/v1/calls/permissions?to=%2B5511999999999" \
  -H "x-api-key: ps_your_key_here"

# solicitar (dentro da janela de atendimento de 24h)
curl -X POST "https://pilotstatus.com.br/v1/calls/permissions/request" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{ "to": "+5511999999999", "text": "May we call you about your order?" }'

Resposta da verificação:

{
  "permission": { "status": "temporary", "expiration_time": 1768550400 },
  "actions": [
    {
      "action_name": "start_call",
      "can_perform_action": true,
      "limits": [{ "time_period": "PT24H", "max_allowed": 1, "current_usage": 0 }]
    }
  ]
}

A resposta do usuário chega como o evento de webhook call.permission_updated (status: NO_PERMISSION | TEMPORARY | PERMANENT). A Meta limita a taxa de solicitações de permissão (erro 138009) e o volume de BIC (100 chamadas/24h por número — erro 138012).

5. Reproduzir áudio na chamada (somente não oficial)

Nos números não oficiais a mídia é tratada no servidor, então você pode instruir o backend a baixar um arquivo de áudio e reproduzi-lo na chamada ativa. O backend busca a URL através de um guard de SSRF.

curl -X POST "https://pilotstatus.com.br/v1/calls/call_01HZX.../play" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_key_here" \
  -d '{ "url": "https://example.com/audio.ogg" }'

Endpoint somente não oficial — em um número Meta retorna 400 FEATURE_NOT_SUPPORTED.

6. Sessão de áudio em tempo real (somente não oficial)

Abre uma sessão WebSocket full-duplex de áudio PCM16 para transmitir áudio de/para a chamada ao vivo.

curl -X POST "https://pilotstatus.com.br/v1/calls/call_01HZX.../realtime-session" \
  -H "x-api-key: ps_your_key_here"

{ "wsUrl": "wss://<host-de-mídia-dedicado>/...", "token": "...", "expiresIn": 120 }

A wsUrl retornada aponta para um host de mídia dedicado — conecte-se diretamente a ela (não é feito proxy). O token é de uso único com TTL de ~2 minutos. A camada HTTP não faz upgrade de WebSocket. Endpoint somente não oficial (Meta → 400 FEATURE_NOT_SUPPORTED).

7. Objeto de chamada (DTO)

{
  "id": "call_01HZX...",
  "externalCallId": "wacid.ABGG...",
  "direction": "INBOUND",
  "status": "COMPLETED",
  "peerNumber": "5511999999999",
  "fromNumber": "5511999999999",
  "conversationId": "conv_abc",
  "bizOpaqueCallbackData": null,
  "startedAt": "2026-07-03T15:00:00.000Z",
  "connectedAt": "2026-07-03T15:00:05.000Z",
  "endedAt": "2026-07-03T15:02:05.000Z",
  "durationSeconds": 120,
  "errorCode": null,
  "errorMessage": null,
  "createdAt": "2026-07-03T15:00:00.000Z",
  "updatedAt": "2026-07-03T15:02:05.000Z"
}

status: INITIATED | RINGING | ACCEPTED | REJECTED | COMPLETED | FAILED | MISSED.
direction: INBOUND (UIC) | OUTBOUND (BIC).
Os SDPs (sdpOffer/sdpAnswer) aparecem apenas com ?includeSdp=1 em GET /v1/calls/{callId} — nunca na listagem. No provedor não oficial permanecem null (mídia no servidor).
durationSeconds é definido apenas quando a chamada foi atendida.

Webhooks

Estes eventos disparam para ambos os provedores (META e não oficial):

Eventos de chamada

call.ringing · call.connected · call.ended (com duration em segundos quando atendida) · call.missed

O evento call.permission_updated é exclusivo da Meta — números não oficiais não têm modelo de permissão de chamada. (No objeto de chamada REST retornado por GET /v1/calls, o campo equivalente é durationSeconds.)

Faturamento

Meta: as BIC são cobradas pela Meta na WABA (por minuto, pulsos de 6s, apenas quando atendida). As UIC são gratuitas.
não oficial: sem cobrança por minuto da Meta.
O Pilot Status não cobra nada pelas chamadas em nenhum dos provedores.

Erros comuns

400 FEATURE_NOT_SUPPORTED — o número da chave não suporta o endpoint (ex.: um provedor não suportado, ou um endpoint exclusivo de um provedor chamado no outro).
409 WHATSAPP_INSTANCE_NOT_CONNECTED — número não oficial não conectado.
400 NUMBER_NOT_FOUND — a chave não está vinculada a um número.
400 — validação do corpo, INVALID_LIMIT, INVALID_BEFORE, MISSING_TO.
401 — x-api-key / x-api-key-id ausente/inválido.
403 — chave com escopo de tenant (os endpoints de chamadas têm escopo de número).
404 CALL_NOT_FOUND — o callId/wacid não pertence ao número da chave.
Erros de chamada da Meta são encaminhados com um code mapeado — ex.: META_CALL_PERMISSION_REQUIRED (138006), limite de solicitação de permissão (138009), limite de BIC de 100 chamadas/24h (138012), chamadas não habilitadas (138000), tier de mensagens muito baixo para habilitar (138015 → PENDING_TIER), pré-requisitos de chamada não atendidos — subscreva o campo de webhook calls ou configure SIP (138018 → PENDING_WEBHOOK), META_CALLING_PAYMENT_REQUIRED (131044 — a WABA não tem método de pagamento; chamadas iniciadas pela empresa são cobradas pela Meta, adicione um cartão em Configurações de pagamento do WhatsApp Manager).

Visão Geral

Mensagens

Modelos

Números

Conversas & Dados

Webhooks

Chamadas de Voz

Camada de Compatibilidade

Conta & Cobrança

Marca & Incorporação

Referência da API de Chamadas

Referência da API de Chamadas

Endpoints

1. Iniciar uma chamada (BIC)

2. Atender uma chamada recebida (UIC)

3. Habilitar chamadas e configurações (somente Meta)

4. Permissão de chamada (somente Meta, obrigatória antes de uma BIC)

5. Reproduzir áudio na chamada (somente não oficial)

6. Sessão de áudio em tempo real (somente não oficial)

7. Objeto de chamada (DTO)

Webhooks

Eventos de chamada

Faturamento

Erros comuns

​Referência da API de Chamadas

​Endpoints

​1. Iniciar uma chamada (BIC)

​2. Atender uma chamada recebida (UIC)

​3. Habilitar chamadas e configurações (somente Meta)

​4. Permissão de chamada (somente Meta, obrigatória antes de uma BIC)

​5. Reproduzir áudio na chamada (somente não oficial)

​6. Sessão de áudio em tempo real (somente não oficial)

​7. Objeto de chamada (DTO)

​Webhooks

Eventos de chamada

​Faturamento

​Erros comuns

Referência da API de Chamadas

Endpoints

1. Iniciar uma chamada (BIC)

2. Atender uma chamada recebida (UIC)

3. Habilitar chamadas e configurações (somente Meta)

4. Permissão de chamada (somente Meta, obrigatória antes de uma BIC)

5. Reproduzir áudio na chamada (somente não oficial)

6. Sessão de áudio em tempo real (somente não oficial)

7. Objeto de chamada (DTO)

Webhooks

Faturamento

Erros comuns