API de URA e disparo de voz integrada ao seu SaaS
Como usar uma API URA e disparo de voz para colocar ligações, menus por tecla e campanhas de voz dentro do produto do seu SaaS.
Time D-API. Atualizado em .9 min de leitura.
Uma API URA e disparo de voz permite que o seu SaaS ligue para o cliente final, toque uma mensagem, ofereça um menu por tecla e devolva o resultado para dentro do produto, sem que o seu time precise montar telefonia. Para quem vende agendamento, cobrança, clínicas ou delivery, isso vira uma feature nova na tela do cliente: “confirmar consultas por ligação” ou “avisar inadimplentes por voz”, com relatório de quem atendeu e o que respondeu.
O ganho para o SaaS está no controle. A ligação nasce de uma chamada HTTP e cada etapa (iniciada, atendida, tecla pressionada, encerrada) chega por webhook. Você grava o resultado no seu banco, atualiza o agendamento e decide o próximo passo sem depender de planilha exportada de outro sistema.
A seguir, como a URA e o disparo de voz funcionam por API na D-API e como tratar os eventos.
O que o seu SaaS ganha com voz dentro do produto
O primeiro ganho é atenção em momentos críticos. Uma ligação interrompe o dia de um jeito que texto raramente consegue, e isso importa numa consulta amanhã cedo ou numa fatura vencendo. Com voz ao lado de WhatsApp e SMS, o cliente do seu SaaS monta a régua completa sem sair do seu produto.
O segundo ganho é dado estruturado. A tecla que o destinatário pressiona chega como evento, e “pressione 1 para confirmar, 2 para remarcar” vira um campo no seu banco que dispara automações.
O terceiro é um fornecedor só. A D-API reúne WhatsApp (API não-oficial e API Oficial da Meta), SMS e voz, com 1.875 conexões, 4 datacenters no Brasil e 99,9% de uptime garantido em contrato: um contrato, um formato de webhook e suporte humano para todos os canais.
Três formas de iniciar uma ligação
Ligação única com /api/v1/voice/call
Serve para o caso transacional: um evento no seu sistema gera uma ligação. O obrigatório é to, mais audioUrl para tocar um áudio gravado ou flowId para executar um fluxo de URA interativo, exatamente um dos dois. A resposta traz o callId, que é o identificador que aparece em todos os webhooks dessa ligação.
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": "SEU_FLOW_ID",
"name": "confirmacao-consulta-4821",
"maxAttempts": 2
}'
O to aceita o número com ou sem + (+5511999999999 e 5511999999999 funcionam igual): a API usa só os dígitos e, se um celular brasileiro chegar sem o nono dígito, insere o 9 antes de discar. Os opcionais:
from: número exibido para quem recebe, quando a rota de saída permite fixá-lo.audioSecs: duração do áudio em segundos, no modoaudioUrl, para estimar o consumo antes de discar (sem ele, a API considera 120 segundos; o débito final usa o tempo real de conversa).maxAttempts: quantas tentativas fazer quando a ligação falha por motivo técnico. Não atendeu, ocupado e caixa postal não ganham nova tentativa.trunk: seleciona uma rota de saída específica. Na integração padrão você omite e a D-API usa a rota da conta.
Campanha de voz com /api/v1/voice/bulk
Para o cliente do seu SaaS que quer avisar uma base inteira (lembrete de vencimento, aviso de mudança de horário, pesquisa rápida por tecla), o endpoint de disparo em massa recebe a lista de destinos e devolve um bulkId. Esse mesmo valor chega como callId nos webhooks, então toda a campanha fica correlacionada por um único identificador, enquanto bulkCallId separa cada ligação individual dentro do lote.
Os destinos podem ir em numbers (lista simples de telefones) ou em recipients, em que cada item tem phone e um objeto variables para personalização. O campo scheduledAt agenda a campanha, o que encaixa bem com produtos que já têm agenda ou régua de cobrança.
{
"flowId": "SEU_FLOW_ID",
"name": "lembrete-vencimento-outubro",
"recipients": [
{ "phone": "+5511999999999", "variables": { "nome": "Ana" } },
{ "phone": "+5521988888888", "variables": { "nome": "Carlos" } }
],
"maxAttempts": 2
}
O scheduledAt recebe um timestamp ISO 8601, como 2026-10-20T13:00:00-03:00. Com data futura, a resposta volta com scheduled: true e a discagem começa no horário; sem o campo, ou com data passada, a campanha sai na hora.
As variables entram no contexto do fluxo de URA de cada ligação e ficam disponíveis nos blocos como {{input.nome}}, ao lado de {{input.phone}} e das teclas já pressionadas ({{input.lastDigit}}). Como os áudios da URA são gravações, as variáveis personalizam o que o fluxo faz durante a ligação, como um SMS ou WhatsApp de confirmação ou uma chamada HTTP para o seu backend. No modo audioUrl elas não são usadas.
Ligação ao vivo com /api/v1/voice/live/start
O terceiro endpoint serve para conversa em tempo real: um atendente no navegador ou um agente de IA de voz falando com a pessoa, em vez de um fluxo gravado. O corpo pede apenas o to, e a resposta traz callId, wsUrl e token. A D-API liga para o número e o seu sistema abre a wsUrl (WebSocket): frames binários carregam o áudio nos dois sentidos e frames de texto trazem o ciclo de vida (accepted, dtmf, recording, ended, error). Diferente do WhatsApp, a telefonia não emite calling nem ringing: até o accepted, o telefone está tocando. Fora isso, é o mesmo protocolo do stream de ligações de WhatsApp, então o código de áudio se reaproveita.
O nome Bina Inteligente vem do número exibido, escolhido automaticamente para a ligação ser mais atendida. Como a wsUrl carrega a sua API key, inicie a ligação pelo backend e entregue ao navegador só a URL.
Áudio único ou URA interativa
A escolha entre audioUrl e flowId define o tipo de experiência que o seu SaaS oferece.
Com audioUrl, a ligação toca uma mensagem e termina. Serve para avisos que só precisam ser ouvidos, como “sua entrega sai amanhã entre 8h e 12h”; o que importa é saber se a pessoa atendeu e por quanto tempo ficou na linha.
Com flowId, a ligação executa um fluxo de URA que captura dígitos via DTMF. Apenas fluxos IVR geram eventos call.dtmf, então qualquer feature do tipo “confirme pelo teclado” precisa de um flowId. Para o seu SaaS, isso abre telas como confirmação de presença, pesquisa de satisfação por nota e roteamento simples (“pressione 9 para falar com o atendimento”).
O fluxo é montado no builder de automação do painel da D-API, na categoria Voz / URA. O bloco Tocar áudio reproduz uma gravação; o Menu (DTMF) toca um áudio e transforma cada tecla em uma saída, com caminhos próprios para “Sem resposta” e “Inválido” e captura de vários dígitos com tecla de finalização; Desligar encerra a ligação. Blocos de SMS, WhatsApp, HTTP e Condição entram no meio do fluxo. O flowId é o identificador do fluxo salvo, e a API recusa com FLOW_NOT_FOUND um fluxo que não pertence à sua conta.
Webhooks: onde a ligação vira dado de produto
A URA usa um webhook de conta no canal voice, configurado uma vez no painel. Disparos em massa e ligações avulsas vão para o mesmo endpoint, e você pode restringir no painel quais eventos quer receber.
São quatro eventos no ciclo de vida da chamada:
| Evento | Quando dispara |
|---|---|
call.started |
A ligação foi iniciada |
call.answered |
A ligação foi atendida |
call.dtmf |
O destinatário pressionou uma tecla (um webhook por tecla) |
call.ended |
A ligação encerrou, com duração e código de causa |
Todos usam o mesmo envelope, com event, channel: "voice", data e timestamp. Campos que não se aplicam vêm como null, então um único tipo cobre os quatro eventos. Este é o call.ended de uma ligação atendida:
{
"event": "call.ended",
"channel": "voice",
"data": {
"callId": "...",
"bulkCallId": "...",
"to": "+5511999999999",
"answered": true,
"talkSeconds": 42,
"digits": null,
"cause": 16,
"causeDescription": "Encerramento normal",
"timestamp": "2026-01-24T23:01:02.000Z"
},
"timestamp": "2026-01-24T23:01:02.000Z"
}
Lendo o resultado com o campo cause
O cause segue os códigos Q.850 com dois códigos próprios, e o causeDescription já vem em português. Para o relatório do seu cliente, vale agrupar os códigos em poucos estados de negócio: 16 é encerramento normal, 17 é ocupado, 19 e 150 indicam que a pessoa não atendeu, 151 indica caixa postal ou secretária eletrônica, 1 e 28 apontam número inexistente ou inválido. Assim a tela de campanha mostra “atendeu”, “não atendeu”, “caixa postal” e “número ruim”.
Esse agrupamento alimenta a régua: número inválido sai da base, não atendeu ganha nova tentativa e caixa postal recebe um SMS na sequência.
Capturando teclas com call.dtmf
Cada tecla gera um webhook separado com o campo digits contendo um único caractere (0 a 9, * ou #). Para uma sequência, como um código de três dígitos, acumule os eventos por callId e bulkCallId. Para um menu simples, o primeiro call.dtmf já define a ação: confirmar, remarcar ou transferir.
Segurança e entrega
Quando há um secret configurado, cada requisição traz o header X-DAPI-Signature com o HMAC-SHA256 em hexadecimal do corpo bruto. Calcule o HMAC sobre o raw body recebido, sem re-serializar o JSON, e compare em tempo constante. A entrega usa fila durável com retentativas, circuit breaker por URL e logs, então uma instabilidade momentânea no seu endpoint não faz você perder o resultado de uma campanha.
Como pode haver retentativa, trate os eventos de forma idempotente: use a combinação de event, callId, bulkCallId e timestamp como chave para não processar o mesmo evento duas vezes. O artigo sobre webhooks da API de WhatsApp detalha esse padrão, e ele vale igual para o canal de voz. A referência completa de eventos e códigos está na documentação da D-API.
Modelando voz num SaaS multi-tenant
O webhook de voz é por conta, então quem separa os eventos por cliente é o seu sistema. O caminho mais simples é gravar, no momento do disparo, uma linha com o callId (ou bulkId), o identificador do tenant e o objeto de negócio que originou a ligação, como o agendamento ou a fatura. Quando o evento chega, um lookup por callId resolve o tenant e o registro a atualizar. Esse é o mesmo raciocínio de arquitetura multi-tenant que você já usa para WhatsApp, descrito em detalhe no artigo sobre API de WhatsApp multi-tenant.
Algumas decisões ajudam a manter o produto previsível:
- Dispare fora do request. A tela do cliente cria a campanha e responde rápido; um worker chama
/api/v1/voice/bulke grava obulkId. - Use
namecom o identificador do seu objeto. Fica fácil auditar no painel qual campanha veio de qual cliente. - Defina
maxAttemptspor tipo de aviso. A nova tentativa cobre falha técnica; para quem não atendeu, agende um segundo disparo em outro horário. - Responda o webhook rápido. Grave o evento numa fila sua e processe depois.
Voz na régua multicanal
Voz rende mais quando faz parte de uma sequência. Um padrão comum em SaaS de agendamento é enviar a confirmação por WhatsApp, ligar com URA para quem não respondeu e mandar SMS para quem não atendeu a ligação. Cada etapa usa um canal diferente da mesma D-API, e cada uma devolve o resultado por webhook no mesmo formato de envelope. Vale lembrar que as ligações de WhatsApp acontecem dentro do app de mensagens, enquanto a URA liga para a linha telefônica.
Por onde começar
Comece pelo caso de uso que o seu cliente já pede: confirmação por tecla em agendamento, aviso de vencimento em cobrança. Implemente o endpoint de webhook primeiro, com validação de assinatura e gravação idempotente, depois dispare ligações únicas com /api/v1/voice/call para validar o fluxo de ponta a ponta. Com o mapeamento de cause pronto, liberar campanhas com /api/v1/voice/bulk vira questão de tela e permissão no seu produto.
Nos 14 dias de teste que o time libera para SaaS, o grupo de onboarding acompanha do primeiro webhook à primeira campanha. Se o seu SaaS já usa a D-API para WhatsApp, a conta, a API key e o padrão de webhook são os mesmos.
Veja também: Ligações no WhatsApp, Telefonia e URA, SMS.
Perguntas frequentes
Preciso de um PABX ou operadora própria para usar URA via API?
Não. A ligação é disparada por uma chamada HTTP para a API da D-API e o ciclo de vida da chamada volta para o seu sistema por webhook. O seu SaaS só precisa expor um endpoint para receber os eventos.
Qual a diferença entre disparar com audioUrl e com flowId?
Com audioUrl a ligação toca um áudio único. Com flowId a ligação executa um fluxo de URA interativo, que captura as teclas pressionadas e gera eventos call.dtmf. Cada disparo aceita exatamente um dos dois.
Como sei se a pessoa atendeu ou caiu na caixa postal?
O evento call.answered indica atendimento. O evento call.ended traz answered, talkSeconds e um código cause com descrição em português, incluindo códigos para ocupado, não atendeu e caixa postal.
Consigo separar os eventos de voz por cliente do meu SaaS?
O webhook de voz é configurado uma vez por conta. Para separar por cliente, guarde o callId devolvido no disparo junto com o identificador do seu cliente e faça a correlação quando o evento chegar.
Voz substitui o WhatsApp nas minhas automações?
Funciona melhor como canal complementar. Use voz para avisos que precisam de atenção imediata ou confirmação por tecla, e mantenha WhatsApp e SMS para o restante da jornada, tudo no mesmo provedor.