Pular para o conteúdo principal
O WhatsApp Business Calling permite fazer e receber chamadas de voz com seus clientes pelo WhatsApp. O Pilot Status cuida da sinalização; o áudio flui conforme o provedor do número — direto navegador↔WhatsApp (Meta) ou no servidor (Pilot Status web).
Chamadas de voz funcionam em dois tipos de provedor: números Meta Cloud API e números Pilot Status web (não oficiais, conectados por QR). Qualquer outro tipo de número retorna 400 FEATURE_NOT_SUPPORTED. Em um número Pilot Status web ainda não conectado, os endpoints de chamada retornam 409 WHATSAPP_INSTANCE_NOT_CONNECTED.

​
Os dois provedores em resumo

Meta Cloud APIPilot Status web
SDP em POST /v1/calls e /acceptObrigatório (sdp de oferta/resposta, WebRTC)Nenhum — sdpOffer/sdpAnswer ficam null
Fluxo de mídiaNavegador↔WhatsApp (WebRTC)No servidor
Softphone no painel /chatSim (WebRTC)Sim (áudio no servidor)
Permissão de chamada e configuraçõesSimNão se aplica
Controle de áudioSeu cliente WebRTC/play e /realtime-session
Cobrança Meta por minuto (BIC)Sim, na sua WABANão há
O Pilot Status não cobra nada pelas chamadas. Em números Meta, os minutos de BIC são cobrados pela Meta diretamente na sua WABA; em números Pilot Status web não há cobrança Meta por minuto.

​
Endpoints comuns aos dois provedores

Estes endpoints funcionam tanto em Meta quanto em Pilot Status web:
  • POST /v1/calls — fazer uma chamada iniciada pela empresa (BIC)
  • GET /v1/calls — listar chamadas
  • GET /v1/calls/{callId} — detalhes de uma chamada
  • POST /v1/calls/{callId}/accept — atender
  • POST /v1/calls/{callId}/reject — recusar
  • POST /v1/calls/{callId}/terminate — encerrar

​
Os dois tipos de chamada

TipoQuem iniciaCobrança
BIC — Chamada Iniciada pela EmpresaVocê liga para o clienteMeta: cobrada na sua WABA (por minuto, pulsos de 6s, só quando atendida). Pilot Status web: sem cobrança Meta
UIC — Chamada Iniciada pelo UsuárioO cliente liga para vocêGratuita

​
Números Meta Cloud API

​
Caminho mais fácil: o softphone do painel

A página /chat do painel tem um softphone integrado que funciona nos dois tipos de número — atenda, faça, rejeite e encerre chamadas do WhatsApp sem escrever nenhum código. Em números Meta ele usa WebRTC no navegador; em números Pilot Status web o áudio é tratado no servidor. É a forma mais rápida de testar chamadas. Use a API abaixo quando quiser construir sua própria experiência de chamada.
Softphone do painel no /chat mostrando uma chamada ativa do WhatsApp

​
Requisitos (Meta)

  1. Um número Meta Cloud API conectado.
  2. Chamadas habilitadas no número: PUT /v1/calls/settings com { "status": "ENABLED" }. Números em um tier de mensagens abaixo de 2.000/dia não podem habilitar chamadas (erro Meta 138015).
  3. Para chamadas iniciadas pela empresa, uma permissão de chamada válida do usuário (veja abaixo).

​
Passo 1 — Obter permissão para ligar (só BIC)

Você só pode iniciar uma chamada iniciada pela empresa após o usuário conceder uma permissão de chamada. Solicite-a dentro da janela de atendimento de 24 horas: 
curl -X POST https://pilotstatus.com.br/v1/calls/permissions/request \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_seu_token_aqui" \
  -d '{ "to": "+5511999999999", "text": "Podemos ligar sobre seu pedido?" }'
A resposta do usuário chega como um webhook call.permission_updated. Consulte a permissão atual a qualquer momento: 
curl "https://pilotstatus.com.br/v1/calls/permissions?to=+5511999999999" \
  -H "x-api-key: ps_seu_token_aqui"
Retorna no_permission, temporary ou permanent mais os limites por ação. Sem permissão, POST /v1/calls retorna META_CALL_PERMISSION_REQUIRED.

​
Passo 2 — Fazer uma chamada (BIC)

Seu cliente WebRTC produz uma oferta SDP; passe-a ao Pilot Status, que a retransmite ao WhatsApp. O áudio então flui navegador↔WhatsApp diretamente. 
curl -X POST https://pilotstatus.com.br/v1/calls \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_seu_token_aqui" \
  -d '{ "to": "+5511999999999", "sdp": "<oferta SDP RFC 8866>", "sdpType": "offer" }'

HTTP 201
{ "id": "call_abc", "externalCallId": "wacid.HBg...", "status": "RINGING" }

​
Passo 3 — Receber uma chamada (UIC)

Quando um cliente liga para você, dispara um webhook call.ringing. Atenda com sua resposta SDP: 
curl -X POST https://pilotstatus.com.br/v1/calls/call_abc/accept \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_seu_token_aqui" \
  -d '{ "sdp": "<resposta SDP RFC 8866>" }'
  • POST /v1/calls/{callId}/pre-accept — resposta antecipada opcional que reduz o corte de áudio; a chamada ainda conecta apenas no accept. Somente Meta.
  • POST /v1/calls/{callId}/reject — recusar (sem corpo).
  • POST /v1/calls/{callId}/terminate — encerrar uma chamada ativa (sem corpo).
Os endpoints exclusivos da Meta — POST /v1/calls/{callId}/pre-accept, GET/PUT /v1/calls/settings, GET /v1/calls/permissions e POST /v1/calls/permissions/request — retornam 400 FEATURE_NOT_SUPPORTED em números Pilot Status web.

​
Números Pilot Status web

Em números Pilot Status web (não oficiais, conectados por QR), as chamadas funcionam de forma diferente: não há SDP e não há WebRTC no navegador. O áudio flui no servidor, e não existe modelo de permissão nem tela de configurações de chamada.

​
Fazer e atender (sem SDP)

Envie POST /v1/calls sem sdp; para atender uma chamada recebida, chame /accept sem corpo. Os campos sdpOffer/sdpAnswer permanecem null. 
# Fazer uma chamada de um número Pilot Status web
curl -X POST https://pilotstatus.com.br/v1/calls \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_seu_token_aqui" \
  -d '{ "to": "+5511999999999" }'

# Atender uma chamada recebida (sem corpo)
curl -X POST https://pilotstatus.com.br/v1/calls/call_abc/accept \
  -H "x-api-key: ps_seu_token_aqui"
Recusar e encerrar são iguais aos da Meta: POST /v1/calls/{callId}/reject e POST /v1/calls/{callId}/terminate.

​
Controlar o áudio da chamada

Como a mídia é tratada no servidor, você controla o áudio com dois endpoints exclusivos do Pilot Status web (retornam 400 FEATURE_NOT_SUPPORTED em números Meta): 
# O backend baixa seu arquivo (com proteção SSRF) e o toca na chamada
curl -X POST https://pilotstatus.com.br/v1/calls/call_abc/play \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_seu_token_aqui" \
  -d '{ "url": "https://exemplo.com/mensagem.ogg" }'
O wsUrl retornado por /realtime-session aponta para o host público de mídia dedicado (não é proxeado pelo Pilot Status). O token é de uso único com TTL de aproximadamente 2 minutos — conecte-se diretamente ao WebSocket assim que receber a resposta.

​
Requisitos (Pilot Status web)

  1. Um número Pilot Status web conectado. Se não estiver conectado, os endpoints de chamada retornam 409 WHATSAPP_INSTANCE_NOT_CONNECTED.
  2. Não há permissão de chamada nem configurações a habilitar — basta fazer ou atender a chamada.

​
Acompanhe o progresso com webhooks

Assine estes eventos no seu webhook — eles disparam para ambos os provedores (Meta e Pilot Status web): call.ringing, call.connected, call.ended (inclui duration em segundos quando atendida), call.missed e call.permission_updated. Em números Meta, o envelope nativo calls da Meta também é entregue para sinalização WebRTC personalizada.

​
Próximos passos

Referência da API de Chamadas

Todos os endpoints /v1/calls, parâmetros e configurações.

Visão geral de Chamadas

Modelo de sinalização, detalhes de cobrança e limites por provedor.