EntrarComeçar teste grátis
Meta Tech Provider

Webhooks de chamadas do WhatsApp: eventos da Calling API e chamadas em um número de Coexistência

O campo calls do webhook informa os eventos da WhatsApp Business Calling API: connect com uma resposta ou oferta SDP, os status de chamada RINGING, ACCEPTED e REJECTED, terminate com COMPLETED ou FAILED e a duração, e call_recording_available ou call_transcription_available. O guia de Coexistência da Meta lista chamadas de voz e vídeo como inalteradas no app do WhatsApp Business e sem suporte na Cloud API, então essas chamadas continuam no telefone.

O easyCoexistence conecta o número do seu app do WhatsApp Business à Cloud API da Meta por meio da Coexistência, para que sua IA e suas automações respondam a mensagens e enviem templates enquanto as chamadas continuam tocando no app do seu telefone.

Not supported

Chamadas de voz e vídeo na Cloud API para um número integrado a partir do app do WhatsApp Business; no app, elas continuam inalteradas.

2,000

Limite diário mínimo de mensagens, em destinatários únicos, que um número precisa ter antes de poder usar a Calling API.

7 days

Por quanto tempo gravações e transcrições de chamadas continuam disponíveis para download depois que o webhook correspondente é entregue.

wacid

O prefixo dos IDs de chamada, o valor que liga os webhooks de connect, status e terminate de uma mesma chamada.

whatsapp_business_messaging

A permissão de que um app precisa para receber webhooks de chamadas, a mesma exigida para mensagens.

O que o campo calls do webhook informa?

Tudo o que acontece com uma chamada feita ou recebida pela Calling API, em um único campo com um evento por etapa. Uma chamada iniciada pela empresa gera um evento connect, atualizações de status e um evento terminate. Chamadas tratadas via SIP informam call_created em vez de connect, sem a sessão SDP. Um evento relacionado fica em outro lugar: quando um cliente responde a uma solicitação de permissão de chamada, a resposta chega no campo messages como uma mensagem interativa do tipo call_permission_reply.

connectThe call is ready to connect; session carries the SDP to apply to your WebRTC stack.
call_createdA SIP call was attempted, business- or user-initiated.
statuses (type call)RINGING, ACCEPTED or REJECTED for a business-initiated call.
terminateThe call ended: status COMPLETED or FAILED, with times and duration when answered.
call_recording_availableA media id for the finished audio recording.
call_transcription_availableA media id for the transcript, a JSON document.

Como é um webhook de chamadas?

O mesmo envelope de todo webhook do WhatsApp, com um array calls em value e field definido como calls. direction indica BUSINESS_INITIATED ou USER_INITIATED; from e to trazem os números de telefone e to_user_id traz o BSUID do cliente, e qualquer um dos números pode estar ausente quando o cliente usa nome de usuário. metadata.phone_number_id identifica o seu número, como em qualquer outro campo. Este é o exemplo Call Connect da Meta, com os placeholders exatamente como a Meta os publica:

Meta's example: the Call Connect webhook
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315553601",
              "phone_number_id": "<PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<CALLEE_NAME>",
                  "username": "<USERNAME>"
                },
                "wa_id": "16315553602",
                "user_id": "<BSUID>",
                "parent_user_id": "<PARENT_BSUID>"
              }
            ],
            "calls": [
              {
                "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
                "to": "16315553601",
                "to_user_id": "<BSUID>",
                "to_parent_user_id": "<PARENT_BSUID>",
                "from": "16315553602",
                "event": "connect",
                "timestamp": "1671644824",
                "direction": "BUSINESS_INITIATED",
                "session": {
                  "sdp_type": "answer",
                  "sdp": "<<RFC 8866 SDP>>"
                }
              }
            ]
          },
          "field": "calls"
        }
      ]
    }
  ]
}

Quais campos o evento terminate acrescenta?

terminate é o evento que a maioria dos sistemas armazena, porque é ele que fecha a chamada. Seus campos, segundo a referência da Meta:

  • status: COMPLETED quando a chamada terminou sem erros inesperados, incluindo chamadas não atendidas; FAILED quando não conectou ou caiu.
  • start_time, end_time e duration em segundos: presentes somente quando a outra parte atendeu.
  • errors: code, message, href e error_data.details em uma chamada FAILED.
  • biz_opaque_callback_data: sua própria string de rastreamento, quando você enviou uma ao iniciar ou aceitar a chamada.

Os webhooks de chamadas funcionam em um número de Coexistência?

O guia de Coexistência da Meta responde isso na tabela de recursos: chamadas de voz e vídeo não mudam no app do WhatsApp Business e não têm suporte na Cloud API para um número integrado dessa forma. Os pré-requisitos da própria Calling API dizem o mesmo pelo outro lado: o número da empresa precisa estar em uso com a Cloud API, não com o app do WhatsApp Business. Portanto, em um número de Coexistência, os clientes continuam ligando como antes, a chamada toca no app, no telefone, e o campo calls não tem nada a informar. Uma empresa que precisa de chamadas em software usa um número somente na Cloud API.

Como os eventos de uma chamada se encaixam?

Pelo ID da chamada, que começa com wacid e se repete em todos os eventos daquela chamada. Uma chamada iniciada pela empresa informa connect com a resposta SDP, os status RINGING e depois ACCEPTED ou REJECTED e, por fim, terminate. Uma chamada iniciada pelo usuário informa connect com uma oferta SDP para a sua stack responder e depois terminate. Os eventos de gravação e transcrição, quando ativados, chegam depois de terminate. Use id mais event como chave dos eventos armazenados, já que as reentregas os repetem e a ordem de chegada não é garantida. A lista completa de pré-requisitos da Calling API está na página sobre chamadas em um número de Coexistência.

O que a sua IA pode fazer sobre chamadas em um número de Coexistência?

Atuar no chat, enquanto as chamadas continuam com a pessoa no telefone. O easyCoexistence não assina o campo calls e não tem ferramentas de chamada; seu conector e suas automações cobrem mensagens e templates. Na prática, uma resposta da IA pode informar ao cliente quando alguém está disponível para conversar e para qual número ligar, uma automação por palavra-chave pode responder a "ligar" ou "telefone" com essa informação, e o dono atende a chamada no app do WhatsApp Business como antes.

Erros comuns

  • Assinar o campo calls em um número de Coexistência e ficar esperando eventos. A Meta lista chamadas como sem suporte na Cloud API para esses números.
  • Esperar start_time e duration em todo terminate. Eles só aparecem quando a chamada foi atendida; uma chamada não atendida também termina como COMPLETED.
  • Procurar as respostas de permissão no campo calls. Elas chegam em messages, como uma mensagem interativa call_permission_reply.
  • Deixar as gravações e transcrições só na Meta. As duas podem ser baixadas por 7 dias após o webhook; depois disso, somem.
Fazendo isso com o EasyCoexistence

Cada número é monitorado 24/7, incluindo a regra dos 14 dias que desconecta um número cujo app não é aberto. De R$ 29,90 a R$ 3,90 por número conectado por mês, caindo conforme você adiciona números, com os 3 primeiros dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

Os clientes perdem o botão de ligar quando o número é conectado à API pela Coexistência?

O guia de Coexistência da Meta lista chamadas de voz e vídeo como inalteradas no app do WhatsApp Business. Os clientes ligam para o mesmo número, e o dono atende no app, no telefone.

A Calling API é cobrada como as mensagens?

Não. A página de preços da Meta diz que a Calling API tem preços diferentes e remete a um documento separado de preços de chamadas, então as cobranças de chamadas não aparecem no objeto pricing dos status de mensagens.

Dá para gravar ou transcrever uma chamada da Calling API?

Sim, quando a gravação ou a transcrição está ativada. Depois da chamada, a Meta envia call_recording_available com um id de mídia de áudio ou call_transcription_available com um id de documento JSON, geralmente em até um minuto.

O webhook de chamadas pode ir para um endpoint diferente do endpoint do app?

Sim. calls é um dos campos que a Meta permite direcionar, por conta do WhatsApp Business (WABA) ou por número de telefone, para uma URL de callback alternativa, junto com messages e os campos de Coexistência.

Continue lendo

Pronto para começar?

Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.

Começar teste grátis

Verificado em