ligações de saída
Fazer ligações de WhatsApp pela API, com áudio gravado ou conversa ao vivo
Para fazer ligações de WhatsApp pela API, o seu SaaS chama um endpoint e a chamada sai do número do seu cliente, tocando um áudio pronto ou abrindo a conversa ao vivo no navegador, sem custo por ligação.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Dois modos de saída
/calls/place toca um áudio ou silêncio; /calls/stream abre a conversa ao vivo por WebSocket ou WebRTC.
Resposta imediata
A API devolve o callId na hora. Toque, atendimento e fim chegam depois, como eventos call.* no seu webhook.
Não atendida é um evento
call.not_answered separa quem não atendeu de quem atendeu e desligou, sem você interpretar motivo.
Gravação em três faixas
No modo stream, a chamada atendida gera WAV mono de 16 kHz: mixagem, lado da sessão e lado do contato.
Fazer ligações de WhatsApp pela API coloca o botão “ligar” dentro do seu produto. O atendente do helpdesk retorna o cliente sem pegar o celular, o sistema de cobrança liga no dia do vencimento e a clínica confirma a consulta da tarde, tudo saindo do número de WhatsApp que o seu cliente já usa e que o contato já conhece. Na D-API, essas ligações estão incluídas na conexão não-oficial, sem custo por chamada.
Há dois jeitos de ligar, e escolher o certo poupa trabalho. Esta página mostra quando usar cada um, como acompanhar o resultado e o que controlar durante a chamada. A visão geral do recurso está em ligações WhatsApp API.
Dois modos para fazer ligações de WhatsApp
POST /api/v1/calls/place |
POST /api/v1/calls/stream |
|
|---|---|---|
| Quem fala | Um áudio pronto, ou silêncio | Uma pessoa no navegador ou um agente no servidor |
| Áudio de volta para você | Opcional, em pedaços pelo webhook | Ao vivo, pelo WebSocket da chamada |
| Gravação | Sem arquivo de gravação | Grava por padrão (dá para desligar) |
| Resposta | callId |
callId e wsUrl |
| Caso típico | Aviso, lembrete, confirmação | Atendimento, venda, agente de IA |
Ligação com áudio pronto: /calls/place
É o modo para quando ninguém precisa estar na linha. O sistema de cobrança liga e toca “Olá, a sua mensalidade vence hoje, o boleto está na conversa”. O campo audioSource escolhe o que a chamada envia: vazio ou silence para silêncio (o padrão), uma URL https:// com o áudio, ou o áudio embutido em base64 (base64:... ou um data URI data:audio/...;base64,...). Caminhos de arquivo local são recusados.
curl -X POST https://api.d-api.cloud/api/v1/calls/place \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "minha-sessao",
"phone": "5511999999999",
"audioSource": "https://seu-dominio.com/audios/vencimento-hoje.wav",
"durationSeconds": 60
}'
O durationSeconds define o teto para a chamada desligar sozinha. A resposta volta imediatamente com o callId no estado calling; o andamento chega por webhook. Se você quiser ouvir o que o contato disse, envie "recordAudio": true: o áudio da outra ponta chega como eventos call.audio em pedaços de cerca de 1 segundo, PCM s16le em base64, ordenados por seq. São cerca de um evento por segundo por chamada, então ligue só se for consumir.
Ligação ao vivo: /calls/stream
É o modo para conversa. A resposta traz uma wsUrl de uso único que transporta o áudio nos dois sentidos: o microfone do atendente vai para o contato e a voz do contato volta para o alto-falante, em PCM de 16 kHz ou por WebRTC com o SDK.
curl -X POST https://api.d-api.cloud/api/v1/calls/stream \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "sessionId": "minha-sessao", "phone": "5551999998888" }'
{
"success": true,
"sessionId": "minha-sessao",
"callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"wsUrl": "wss://api.d-api.cloud/voip/stream?callId=a1b2c3d4-...&token=...",
"token": "..."
}
O token embutido na wsUrl é exclusivo daquela chamada e deixa de valer quando ela termina. Por isso o desenho seguro é o seu backend chamar o endpoint com a API key e entregar ao navegador só a wsUrl. O protocolo do socket está em stream de áudio da ligação de WhatsApp, e a forma recomendada de usá-lo no navegador, em ligação de WhatsApp com WebRTC.
Acompanhe o resultado de cada ligação
Ligar é metade do trabalho; o seu cliente quer saber quem atendeu. Os eventos de saída chegam no webhook da sessão nesta ordem:
call.ringing, emitido assim que a chamada é discada, com estadoringing.call.connected, estadoactive, quando o contato atende.call.ended, estadoidle, com oreasondo encerramento. Só para chamadas atendidas.
Uma chamada que tocou e ninguém atendeu gera call.not_answered no lugar do call.ended, com reason: "no_answer". Isso deixa a taxa de atendimento a uma contagem de eventos, sem parse de motivo. Todos os eventos trazem phone, o telefone do contato só com dígitos, que é o campo certo para casar com o cadastro. Os campos from e callCreator indicam quem iniciou a chamada e, numa ligação feita pela sessão, trazem o número da própria sessão.
Um exemplo de uso em software de agendamento: a confirmação liga às 10h; quem gera call.connected vira “confirmado por voz”, quem gera call.not_answered recebe uma mensagem de texto com botões em seguida. A lista completa de campos está em webhook de chamadas do WhatsApp.
Controle a chamada em andamento
Pela API HTTP, o seu backend age sobre a ligação ativa:
POST /api/v1/calls/mutecommuted: trueoufalsesilencia ou reativa o áudio enviado.POST /api/v1/calls/enddesliga, comreasonopcional. Ocall.endedvem depois.POST /api/v1/calls/statedevolve o estado atual:idle,starting,calling,ringing,active,ending, entre outros.
Com uma ligação só na conexão, o callId é opcional nessas rotas. Com mais de uma ativa, ele passa a ser obrigatório, e sem ele a API responde callId is required: N calls active em vez de agir na chamada errada. Guarde o callId retornado junto do atendimento no seu banco.
No modo stream, o socket também controla a chamada: fechá-lo desliga, e enviar { "type": "hangup" } ou { "type": "mute", "muted": true } tem o mesmo efeito das rotas HTTP.
Gravação e histórico
No modo stream, a chamada atendida é gravada por padrão. Perto do fim, o socket recebe o evento recording e o webhook recebe call.audio com três arquivos WAV mono de 16 kHz: full (mixagem), sender (o lado da sessão) e recipient (o contato), além de durationMs. Chamadas não atendidas não geram gravação.
Para não gravar uma ligação, envie "record": false no /calls/stream; o áudio é descartado e não há evento de gravação. Para consultar depois, GET /api/v1/calls lista as chamadas gravadas com paginação de até 100 por página e filtros por sessionId, phone e recordingStatus (uploaded, empty, failed). GET /api/v1/calls/{callId} traz os metadados e a transcrição, quando disponível.
Quando o contato prefere escolher a hora
Nem toda ligação precisa ser agora. Para a consultoria que agenda uma conversa ou a escola que marca reunião com o responsável, um link de chamada do WhatsApp ou um convite com horário pode funcionar melhor que tocar o telefone de surpresa. Esse fluxo está em link de ligação do WhatsApp. E se a régua precisa ligar para milhares de pessoas, inclusive sem WhatsApp, o artigo sobre URA e disparo de voz por API mostra o outro produto.
Os parâmetros completos de cada endpoint estão na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
Em que formato vai o número de destino?
Com DDI e DDD, só dígitos, como 5511999999999. Os dois endpoints de saída também aceitam o campo identifier no lugar de phone; um dos dois é obrigatório, e sem nenhum a API responde 400.
Posso ligar para vários contatos ao mesmo tempo pelo mesmo número?
Cada conexão tem 1 canal de voz incluso, então faz uma ligação por vez. Com canais extras, até 5 no total por conexão, cada ligação é independente e identificada pelo próprio callId. Com todos ocupados, a API responde a call is already in progress.
Para disparar voz em massa, este é o caminho?
Para milhares de contatos com mensagem gravada, inclusive números sem WhatsApp, o produto de URA e disparo de voz é mais adequado. As ligações de WhatsApp servem melhor a chamadas individuais no número da sessão.
Como desligo uma chamada pelo backend?
POST /api/v1/calls/end com sessionId e, quando houver mais de uma ligação ativa, o callId. O comando só dispara o desligamento; o evento call.ended chega depois, de forma assíncrona.