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

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, com digit.
  • recording: a gravação está disponível, com url e files.
  • ended: a ligação acabou, com reason (remote-hangup, hangup, false-answer, setup-failed, terminate).
  • error: falha, com code e msg.

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.

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.