Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

Webhooks de chamadas do WhatsApp: eventos da Calling API e chamadas num número Coexistence

O campo calls do webhook reporta eventos da Calling API do WhatsApp Business: connect com uma resposta ou oferta SDP, estados 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 Coexistence da Meta indica que as chamadas de voz e vídeo não mudam na app WhatsApp Business e não são suportadas na Cloud API, pelo que essas chamadas continuam no telemóvel.

A easyCoexistence liga o número da sua app WhatsApp Business à Cloud API da Meta através de Coexistence, para que a sua IA e as automações respondam a mensagens e enviem templates, enquanto as chamadas continuam a tocar na app no seu telemóvel.

Not supported

Chamadas de voz e vídeo na Cloud API, num número integrado com a app WhatsApp Business; na app, ficam inalteradas.

2,000

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

7 days

Durante quanto tempo as gravações e transcrições de chamadas continuam disponíveis para transferir depois de o respetivo webhook ser entregue.

wacid

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

whatsapp_business_messaging

A permissão que uma aplicação precisa para receber webhooks de chamadas, a mesma exigida para as mensagens.

Que eventos reporta o campo calls?

Tudo o que acontece a uma chamada feita ou recebida através da Calling API, num só campo, com um evento por cada fase. Uma chamada iniciada pela empresa produz um evento connect, atualizações de estado e um evento terminate. As chamadas tratadas por SIP reportam call_created em vez de connect, sem a sessão SDP. Um evento relacionado está noutro campo: quando um cliente responde a um pedido de permissão para chamadas, a resposta chega ao campo messages como 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 qualquer 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, to_user_id o BSUID do cliente, e qualquer um dos números pode estar em falta para um cliente que usa um nome de utilizador. metadata.phone_number_id identifica o seu número, como em qualquer outro campo. Este é o exemplo Call Connect da Meta, com os marcadores de posição tal como a Meta os apresenta:

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"
        }
      ]
    }
  ]
}

Que campos acrescenta o evento terminate?

terminate é o evento que a maioria dos sistemas guarda, porque fecha a chamada. Os seus campos, segundo a referência da Meta:

  • status: COMPLETED quando a chamada terminou sem erros inesperados, incluindo as chamadas não atendidas; FAILED quando não se estabeleceu ou se interrompeu.
  • start_time, end_time e duration em segundos: presentes apenas quando a outra parte atendeu.
  • errors: code, message, href e error_data.details numa chamada FAILED.
  • biz_opaque_callback_data: a sua própria cadeia de rastreio, quando a passou ao iniciar ou aceitar a chamada.

Os webhooks de chamadas funcionam num número Coexistence?

O guia Coexistence da Meta responde na sua tabela de funcionalidades: as chamadas de voz e vídeo não sofrem alterações na app WhatsApp Business e não são suportadas na Cloud API para um número integrado desta forma. Os pré-requisitos da própria Calling API dizem o mesmo do outro lado: o número da empresa tem de estar em uso com a Cloud API, e não com a app WhatsApp Business. Assim, num número Coexistence os clientes continuam a ligar como antes, a chamada toca na app no telemóvel, e o campo calls não tem nada a reportar. Uma empresa que precise de chamadas no software usa um número apenas na Cloud API.

Como se relacionam os eventos de uma mesma chamada?

Pelo ID da chamada, que começa por wacid e se repete em cada evento dessa chamada. Uma chamada iniciada pela empresa reporta connect com a resposta SDP, os estados RINGING e depois ACCEPTED ou REJECTED, e por fim terminate. Uma chamada iniciada pelo utilizador reporta connect com uma oferta SDP para o seu sistema responder, e depois terminate. Os eventos de gravação e transcrição, quando ativados, chegam depois de terminate. Guarde os eventos por id e event, já que as tentativas os repetem e a ordem de chegada não é garantida. A lista completa dos pré-requisitos da Calling API está na página sobre chamadas num número Coexistence.

O que pode a sua IA fazer com as chamadas num número Coexistence?

Trabalhar no chat, enquanto as chamadas ficam com a pessoa que está ao telefone. A easyCoexistence não subscreve o campo calls e não tem ferramentas de chamada; o conector e as automações cobrem mensagens e templates. Na prática, uma resposta da IA pode indicar ao cliente quando alguém está disponível para falar e a que número ligar, uma automação por palavra-chave pode responder a «chamada» ou «telefone» com essa informação, e o proprietário atende a chamada na app WhatsApp Business como antes.

Erros comuns

  • Subscrever as chamadas de um número Coexistence e esperar eventos. A Meta indica que as chamadas não são suportadas na Cloud API para estes números.
  • Contar com start_time e duration em todos os terminate. Só aparecem quando a chamada foi atendida; uma chamada não atendida continua a terminar como COMPLETED.
  • Procurar respostas de permissão no campo calls. Chegam ao campo messages, como mensagem interativa call_permission_reply.
  • Deixar as gravações e transcrições apenas na Meta. Ambas podem ser transferidas durante 7 dias após o respetivo webhook; depois desaparecem.
Fazer isto com a EasyCoexistence

Cada número é monitorizado 24/7, incluindo a regra dos 14 dias que desliga um número cuja app não é aberta. De US$ 9 a US$ 0.75 por número por mês, a descer à medida que adiciona números, com os primeiros 3 dias grátis.

Perguntas frequentes

Os clientes perdem o botão de chamada quando um número se liga à API através de Coexistence?

O guia Coexistence da Meta indica que as chamadas de voz e vídeo não mudam na app WhatsApp Business. Os clientes ligam para o mesmo número, e o proprietário atende na app, no telemóvel.

A Calling API tem o mesmo preço das mensagens?

Não. A página de preços da Meta indica que a Calling API tem uma tarifação diferente e remete para um documento de preços de chamadas à parte, por isso os custos das chamadas não aparecem no objeto pricing dos estados das mensagens.

Pode uma chamada da Calling API ser gravada ou transcrita?

Sim, quando a gravação ou a transcrição estão ativadas. Depois da chamada, a Meta envia call_recording_available com um media id de áudio ou call_transcription_available com um document id de JSON, normalmente em menos de um minuto.

Um webhook de chamadas pode ir para um endpoint diferente do da aplicação?

Sim. calls é um dos campos que a Meta permite encaminhar para um URL de callback alternativo, a par de messages e dos campos de Coexistence.

Continue a ler

Pronto para começar?

Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.

Começar período experimental gratuito

Verificado em