WhatsApp Calling — integração via hub

1. Visão geral

A WhatsApp Cloud API Calling envia atualizações de chamadas no mesmo fluxo de webhooks da Meta. Este hub:

• Recebe o POST da Meta em /api/webhooks/meta (já configurado no App).
• Quando o payload contém o array calls, encaminha cada item para as URLs configuradas na conexão (webhookUrl e/ou webhookUrl2).
• Cada encaminhamento usa o evento call.event e o corpo descrito abaixo.

O seu sistema pode iniciar outbound com call-offer/connect e, no inbound, gerar o SDP answer (WebRTC); o hub encaminha connect, pre_accept, accept, reject e terminate para a Graph API com o token da conexão — sem expor credenciais Meta ao seu frontend.

2. Configurar o seu endpoint

Na conexão WhatsApp do hub, informe a URL do seu sistema em Webhook URL (e opcionalmente Webhook URL 2). O hub fará POST com Content-Type: application/json.

Headers enviados pelo hub

• X-Webhook-Event: call.event
• X-Webhook-Timestamp — ISO 8601
• X-Webhook-Attempt — número da tentativa (retries em falhas transitórias)

3. Formato do JSON (outbound)

Campos de alto nível:

• event — sempre "call.event".
• timestamp — momento do encaminhamento pelo hub.
• connection — identificação da conexão (token, canal, nome, wabaId quando disponível).
• metadata — display_phone_number e phone_number_id do webhook Meta.
• call — objeto retornado pela Meta para aquele item (sanitizado; sem blobs base64).

Exemplo vivo (ambiente configurado):

GET {APP_URL}/api/integrations/whatsapp-calling/reference

Substitua {APP_URL} pela URL base da sua instância (ex.: https://api.suaempresa.com).

4. Aceitar, recusar ou encerrar (API do hub)

Autenticação: Authorization: Bearer <company_token_uuid> ou X-Company-Token (igual às outras rotas). Opcional: X-Request-Id, Idempotency-Key.

No corpo, informe connection_id (UUID da conexão = campo token no banco, mesmo que connection.id no webhook call.event) ou phone_number_id.

• POST {APP_URL}/api/calls/call-offer ou .../connect — inicia ligação outbound (body com to)
• POST {APP_URL}/api/calls/<callId>/pre-accept — corpo com session.sdp_type: "answer" e session.sdp
• POST {APP_URL}/api/calls/<callId>/accept — mesmo corpo (SDP answer final)
• POST {APP_URL}/api/calls/<callId>/reject ou .../decline
• POST {APP_URL}/api/calls/<callId>/terminate

Alias com prefixo interno (mesmo router): /api/internal/calls/<callId>/...

Contrato detalhado: docs/hub-calling-api-accept-decline.md no repositório.

5. Swagger / OpenAPI

O schema CallEventWebhookPayload e o endpoint de referência estão na documentação Swagger da API:

• GET /api-docs (ou a rota configurada para o Swagger UI no seu deploy)
• Tag: WhatsApp - Chamadas (Calling)

6. Meta — o que configurar

• Webhook do app apontando para este hub (/api/webhooks/meta).
• Inscrição nos campos necessários para chamadas na Cloud API (consulte a documentação atual da Meta para Calling).
• Elegibilidade da conta WABA / número para Calling (pode variar por região e produto).

7. Próximos passos no seu sistema

1. Implementar um endpoint HTTP que valide origem (IP fixo, assinatura se você adicionar no hub no futuro, ou segredo na query).
2. Persistir call.id e estado conforme os eventos que a Meta enviar.
3. Gerar SDP answer no browser ou media server e chamar o hub em pre_accept e accept na ordem recomendada pela Meta.