ligação telefônica por api
Ligação telefônica por API: do evento no seu sistema ao telefone tocando
Com uma ligação telefônica por API, o seu SaaS liga para celular ou fixo quando algo acontece no produto, toca um aviso ou abre a conversa ao vivo, e recebe o resultado por webhook na mesma conta do WhatsApp e do SMS.
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
Ligação disparada por evento
POST /api/v1/voice/call liga para um número com um áudio ou um fluxo de URA e devolve o callId na hora.
Conversa em tempo real
POST /api/v1/voice/live/start disca e entrega uma wsUrl com o áudio da ligação nos dois sentidos.
Gravação inclusa no modo ao vivo
Toda ligação ao vivo atendida é gravada em WAV, com a mixagem e cada lado separado.
Chave fora do navegador
A wsUrl carrega um token exclusivo da ligação, que perde a validade quando ela termina.
Fazer uma ligação telefônica por API significa que o telefone do cliente final toca porque o seu sistema decidiu, e não porque alguém pegou o fone. No seu SaaS, isso pode ser um lembrete que liga 2 horas antes da consulta, um botão “ligar” na ficha do lead ou um agente de IA que retorna um pedido de orçamento. Na D-API, a ligação telefônica por API sai pela rede de telefonia, alcança celular e fixo e não precisa de conexão de WhatsApp: basta a API key da conta e saldo na carteira.
Há dois endpoints para ligações individuais, e eles servem a objetivos diferentes. Esta página explica quando usar cada um e o que o seu backend precisa tratar. Campanhas para listas estão em disparo de voz em massa.
Quando cada endpoint faz sentido
| Situação no seu produto | Endpoint | O que o seu sistema faz depois |
|---|---|---|
| Aviso gravado ou menu por tecla para um número | POST /api/v1/voice/call |
Espera os webhooks de atendimento, tecla e encerramento |
| Atendente falando pelo navegador | POST /api/v1/voice/live/start |
Entrega a wsUrl ao navegador e toca o áudio |
| Robô ou agente de IA conversando | POST /api/v1/voice/live/start |
Abre a wsUrl no servidor e troca áudio PCM |
O /voice/call é assíncrono: você dispara e acompanha pelo webhook. O /voice/live/start é síncrono no áudio: o seu sistema precisa estar presente durante a ligação, porque é ele que fala.
Ligação única com /api/v1/voice/call
O corpo pede to e um conteúdo: audioUrl para tocar um arquivo ou flowId para executar um fluxo de URA do builder do painel. Os opcionais são name (rótulo para auditoria), audioSecs (duração do áudio, usada para reservar saldo), maxAttempts (novas tentativas em falha técnica) e from (número exibido, quando a rota permite).
Um caso de clínica: o sistema de agendamento dispara a confirmação por tecla quando falta um dia para a consulta.
curl -X POST https://api.d-api.cloud/api/v1/voice/call \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511999999999",
"flowId": "FLOW_CONFIRMACAO_CONSULTA",
"name": "clinica-33-consulta-55120"
}'
A resposta traz success: true e o callId. Esse valor volta como callId em call.started, call.answered, cada call.dtmf e call.ended, então é ele que liga a ligação à consulta no seu banco. Os erros têm códigos estáveis: AUDIO_OR_FLOW_REQUIRED e AUDIO_AND_FLOW_EXCLUSIVE (HTTP 400) para conteúdo ausente ou duplicado, FLOW_NOT_FOUND (404) para fluxo de outra conta, insufficient_balance (402) sem saldo e 502 quando a rede recusa a discagem, com a reserva devolvida.
Ligação ao vivo com /api/v1/voice/live/start
O modo ao vivo é o que permite conversa. O corpo pede só o to, com DDI e apenas dígitos. A D-API reserva saldo, disca e responde com três campos: callId, wsUrl e token. O telefone já está tocando quando a resposta chega, e o seu sistema tem até 30 segundos para abrir a wsUrl; se não abrir, a ligação é desligada e a reserva volta para o saldo.
O padrão recomendado é iniciar pelo backend e entregar ao navegador só o que ele precisa:
app.post("/api/ligar", async (req, res) => {
const r = await fetch("https://api.d-api.cloud/api/v1/voice/live/start", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: process.env.DAPI_API_KEY,
},
body: JSON.stringify({ to: req.body.to }),
});
const data = await r.json();
if (!data.success) return res.status(r.status).json(data);
res.json({ callId: data.callId, wsUrl: data.wsUrl });
});
O token embutido na wsUrl é exclusivo daquela ligação e deixa de valer quando ela termina. Mesmo assim, trate a URL como segredo de curta duração e não registre em log. Antes de chamar a rota, autentique o usuário do seu SaaS: a ligação é cobrada da carteira da conta.
O que trafega no WebSocket
Frames binários são áudio PCM s16le, 16 kHz, mono, em frames de 20 ms (640 bytes), nos dois sentidos. Frames de texto são eventos JSON com type:
accepted: o telefone atendeu. A partir daqui o áudio enviado chega à pessoa e a cobrança começa.dtmf: uma tecla foi pressionada, comdigit.recording: a gravação está disponível, comurlefiles.ended: a ligação acabou, comreason(remote-hangup,hangup,false-answer,setup-failed,terminate).error: falha, comcodeemsg.
Diferente da ligação de WhatsApp, a telefonia não emite calling nem ringing. Entre a resposta do /live/start e o accepted, o telefone está tocando, e uma ligação que termina sem accepted não foi atendida. Para desligar, feche o WebSocket ou envie { "type": "hangup" }. O mudo é do seu lado: pare de enviar frames.
Se a rede do usuário oscila, adicione &resume=1 à wsUrl. Uma queda do socket deixa de derrubar a ligação, que espera até 20 segundos pela reconexão com a mesma URL, com o tempo correndo normalmente.
Gravação, cobrança e encerramento
Toda ligação ao vivo atendida é gravada em WAV mono de 16 kHz, em três arquivos: full (mixagem), sender (o seu lado) e recipient (o telefone). Os links chegam no evento recording, no webhook call.audio e ficam disponíveis em GET /api/v1/calls/{callId}. Para um CRM, isso significa anexar a gravação à ficha do lead sem storage próprio no caminho crítico.
A cobrança é pelo tempo de ligação, com o saldo da carteira. O tempo conta do accepted até o fim. Ligação não atendida e falso atendimento (false-answer, quando a operadora “atende” mas o áudio nunca chega ao aparelho) não são cobrados. Na ligação ao vivo, o call.ended do webhook traz answered e talkSeconds com os valores efetivamente cobrados, e o motivo do encerramento vem pelo reason do WebSocket.
Exemplos de produto
Alguns jeitos de usar a ligação telefônica por API em SaaS:
- CRM de vendas: botão de clique para ligar na ficha do contato, com o vendedor falando pelo navegador e a gravação salva no histórico. O passo a passo está em URA no navegador com WebRTC.
- Plataforma de atendimento: retorno automático para quem pediu “me liga” no chat, conduzido por um agente de voz com IA para telefone.
- Software de cobrança: ligação única com fluxo de URA quando uma promessa de pagamento vence sem baixa, com a tecla 1 gerando a segunda via.
- Sistema de delivery: aviso gravado para o cliente quando o entregador não encontra o endereço.
O mesmo código para telefone e WhatsApp
O contrato do WebSocket da URA ao vivo é o mesmo das ligações de WhatsApp por stream: mesmo formato de áudio, mesma URL opaca, mesmos eventos de ciclo de vida, com a diferença de calling e ringing. Se o seu produto já integra o stream de áudio da ligação de WhatsApp, a ligação telefônica reaproveita o player, o microfone e o pipeline de IA. No SDK Node, dapi.voice.live({ to }) disca e devolve o mesmo objeto de ligação usado no WhatsApp.
Os eventos call.* que o seu backend recebe estão descritos em webhook de URA. O protocolo completo, com conversões de áudio e diagnóstico de problemas de som, está 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, como 5511999999999. Na ligação única o sinal de mais é opcional, e um celular brasileiro sem o nono dígito recebe o 9 antes da discagem. No modo ao vivo, envie apenas dígitos.
Consigo escolher o número que aparece para quem recebe?
Na ligação única existe o campo from, que define o número exibido quando a rota de saída permite fixá-lo. O modo ao vivo não tem esse campo.
Quanto tempo pode durar uma ligação ao vivo?
Até 3.600 segundos, ou menos se o saldo da carteira cobrir menos tempo. Quando o tempo reservado acaba, a ligação é desligada com o motivo hangup.
Onde encontro a gravação depois que a ligação acaba?
No evento recording do WebSocket, no webhook call.audio e depois em GET /api/v1/calls/{callId}. Contas com armazenamento de mídia desativado não têm gravação.
O que acontece se a operadora recusar a ligação?
A API responde HTTP 502 e a reserva de saldo é devolvida. Sem saldo para iniciar, a resposta é HTTP 402 com o código insufficient_balance.