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

voz e sms

API de ligações WhatsApp para fazer e receber chamadas

Use a API de ligações WhatsApp para fazer e receber chamadas de voz no seu SaaS, com áudio em tempo real e gravação, sem custo extra na API não-oficial.

Time D-API. Atualizado em .7 min de leitura.

Uma API de ligações WhatsApp coloca a chamada de voz dentro do seu produto. A clínica confirma a consulta ligando direto do painel de agenda, o atendente do seu CRM atende o cliente no navegador e o seu agente de IA conversa por voz com quem ligou. Tudo usando o número de WhatsApp que o seu cliente já tem, com o contato atendendo no aplicativo que ele já usa.

Na D-API, fazer e receber ligações está incluído na conexão da API não-oficial, sem custo extra por chamada. O seu SaaS paga a conexão, e voz passa a ser mais uma funcionalidade que você oferece aos seus clientes.

Este guia mostra como cada fluxo funciona com os endpoints reais: ligação de saída com e sem áudio ao vivo, recebimento de chamadas em tempo real, gravação, histórico e os eventos de webhook que fecham o ciclo.

Três jeitos de usar voz no seu SaaS

Antes do código, vale separar os cenários, porque cada um usa uma combinação diferente de endpoints.

Ligação de saída disparada pelo sistema. O seu produto inicia a chamada e acompanha o andamento pelos eventos call.*. Serve para lembrete, confirmação e retorno de atendimento. O endpoint é POST /api/v1/calls/place.

Ligação ao vivo com áudio no seu app. O seu usuário fala pelo microfone do navegador, ou um agente de IA fala pelo servidor, e o áudio trafega nos dois sentidos por WebSocket. O endpoint é POST /api/v1/calls/stream, e a chamada é gravada.

Chamada recebida. Alguém liga para o número do seu cliente, o seu sistema é avisado no instante em que toca e decide se atende ou recusa.

Se o que você precisa é ligar para milhares de contatos com mensagem gravada ou montar uma URA, o caminho é o produto de voz, coberto no artigo sobre URA e disparo de voz por API. Aqui o assunto é a chamada de WhatsApp no número da sessão.

Fazer ligações pela API

O benefício para o seu cliente é ligar sem trocar de ferramenta: o botão “ligar” fica no seu produto, e a chamada sai pelo WhatsApp dele.

A forma mais direta é POST /api/v1/calls/place, que inicia uma chamada 1:1 e responde imediatamente com o callId no estado calling. Toque, atendimento e encerramento chegam depois como eventos de webhook.

Quando o seu produto precisa do áudio, use o modo stream. A chamada recebe a sessão e o número de destino com DDI, só dígitos:

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": "..."
}

A wsUrl já carrega a autenticação: um token próprio da chamada, nunca a sua API key. Por isso o padrão seguro é iniciar a chamada pelo seu backend, onde a API key fica, e entregar ao navegador apenas a wsUrl, tratada como segredo de curta duração.

O áudio e o ciclo de vida

No WebSocket, frames de texto são eventos e frames binários são áudio. O formato é o mesmo nos dois sentidos: PCM s16le, 16 kHz, mono, em frames de 20 ms (320 amostras, 640 bytes), enviados em cadência de tempo real. Rodar o AudioContext do navegador a 16 kHz evita reamostragem manual.

Os eventos de texto contam a história da chamada: calling, ringing, accepted (o destino atendeu e o áudio está ao vivo), recording, ended com reason (como hangup, rejected, timeout ou terminate) e error. A regra mais importante é não enviar áudio do microfone antes de accepted.

Fechar o WebSocket desliga a chamada. Para manter a ligação durante uma queda de rede, acrescente &resume=1 à wsUrl: o servidor aguarda a reconexão por até 20 segundos e reenvia os eventos desde o início. Pela API HTTP, você também controla a chamada ativa com POST /api/v1/calls/mute, POST /api/v1/calls/end e POST /api/v1/calls/state, que devolve o estado atual (calling, ringing, active e outros).

Há limites claros para planejar a capacidade: por padrão, 10 novas chamadas a cada 60 segundos por usuário (acima disso, a API responde 429) e duração máxima de 3600 segundos por chamada.

Receber ligações em tempo real

Para o seu cliente, receber pela API significa não perder a ligação que entra no WhatsApp da empresa: ela aparece no painel do seu produto, com o contato identificado, e pode ser atendida ali mesmo.

O fluxo tem quatro passos. Primeiro, ligue o recebimento na conexão, que vem desligado por padrão:

curl -X POST https://api.d-api.cloud/api/v1/sessions/minha-sessao/receive-calls-settings \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "receiveCalls": true }'

Essa configuração reinicia a conexão, que fica alguns segundos sem enviar nem receber mensagens. Faça a mudança uma vez, em janela controlada, e mantenha ligada.

Depois, abra pelo seu backend um WebSocket em wss://api.d-api.cloud/voip/events, passando a chave e a lista de sessões na query string (até 20 sessões por conexão). A oferta chega como call.offer, com callId, from e o sessionId que recebeu a chamada. Esse canal não reenvia histórico: uma oferta vale poucos segundos, então mantenha o socket aberto continuamente, com reconexão automática.

Para atender, chame POST /api/v1/calls/accept com sessionId e callId. A resposta traz uma wsUrl de mídia idêntica à do modo stream, e daí em diante o áudio funciona exatamente como na ligação de saída. Para recusar, POST /api/v1/calls/reject exige também o from, repassado exatamente como veio, inclusive quando for um LID.

Um detalhe evita um bug clássico. O evento call.accepted avisa que a chamada foi atendida fora da sua integração, no próprio aparelho ou em outro dispositivo conectado. A confirmação de que o seu sistema atendeu é a resposta HTTP de /calls/accept. Trate call.accepted, call.rejected e call.ended como “pare de tocar”.

O exemplo completo em Node, com assinatura de eventos, atendimento e conexão no WebSocket de mídia, está na documentação da D-API.

Recusar automaticamente com uma mensagem

Nem todo cliente do seu SaaS quer atender ligações. Para esses, POST /api/v1/sessions/{sessionId}/call-settings com rejectCalls e rejectCallsMessage recusa a chamada e responde com uma mensagem automática, como “Atendemos só por mensagem, pode escrever aqui”. O call.offer continua sendo entregue no webhook, então o seu produto ainda registra quem tentou ligar.

Webhooks de chamadas, gravação e histórico

Tudo o que acontece nas chamadas também chega por webhook, no mesmo envelope dos demais eventos. É a trilha server-to-server que alimenta relatórios, CRM e auditoria. Se você ainda não montou o recebimento de eventos, o artigo sobre webhook WhatsApp API cobre retentativas, timeout e deduplicação.

Os eventos de saída seguem a ordem call.ringing, call.connected e call.ended. Uma chamada que tocou e não foi atendida gera call.not_answered no lugar de call.ended, o que permite medir taxa de atendimento sem inspecionar o reason. Todos os eventos call.* trazem phone, o telefone da outra ponta só com dígitos:

{
  "event": "call.ended",
  "sessionId": "minha-sessao",
  "data": {
    "callId": "ABCD1234",
    "state": "idle",
    "reason": "hangup",
    "peerPn": "[email protected]",
    "phone": "5511999999999"
  },
  "timestamp": "2026-05-26T12:35:40.000Z"
}

Use phone para identificar o contato. 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.

Ao fim de uma chamada por stream atendida, o call.audio entrega a gravação com três faixas em WAV mono de 16 kHz: full (mixagem), sender (lado da sessão) e recipient (o contato), além de durationMs. Chamadas não atendidas não geram gravação. Para consultar depois, GET /api/v1/calls lista as chamadas gravadas com paginação (até 100 por página) e filtros por sessionId, phone e recordingStatus, e GET /api/v1/calls/{callId} retorna os metadados de gravação e a transcrição, quando disponível.

Os eventos de chamada vão apenas para o webhook D-API e para o RabbitMQ, e não são enviados para integrações de CRM. Se o seu produto depende de uma dessas integrações, consuma os eventos pelo seu próprio endpoint.

Às vezes o melhor é deixar o contato escolher a hora. POST /api/v1/calls/create-link cria um link de chamada do WhatsApp, de áudio ou vídeo, que pode ser compartilhado. E POST /api/v1/calls/send-event envia ao destinatário um convite de chamada agendada, com título e horário, usando um link do WhatsApp ou uma URL própria de outra ferramenta de reunião. Para um SaaS de agendamento, isso substitui o lembrete em texto por um convite que o paciente abre no próprio WhatsApp.

Ligações e API Oficial na mesma integração

As chamadas por API exigem uma conexão não-oficial. Para conexões da API Oficial, os endpoints de chamada respondem 400. Na prática, muitos SaaS mantêm os dois tipos no mesmo código: o cliente que precisa de voz usa uma conexão não-oficial, e o cliente que exige a API Oficial usa a Cloud API, com o mesmo preço por conexão na D-API.

Se você vai oferecer as duas opções, vale saber quanto o cliente da API Oficial paga à Meta pelas mensagens antes de montar o plano. A conta é simples: volume previsto por categoria de mensagem multiplicado pela tarifa correspondente na tabela de preços da Meta.

Por onde começar

Comece pela ligação de saída: uma conexão não-oficial de teste, um POST /api/v1/calls/stream feito pelo seu backend e a wsUrl aberta num navegador com o worklet de áudio da documentação. Com o áudio funcionando, ligue o receiveCalls em janela controlada e suba o consumidor de /voip/events com reconexão automática.

Depois, conecte os eventos call.* ao seu banco para ter histórico, taxa de atendimento e gravações por cliente. E se o próximo passo for colocar um agente de IA falando ao telefone, o artigo sobre agentes de IA no WhatsApp mostra como conectar o modelo à D-API.

Veja também: Ligações no WhatsApp, Telefonia e URA, SMS.

Perguntas frequentes

As ligações têm custo adicional?

Não. Fazer e receber ligações de WhatsApp está incluído na conexão da API não-oficial da D-API, sem custo extra por chamada.

Consigo fazer ligações por uma conexão da API Oficial?

Não pela D-API. Os endpoints de chamada exigem uma conexão não-oficial; para conexões Cloud API, rotas como /calls/accept e receive-calls-settings respondem 400.

As chamadas ficam gravadas?

As chamadas feitas por stream são gravadas quando atendidas. A gravação chega no evento call.audio com faixas full, sender e recipient em WAV mono de 16 kHz, e também pode ser consultada em GET /api/v1/calls/{callId}.

Dá para atender uma ligação no navegador do meu usuário?

Sim. O seu backend chama /calls/accept e recebe uma wsUrl de mídia. Você entrega apenas essa URL ao navegador, que troca áudio PCM pelo WebSocket. A API key nunca sai do servidor.

Existe limite de chamadas?

Sim. O padrão é de 10 novas chamadas a cada 60 segundos por usuário, e cada chamada por stream tem duração máxima de 3600 segundos.

Teste com o time técnico do seu lado

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

Leia também

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.