Saltar para o conteúdo principal

O que é

A API WhatsApp Calling da YCloud gerencia a sinalização de chamadas de voz entre um usuário do WhatsApp e um número de telefone comercial. Seu aplicativo troca SDP por meio da YCloud, enquanto sua implementação WebRTC gerencia a conexão de áudio. As chamadas podem ser iniciadas em qualquer direção:
  • Iniciadas pelo usuário: Um usuário do WhatsApp liga para sua empresa. Seu aplicativo recebe uma oferta e aceita ou rejeita a chamada.
  • Iniciadas pela empresa: Seu aplicativo cria uma oferta e solicita que a YCloud ligue para um usuário do WhatsApp.
A Calling API gerencia a sinalização de chamadas, não a pilha de mídia WebRTC. Seu aplicativo é responsável pela configuração da conexão ponto a ponto, captura e reprodução de áudio, geração de SDP e liberação de recursos do WebRTC.

Mapa da API

As APIs de chamadas e os eventos de webhook seguem o mesmo ciclo de vida, mas não formam uma sequência única que se aplica a todas as chamadas. Conclua a configuração compartilhada e, em seguida, siga o fluxo iniciado pelo usuário ou iniciado pela empresa. Use o ID da chamada, wacid, para correlacionar cada operação e evento.

Configuração compartilhada

Chamadas iniciadas pelo usuário

Chamadas iniciadas pela empresa

Conclusão de chamada compartilhada

Processamento de mídia opcional

Estas tabelas descrevem o fluxo de trabalho do aplicativo. Elas não garantem que os webhooks serão entregues na mesma ordem das linhas. Correlacione eventos por wacid e gerencie reentregas de forma idempotente.

Antes de começar

Antes de fazer uma solicitação de Calling, prepare o seguinte:
  1. Uma chave de API da conta YCloud. Envie-a no cabeçalho X-API-Key. Consulte Autenticação.
  2. Uma conta do WhatsApp Business e um número de telefone comercial registrado na YCloud.
  3. Calling habilitado para esse número de telefone.
  4. Uma implementação de áudio WebRTC capaz de criar e aplicar ofertas e respostas SDP.
  5. Um endpoint de webhook da YCloud inscrito nos eventos de Calling utilizados pela sua integração. Consulte Configurar webhooks.
  6. Permissão de chamada do usuário quando for necessária para uma chamada iniciada pela empresa.
Entre em contato com seu representante da YCloud para habilitar o acesso à API Calling. Para elegibilidade de saída, siga os requisitos atuais de Calling, incluindo o nível de mensagens de 2.000 clientes do Portfólio Empresarial e os países de números comerciais suportados. O limite anterior de 1.000 conversas foi substituído pelos requisitos atuais. Os exemplos abaixo usam estas variáveis de ambiente:
Mantenha a chave de API no seu servidor. Não a inclua no código de aplicativos móveis ou de navegador.

Como funciona

Comece configurando o número de telefone comercial. Em seguida, troque SDP de acordo com a direção da chamada. As respostas da API confirmam operações individuais de sinalização, enquanto os eventos de webhook relatam mudanças de estado e o resultado final. Se a captura estiver habilitada, eventos separados indicarão quando uma gravação ou transcrição estiver pronta para download.

Requisição

Configurar o número de telefone comercial

As configurações de chamada e captura pertencem a um número de telefone comercial específico do WhatsApp. Configure-as antes de processar chamadas.

Ler configurações de Calling

Use GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings para verificar se o Calling está habilitado e se o ícone de Calling está visível:
Se você omitir type, a YCloud retornará a resposta de configurações de Calling.

Habilitar o Calling

Salve as configurações de Calling com POST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings antes de começar a aceitar ou realizar chamadas:
A resposta contém o objeto calling salvo. Antes de processar chamadas em tempo real, conclua a configuração dos seus webhooks e sessões WebRTC.

Configurar gravação e transcrição

As configurações de captura se aplicam a novas chamadas originadas pela API. Você pode habilitar a gravação, a transcrição ou ambas.
Para ler as configurações de captura, use type=capture:
Você pode incluir calling e capture na mesma requisição POST. Após validar o acesso ao número de telefone, a YCloud tenta salvar cada seção de forma independente. Se um dos salvamentos falhar, a outra seção já pode ter sido armazenada. Leia ambas as configurações após um erro e tente novamente apenas a seção que ainda precisa de atualização.

Processar uma chamada iniciada pelo usuário

Sequência de Calling iniciada pelo usuário Em uma chamada iniciada pelo usuário, o WhatsApp envia a oferta SDP. Sua aplicação responde a essa oferta e, em seguida, aceita ou rejeita a chamada.

1. Receber o evento de conexão

Assine whatsapp.call.connect. Um evento iniciado pelo usuário tem direction definido como USER_INITIATED e inclui uma oferta SDP offer.
Armazene callingConnect.wacid e callingConnect.phoneId juntos. Aplique a oferta SDP recebida à sua conexão peer WebRTC e crie uma resposta SDP.

2. Fazer o pré-aceite da chamada

Chame o pré-aceite após criar uma resposta SDP, mas antes que o atendente aceite a chamada. Isso prepara o caminho de mídia e pode reduzir cortes de áudio quando a chamada for atendida. Endpoint: POST /whatsapp/calls/preAccept
Após o pré-aceite ser bem-sucedido, mantenha a chamada em estado de chamada tocando ou pronta. O pré-aceite não atende a chamada para o usuário.

3. Aceitar a chamada

Quando o agente atender, envie os mesmos phoneId, wacid, tipo de SDP e resposta SDP para o endpoint de aceite. Endpoint: POST /whatsapp/calls/accept
Os campos da requisição e o formato da resposta são os mesmos do pré-aceite. Após uma resposta bem-sucedida, use o estado da conexão WebRTC para prontidão de mídia e aguarde whatsapp.call.terminate para obter o resultado final da chamada. A janela documentada de aceite de entrada é de aproximadamente 30 a 60 segundos após o webhook de conexão. Aceite prontamente; uma chamada não atendida é encerrada do lado do usuário com uma notificação de Not Answered e um webhook de encerramento. Mesmo que a conexão WebRTC já esteja estabelecida, inicie o áudio somente depois que a solicitação de aceite retornar HTTP 200. Iniciar antes pode cortar as primeiras palavras; iniciar tarde demais causa silêncio.

Rejeitar em vez de aceitar

Se o agente não puder atender a chamada de entrada, rejeite-a em vez de criar uma sessão ativa. Endpoint: POST /whatsapp/calls/reject
A resposta usa a resposta padrão de Calling. Libere a conexão peer local após a solicitação e ainda assim aceite um evento posterior de encerramento para este wacid, caso algum chegue.

Iniciar uma chamada iniciada pela empresa

Em uma chamada iniciada pela empresa, sua aplicação cria a oferta SDP e a envia para a YCloud.

Obter permissão de chamada

Antes de iniciar uma chamada, obtenha a permissão de chamada do usuário. Uma solicitação interativa de permissão pode ser enviada dentro de uma janela de atendimento ao cliente qualificada:
Envie este corpo para POST /v2/whatsapp/messages/sendDirectly ou enfileire-o com POST /v2/whatsapp/messages. Você também pode criar um modelo de permissão de chamada. Por exemplo, envie este corpo para POST /v2/whatsapp/templates e aguarde a aprovação:
Envie o modelo aprovado com seu parâmetro de corpo:
Quando callback_permission_status estiver ativado nas configurações de chamada do número de telefone, uma chamada iniciada pelo usuário pode conceder permissão de retorno de chamada. O usuário também pode conceder permissão de chamada permanente a partir do perfil comercial. As respostas de permissão chegam como eventos whatsapp.inbound_message.received. Inspecione o objeto interactive.call_permission_reply, não apenas se a mensagem de solicitação de permissão foi entregue:
Não inicie a chamada após uma rejeição ou uma permissão expirada. O erro 138006 da Meta significa que o número comercial não possui a permissão de chamada necessária. Para obter detalhes sobre erros do provedor, consulte os erros de Calling da Meta.

1. Criar uma oferta SDP

Crie uma conexão peer WebRTC local e anexe a faixa de áudio. Gere a oferta SDP, defina-a como a descrição local e aguarde a conclusão dessa operação antes de enviar a oferta para a YCloud.

2. Conectar a chamada

Endpoint: POST /whatsapp/calls/connect Forneça pelo menos um dentre to ou recipient. Se você enviar ambos, a YCloud usará to e ignorará recipient.
Armazene o wacid retornado imediatamente. success: true significa que a operação de conexão foi aceita; não significa que o usuário atendeu.

3. Aplicar a resposta e acompanhar a tentativa

A YCloud envia whatsapp.call.connect para a chamada. Para uma chamada iniciada pela empresa, o evento tem direction: BUSINESS_INITIATED e traz o SDP remoto answer. Aplique essa resposta (answer) como a descrição remota para a mesma conexão de pares (peer connection). Inscreva-se em whatsapp.call.status.updated para acompanhar a tentativa:
Torne o processamento de eventos idempotente para que uma nova entrega não repita ações de atendentes, cobranças ou rotinas de limpeza.

Encerrar uma chamada ativa

Chame terminate quando a sua aplicação precisar encerrar uma chamada ativa, seja de entrada ou de saída. Endpoint: POST /whatsapp/calls/terminate
Os campos da requisição coincidem com os da requisição reject. Uma resposta com êxito confirma que a YCloud processou a operação terminate. Mantenha o registro da chamada aberto até receber o evento final de encerramento ou até que a sua própria política de recuperação o feche.

Resposta

Todos os cinco endpoints de sinalização retornam o mesmo formato de resposta:
wacid identifica a chamada associada à operação. success: true confirma que a operação de sinalização foi bem-sucedida; isso não confirma que o outro participante atendeu ou que a chamada foi concluída. Use o estado do WebRTC e os eventos de webhook de chamadas (Calling) para esses resultados.

Processar o evento final da chamada

whatsapp.call.terminate é o evento terminal do ciclo de vida de uma chamada.
Ao receber este evento, finalize o registro da chamada e libere os recursos restantes de WebRTC. Uma resposta anterior da API não confirma que a chamada foi concluída.

Receber gravações e transcrições

Quando a captura está habilitada, o processamento de mídia continua após o ciclo de vida da chamada. A gravação e a transcrição têm eventos terminais separados: O exemplo a seguir mostra uma gravação disponível:
Ambas as propriedades do payload utilizam os mesmos campos:

Baixar um recurso disponível

Chame o endpoint de mídia somente depois que o evento correspondente reportar AVAILABLE. Endpoint: GET /whatsapp/calls/media/{mediaAssetId}
O endpoint retorna o arquivo completo como anexo e não oferece suporte a downloads por intervalo de bytes (byte-range). As gravações usam .ogg; as transcrições usam .json. Apenas o locatário proprietário da YCloud pode baixar um recurso. Um recurso permanece disponível por 30 dias a partir da sua criação. Recursos ausentes, indisponíveis, expirados ou que pertençam a outro locatário retornam HTTP 404.

Criar um receptor de webhook confiável

Inscreva o seu endpoint nos eventos de que a sua integração precisa:
Para cada requisição:
  1. Preserve o corpo bruto da requisição e verifique YCloud-Signature antes de confiar no evento.
  2. Persista o evento ou enfileire o trabalho durável.
  3. Retorne uma resposta 2xx de êxito imediatamente.
  4. Faça a desduplicação pelo identificador id de nível superior do evento.
  5. Correlacione os dados da chamada por wacid; mantenha o phoneId com eles para operações posteriores.
  6. Processe eventos relacionados que cheguem com pequeno intervalo de tempo e tolere a reentrega.
Consulte Configurar webhooks para saber mais sobre criação de endpoints, validação de assinatura e comportamento de entrega. A página Exemplos de payload de webhook contém os exemplos gerados completos.

Tratar erros e recuperação

Os endpoints de Calling usam a resposta de erro padrão da API da YCloud. Consulte Tratar erros para ver a estrutura de resposta e as orientações para novas tentativas. Use estas verificações para falhas comuns de Calling: Um tempo limite (timeout) de solicitação não comprova que a ação de sinalização falhou. Antes de tentar novamente, reconcilie a solicitação com os eventos de webhook e o estado local atual da chamada. A ação pode já ter alcançado o WhatsApp.

Lista de verificação de integração

  • Ative Calling no número de telefone comercial correto.
  • Configure e teste todas as assinaturas de webhook de Calling necessárias.
  • Verifique as assinaturas de webhook e elimine a duplicidade de eventos.
  • Armazene wacid, phoneId, direção e o estado atual juntos.
  • Trate o success da API como aceitação da operação, não como o resultado final da chamada.
  • Use preAccept apenas como preparação; chame accept para atender.
  • Finalize as chamadas a partir de whatsapp.call.terminate.
  • Baixe mídias capturadas somente após um evento AVAILABLE e dentro do prazo de 30 dias.
  • Libere os recursos de WebRTC em caso de rejeição, encerramento, falha e tempo limite (timeout) local.
  • Evite registrar chaves de API, SDP completo ou identificadores de participantes nos logs gerais da aplicação.

Referência da API de Calling

Examine os esquemas exatos de solicitação e resposta de cada endpoint de Calling.

Exemplos de payload de webhook

Inspecione os exemplos completos de eventos de Calling gerados a partir da especificação do webhook.