torpedo de voz por api
Disparo de voz em massa pela API, com o resultado de cada ligação
Coloque o disparo de voz em massa dentro do seu SaaS: uma chamada HTTP liga para a lista inteira, toca um áudio ou um fluxo de URA e devolve por webhook quem atendeu, o que apertou e por quanto tempo ouviu.
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
Uma chamada, a lista inteira
O endpoint /api/v1/voice/bulk recebe os números ou destinatários com variáveis e devolve um bulkId para a campanha.
Agendamento nativo
Com scheduledAt no futuro, a API reserva o saldo na hora e começa a discar no horário marcado.
Saldo protegido
A campanha disca só o que o saldo cobre e informa o restante em skipped, sem surpresa na fatura do seu cliente.
Relatório por ligação
Cada ligação tem um bulkCallId e um código de causa, prontos para separar atendeu, ocupado e caixa postal.
O disparo de voz em massa, também chamado de torpedo de voz, é a forma mais direta de avisar muita gente ao mesmo tempo por telefone. Para um SaaS, o valor está em oferecer isso dentro do produto: o seu cliente escolhe a lista, sobe o áudio, define o horário e acompanha o resultado na mesma tela em que já gerencia a agenda, a cobrança ou os pedidos. Na D-API, todo o disparo de voz em massa passa por um endpoint, POST /api/v1/voice/bulk, e o resultado de cada ligação volta por webhook.
Esta página mostra como montar a campanha pela API, como personalizar por destinatário, como agendar e como transformar os eventos em relatório para o seu cliente. A visão geral dos modos de ligação está no hub de API de URA.
Onde o torpedo de voz rende num SaaS
Voz em massa funciona melhor em aviso curto, com prazo, para uma base que nem sempre lê mensagem. Alguns exemplos reais de uso por segmento:
- Software de cobrança: lembrete de vencimento no dia anterior para toda a carteira em aberto, com menu “1 para receber a segunda via”.
- Gestão de academias: aviso de mudança no horário de funcionamento num feriado, para todos os alunos ativos.
- Plataforma de agendamento: confirmação em lote das consultas do dia seguinte, depois de uma primeira tentativa por WhatsApp.
- Sistema para escolas e edtech: comunicado de reunião de pais, com tecla para confirmar presença.
- Software de condomínio ou administradora: aviso de manutenção que vai cortar água ou elevador.
Em todos eles o padrão é o mesmo: o seu produto já tem a lista e o motivo do aviso, e a API entra como o motor de discagem.
Montando a campanha com /api/v1/voice/bulk
O corpo precisa de duas escolhas. A primeira é o conteúdo: audioUrl para um áudio único ou flowId para um fluxo de URA interativo, exatamente um dos dois. A segunda é a lista: numbers para telefones simples ou recipients para destinatários com variáveis, também exatamente um dos dois. Quando a regra não é respeitada, a API responde HTTP 400 com um código claro (AUDIO_OR_FLOW_REQUIRED, AUDIO_AND_FLOW_EXCLUSIVE ou NUMBERS_OR_RECIPIENTS_REQUIRED), o que facilita mostrar o erro certo na interface do seu cliente.
Um aviso gravado para uma lista de alunos fica assim:
curl -X POST https://api.d-api.cloud/api/v1/voice/bulk \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audioUrl": "https://seu-cdn.com/avisos/feriado-horario.mp3",
"audioSecs": 25,
"numbers": ["5511999999999", "5521988888888", "5531977777777"],
"name": "academia-412-feriado-novembro"
}'
A resposta traz o resumo da campanha (os campos de reserva e faixa de preço foram omitidos):
{
"success": true,
"bulkId": "b7e1c2d4-...",
"dialed": 3,
"skipped": 0
}
Guarde o bulkId. Ele chega como callId em todos os webhooks da campanha, enquanto o bulkCallId identifica cada ligação individual. O campo name aparece no painel e ajuda a auditar qual campanha veio de qual cliente do seu SaaS, então vale colocar nele o identificador do tenant e do objeto de negócio.
Personalização por destinatário com recipients
Quando a campanha usa um fluxo de URA, cada destinatário pode levar um objeto variables. Os valores entram no contexto da ligação e ficam disponíveis nos blocos do fluxo como {{input.nome}}, ao lado de {{input.phone}} e da última tecla pressionada.
{
"flowId": "SEU_FLOW_ID",
"name": "cobranca-tenant-87-vencimento",
"recipients": [
{ "phone": "5511999999999", "variables": { "nome": "Marina", "fatura": "F-20931" } },
{ "phone": "5541977776666", "variables": { "nome": "Rogério", "fatura": "F-20977" } }
],
"maxAttempts": 2
}
Como os áudios do fluxo são gravações, as variáveis servem para o que o fluxo faz durante a ligação: mandar um SMS com a segunda via da fatura certa, abrir um WhatsApp com o nome da pessoa ou chamar o seu backend com o número da fatura quando alguém aperta 1. No modo audioUrl elas não são usadas. A montagem do fluxo no builder do painel está explicada no artigo sobre URA e disparo de voz por API.
Agendamento, saldo e novas tentativas
O campo scheduledAt recebe um timestamp ISO 8601. Com data futura, a API reserva o saldo na hora, guarda a lista e começa a discar no horário marcado; a resposta volta com scheduled: true. Sem o campo, ou com data passada, a campanha sai imediatamente. Para produtos que já têm agenda ou régua, isso evita manter um cron próprio só para voz.
A reserva de saldo também define o tamanho real da campanha. A API estima o custo por ligação (com audioSecs no modo áudio; 120 segundos no modo fluxo ou quando o campo falta), disca o que o saldo cobre e devolve o resto em skipped. O acerto final usa o tempo falado de verdade, e a sobra volta para a carteira. Se o seu SaaS revende voz, mostre a estimativa antes do disparo e trate o skipped como alerta na tela da campanha.
O maxAttempts define quantas vezes a plataforma tenta o mesmo número em caso de falha técnica, como congestionamento da rede, tempo de toque esgotado ou atendimento falso da operadora. Ocupado e recusa (cause de 17 a 21), caixa postal (151) e número inválido encerram aquele destinatário sem nova tentativa. Se o seu cliente quiser insistir com quem não atendeu, o caminho é uma segunda campanha só com esses números, agendada para outro horário.
Do webhook ao relatório da campanha
Cada ligação passa por call.started, call.answered quando alguém atende, call.dtmf a cada tecla (apenas em fluxos de URA) e call.ended, com answered, talkSeconds, cause e causeDescription. Para o relatório, agrupe os códigos de causa em estados de negócio:
| Estado no seu produto | Códigos de cause |
|---|---|
| Atendeu | 16 com answered: true |
| Ocupado | 17 |
| Não atendeu | 18, 19, 150 |
| Caixa postal | 151 |
| Número inválido | 1, 22, 28 |
Com essa tabela, a tela da campanha mostra percentuais que o seu cliente entende, e a régua decide o próximo passo: número inválido sai da base, quem não atendeu entra na próxima tentativa, caixa postal recebe um SMS em massa na sequência. O tratamento completo dos eventos, com assinatura e idempotência, está na página sobre webhook de URA, e a tabela inteira de causas na documentação da D-API.
Boas práticas de arquitetura
Algumas decisões deixam o disparo previsível quando o seu SaaS tem muitos clientes disparando ao mesmo tempo:
- Dispare de um worker. A tela do cliente grava a intenção da campanha e responde rápido; um worker chama
/voice/bulke grava obulkIdjunto com o tenant. - Quebre listas muito grandes. Campanhas menores, com
namesequencial, deixam o relatório mais legível e isolam erro de dado numa parte da base. - Valide os números antes. A plataforma insere o nono dígito quando um celular brasileiro chega sem ele, mas número incompleto continua inválido e só aparece no
call.ended. - Respeite horário. Agende avisos com
scheduledAtem horário comercial do destinatário, e não no momento em que o seu cliente clicou.
Para avisos individuais disparados por evento, como a confirmação de uma única consulta, o endpoint certo é o de ligação telefônica por API, que segue o mesmo modelo de cobrança e de webhook.
Time D-API. Atualizado em .
Perguntas frequentes
Qual a diferença entre torpedo de voz e URA?
Torpedo de voz é o disparo de um áudio gravado para uma lista. A URA adiciona interação: a pessoa aperta teclas e a ligação segue caminhos diferentes. No /voice/bulk, o primeiro usa audioUrl e o segundo usa flowId.
Posso subir uma planilha em vez de montar o JSON?
No painel da D-API, a campanha de voz aceita planilha CSV ou XLSX e mapeia as colunas para telefone e variáveis. Pela API, o seu sistema envia a lista em numbers ou recipients.
O que acontece se o saldo acabar no meio da lista?
A reserva é feita antes de discar. A API calcula quantas ligações o saldo cobre, disca essas e devolve a quantidade que ficou de fora em skipped. Se nenhuma couber, a resposta é HTTP 402 com insufficient_balance.
Ligação que cai na caixa postal é tentada de novo?
Não. Caixa postal, ocupado e chamada recusada encerram aquele número na campanha. As novas tentativas de maxAttempts ficam para falhas técnicas, como congestionamento da rede ou tempo de toque esgotado.
Quanto custa uma campanha de voz?
As ligações saem do saldo da carteira e são cobradas pelo tempo falado, sem cobrança para quem não atendeu. Para volume e condições de revenda, fale com o time comercial.