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

voz e ura por api

API de URA para colocar ligação telefônica dentro do seu SaaS

Com a API de URA da D-API, o seu SaaS liga para celular e fixo, toca um aviso, lê a tecla que a pessoa apertou ou abre uma conversa ao vivo, usando a mesma conta e a mesma API key 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
  • Três modos de ligação

    Áudio gravado, URA interativa por teclado e ligação ao vivo com áudio em tempo real, cada um num endpoint próprio.

  • Resultado volta por webhook

    Início, atendimento, cada tecla e encerramento chegam ao seu backend com código de causa em português.

  • Sem conexão de WhatsApp

    A URA sai pela linha telefônica e usa só a API key da conta e o saldo da carteira. Nada de QR code para manter.

  • Mesmo fornecedor dos outros canais

    WhatsApp não-oficial, API Oficial, SMS e voz com um contrato, um padrão de webhook e suporte humano.

Uma API de URA deixa o seu SaaS fazer o que antes exigia uma central telefônica: ligar para o cliente final, tocar uma mensagem, oferecer um menu por tecla e registrar o que aconteceu. Na D-API, essa API de URA fica na mesma conta e na mesma API key que você já usa para WhatsApp e SMS. Para quem vende software de cobrança, agendamento, clínica ou delivery, isso vira uma opção nova na tela do seu cliente, como “confirmar consulta por ligação” ou “avisar atraso por voz”, sem que o seu time precise contratar operadora, montar ramal ou aprender protocolo de telefonia.

Esta página apresenta o tema inteiro: os três jeitos de ligar, como o resultado volta para o seu sistema, como a cobrança funciona e onde a voz entra numa régua com WhatsApp e SMS. Cada parte tem uma página própria com o detalhe técnico, linkada ao longo do texto.

O que uma API de URA resolve para um SaaS

O motivo mais comum para colocar voz no produto é atenção. Uma ligação toca na hora, inclusive em celular sem internet e em telefone fixo, e por isso funciona bem nos avisos em que o atraso custa caro: a consulta de amanhã cedo, a fatura que vence hoje, a entrega que mudou de horário. Num software de cobrança, a ligação costuma ser a etapa da régua depois do WhatsApp e do SMS sem resposta. Num sistema de agendamento, é a confirmação para quem ainda não respondeu à mensagem.

O segundo motivo é dado estruturado. Quando o destinatário aperta 1 para confirmar ou 2 para remarcar, essa tecla chega ao seu backend como evento. O agendamento muda de status sozinho, e o seu cliente vê o resultado na tela que ele já usa, sem planilha exportada de outro sistema.

O terceiro é operacional. Como a URA roda na mesma conta do WhatsApp e do SMS, a autenticação, o formato de webhook e o suporte são os mesmos. O seu time integra um canal novo com o código que já tem.

Os três modos de ligação

A API de URA tem três endpoints de disparo. A escolha depende do que a ligação precisa fazer.

Modo Endpoint O que acontece na ligação Exemplo de uso
Ligação única POST /api/v1/voice/call Toca um áudio ou executa um fluxo de URA para um número Confirmação de consulta disparada por um evento
Campanha POST /api/v1/voice/bulk Mesmo áudio ou fluxo para uma lista, com agendamento opcional Aviso de vencimento para a base inteira
Ao vivo POST /api/v1/voice/live/start Abre um WebSocket com o áudio da ligação nos dois sentidos Atendente no navegador ou agente de IA

Os dois primeiros aceitam audioUrl ou flowId, exatamente um dos dois. Com audioUrl, a pessoa ouve uma gravação e a ligação termina. Com flowId, a ligação executa um fluxo de URA montado no builder do painel, com menu por tecla, caminhos para “sem resposta” e “inválido” e blocos que mandam SMS, WhatsApp ou chamam o seu backend no meio da ligação. O endpoint recusa com AUDIO_AND_FLOW_EXCLUSIVE quando os dois chegam juntos e com FLOW_NOT_FOUND quando o fluxo não pertence à conta.

Um aviso de entrega, num SaaS de delivery, cabe numa chamada só:

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",
    "audioUrl": "https://seu-cdn.com/avisos/entrega-reagendada.mp3",
    "audioSecs": 18,
    "name": "pedido-88231"
  }'

A resposta traz o callId, que aparece em todos os webhooks dessa ligação. O audioSecs informa a duração do áudio para a reserva de saldo; sem ele, a API reserva por 120 segundos e acerta pelo tempo real depois. A página ligação telefônica por API detalha os campos de /voice/call e do modo ao vivo, e a de disparo de voz em massa cobre listas, variáveis por destinatário e agendamento.

URA gravada, URA por teclado ou conversa ao vivo

Na prática, o seu produto vai oferecer um ou mais destes formatos ao cliente final, e cada um pede uma integração diferente.

O aviso gravado é o mais simples. O seu cliente sobe um áudio, escolhe a lista e dispara. O que importa no relatório é quem atendeu e por quanto tempo ficou na linha. Clínicas usam para lembrar preparo de exame; academias, para avisar mudança de horário de aula.

A URA por teclado adiciona decisão. “Pressione 1 para confirmar, 2 para remarcar, 9 para falar com a recepção” vira três caminhos no fluxo e três estados no seu banco. É o formato que mais conversa com software de agendamento e com pesquisa rápida de satisfação, porque a resposta chega pronta para virar automação.

A conversa ao vivo troca a gravação por uma pessoa ou por um modelo de voz. O seu sistema recebe uma wsUrl e passa a enviar e receber áudio PCM de 16 kHz em tempo real. Com isso dá para colocar um botão “ligar” dentro do CRM, com o atendente falando pelo navegador (veja URA no navegador com WebRTC), ou ligar um agente de voz com IA para telefone que conversa, anota dados e encerra sozinho.

Como o resultado volta para o seu sistema

Toda ligação gera eventos no webhook de conta do canal voice, configurado uma vez no painel. Disparos únicos, campanhas e ligações ao vivo vão para o mesmo endpoint, e você pode restringir quais eventos quer receber.

O ciclo tem call.started, call.answered, call.dtmf (um evento por tecla) e call.ended, que traz answered, talkSeconds e um código cause com descrição em português. Nas ligações ao vivo, um evento call.audio entrega os links da gravação. Para o relatório do seu cliente, vale agrupar os códigos de causa em poucos estados: atendeu, ocupado, não atendeu, caixa postal e número inválido. A página sobre webhook de URA mostra o envelope completo, a validação da assinatura X-DAPI-Signature e o tratamento idempotente.

Num SaaS multi-tenant, o webhook único por conta pede um detalhe de modelagem: grave o callId devolvido no disparo junto com o identificador do tenant e do objeto de negócio (a consulta, a fatura, o pedido). Quando o evento chegar, um lookup por callId resolve a quem ele pertence.

Cobrança e limites que o seu produto precisa conhecer

As ligações saem do saldo da carteira da conta, cobradas pelo tempo de ligação atendida, com preço por minuto que cai com o volume. Para o seu SaaS, três comportamentos importam na hora de desenhar a tela.

A API reserva saldo antes de discar. Numa campanha, ela calcula quantas ligações o saldo cobre, disca essas e devolve o restante em skipped. Sem saldo para nenhuma, a resposta é HTTP 402 com insufficient_balance. Se o seu produto revende voz, mostre ao cliente um aviso antes do disparo, e não depois.

A cobrança acontece pelo tempo falado. O débito final usa a duração real, e a sobra da reserva volta para o saldo. Ligações não atendidas não entram na conta.

A ligação ao vivo tem prazo e teto. A wsUrl precisa ser aberta em até 30 segundos depois do início, e a duração máxima é de 3.600 segundos, ou menos se o saldo cobrir menos tempo.

Exemplos por segmento

Alguns fluxos que clientes de SaaS montam com a API de URA:

  • Software de clínicas: na véspera, WhatsApp de confirmação; quem não respondeu até as 18h recebe uma ligação com menu “1 confirma, 2 remarca”; a tecla atualiza a agenda e libera o horário para a lista de espera.
  • Cobrança: no terceiro dia de atraso, a régua liga com um aviso gravado; quem atende e aperta 1 recebe o boleto por SMS ou WhatsApp, disparado por um bloco do próprio fluxo.
  • Delivery: quando o pedido atrasa mais de 20 minutos, uma ligação única avisa o cliente final, e o call.ended registra no pedido se ele ouviu o aviso.
  • CRM imobiliário: o corretor clica em “ligar” na ficha do lead e fala pelo navegador; a gravação da ligação fica ligada ao lead pelo callId.
  • Edtech: aluno sem acesso há duas semanas recebe uma ligação de um agente de voz que pergunta o motivo e grava a resposta como dado capturado.

Voz na mesma régua do WhatsApp e do SMS

A vantagem de ter URA na D-API aparece quando os canais trabalham juntos. Um padrão comum: WhatsApp como canal principal, ligação para quem não respondeu, SMS para quem não atendeu. Cada etapa chama um endpoint diferente da mesma API e devolve o resultado por webhook no mesmo envelope, com event, channel, data e timestamp. A regra de quando trocar de canal fica inteira no seu backend.

Vale separar dois produtos parecidos. As ligações de WhatsApp acontecem dentro do aplicativo, saem do número conectado e estão incluídas na conexão da API não-oficial. A URA liga para a linha telefônica, alcança fixo e quem não usa WhatsApp, e é cobrada pelo tempo falado. O protocolo de áudio ao vivo é o mesmo nos dois, então o código de stream que você escrever para um serve para o outro. O artigo sobre URA e disparo de voz por API aprofunda o builder de fluxos e as variáveis da campanha.

Por onde começar a integração

Comece pelo caso que o seu cliente já pede. Configure o webhook de voz no painel com um secret, implemente a validação da assinatura e grave os eventos de forma idempotente. Depois dispare ligações únicas com /voice/call para validar o fluxo de ponta a ponta, e só então libere campanhas e ligação ao vivo na interface do seu produto. A referência de eventos e códigos de causa está na documentação da D-API.

Se o seu SaaS já usa a D-API para WhatsApp, a API key, a base URL e o padrão de webhook são os mesmos. A URA entra como mais um módulo do que você já integrou.

Time D-API. Atualizado em .

telefonia e ura

Tudo sobre telefonia e ura na D-API

Perguntas frequentes

Preciso de um número de telefone ou de um PABX para usar a API de URA?

Não. A D-API disca pela rede de telefonia e o seu sistema só faz chamadas HTTP e recebe webhooks. Também não é preciso ter uma conexão de WhatsApp ativa para ligar pela URA.

A URA atende ligações que chegam para a minha empresa?

A API de URA da D-API é voltada a ligações de saída. Para atender quem liga, o caminho é a ligação de WhatsApp, que a API recebe e pode entregar a um atendente ou a um agente de voz.

Como funciona a cobrança da URA?

As ligações são pagas com o saldo da carteira da conta, pelo tempo de ligação atendida, e o preço por minuto cai com o volume. Ligação não atendida não é cobrada. Para condições de volume, fale com o time.

Consigo usar a URA em qualquer linguagem?

Sim. É uma API REST com OpenAPI 3, autenticada pelo header Authorization. Para Node existe o SDK oficial d-api-sdk, que já tem os métodos de voz e o cliente da ligação ao vivo.

Dá para testar antes de colocar no produto?

Dá. O time libera 14 dias de teste para SaaS, com um grupo de onboarding em que o time técnico acompanha a implementação. A gente também é SaaS e sabe o que é colocar um canal novo em produção.

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.