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:- Uma chave de API da conta YCloud. Envie-a no cabeçalho
X-API-Key. Consulte Autenticação. - Uma conta do WhatsApp Business e um número de telefone comercial registrado na YCloud.
- Calling habilitado para esse número de telefone.
- Uma implementação de áudio WebRTC capaz de criar e aplicar ofertas e respostas SDP.
- Um endpoint de webhook da YCloud inscrito nos eventos de Calling utilizados pela sua integração. Consulte Configurar webhooks.
- Permissão de chamada do usuário quando for necessária para uma chamada iniciada pela empresa.
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
UseGET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings para verificar se o Calling está habilitado e se o ícone de Calling está visível:
type, a YCloud retornará a resposta de configurações de Calling.
Habilitar o Calling
Salve as configurações de Calling comPOST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings antes de começar a aceitar ou realizar chamadas:
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:
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
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
Assinewhatsapp.call.connect. Um evento iniciado pelo usuário tem direction definido como USER_INITIATED e inclui uma oferta SDP offer.
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
3. Aceitar a chamada
Quando o agente atender, envie os mesmosphoneId, wacid, tipo de SDP e resposta SDP para o endpoint de aceite.
Endpoint: POST /whatsapp/calls/accept
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
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: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:
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.
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 enviawhatsapp.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
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:
Baixar um recurso disponível
Chame o endpoint de mídia somente depois que o evento correspondente reportarAVAILABLE.
Endpoint: GET /whatsapp/calls/media/{mediaAssetId}
.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:- Preserve o corpo bruto da requisição e verifique
YCloud-Signatureantes de confiar no evento. - Persista o evento ou enfileire o trabalho durável.
- Retorne uma resposta
2xxde êxito imediatamente. - Faça a desduplicação pelo identificador
idde nível superior do evento. - Correlacione os dados da chamada por
wacid; mantenha ophoneIdcom eles para operações posteriores. - Processe eventos relacionados que cheguem com pequeno intervalo de tempo e tolere a reentrega.
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
successda API como aceitação da operação, não como o resultado final da chamada. - Use
preAcceptapenas como preparação; chameacceptpara atender. - Finalize as chamadas a partir de
whatsapp.call.terminate. - Baixe mídias capturadas somente após um evento
AVAILABLEe 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.

