Pular para o conteúdo
D-APITestar grátis

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:

  1. call.ringing, emitido assim que a chamada é discada, com estado ringing.
  2. call.connected, estado active, quando o contato atende.
  3. call.ended, estado idle, com o reason do 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/mute com muted: true ou false silencia ou reativa o áudio enviado.
  • POST /api/v1/calls/end desliga, com reason opcional. O call.ended vem depois.
  • POST /api/v1/calls/state devolve 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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.