sms em massa
Envio de SMS em massa por API, com resultado de cada número
Faça o envio de SMS em massa por API a partir do seu SaaS: uma chamada manda o mesmo aviso para a lista, a resposta diz o que saiu, o que falhou e o que ficou sem saldo, e o webhook confirma a entrega.
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 para a lista
POST /api/v1/sms/bulk recebe um array de números e um único texto, com rota e remetente opcionais.
Resultado por número
A resposta traz sent, failed e skipped, e um item em results para cada destino com o seu messageId.
Sem cobrança do que não saiu
Números além do saldo voltam como skipped sem débito, e mensagens rejeitadas na saída têm o valor estornado.
Entrega confirmada por webhook
Cada mensagem aceita gera o status final no webhook de conta, com errorCode normalizado em caso de falha.
O envio de SMS em massa por API é a ferramenta para o aviso que vai para muita gente com o mesmo conteúdo: a manutenção programada, o feriado, a mudança de endereço da unidade, o alerta operacional. Para o seu SaaS, a vantagem de fazer isso por API é que a lista já está no seu banco, filtrada pelo seu cliente, e o resultado volta para a mesma tela. Na D-API, o envio de SMS em massa por API é uma chamada só para POST /api/v1/sms/bulk, com resposta síncrona por número e status de entrega pelo webhook da conta.
Esta página mostra o formato da chamada, como ler a resposta, como o saldo limita o lote e como desenhar o envio num SaaS com muitos clientes disparando ao mesmo tempo. A visão geral do canal está no hub de API de SMS.
Quando o envio em massa é a ferramenta certa
O /sms/bulk envia um único texto para todos os números do array. Ele serve quando a mensagem é igual para todos:
- Gestão de academias: “A unidade Centro fecha às 14h no feriado de amanhã.”
- Software para escolas e edtech: aviso de suspensão de aula por chuva para todos os responsáveis de uma turma.
- Plataforma de delivery: comunicado para a base de clientes de uma região sobre atraso geral por chuva.
- Software de condomínios: aviso de corte de água programado para todos os moradores de um bloco.
- Plataforma de atendimento: alerta de instabilidade para os contatos técnicos dos clientes afetados.
Quando cada pessoa precisa ver o próprio nome, valor ou data, o caminho é /sms/send por destinatário, chamado de um worker com limite de concorrência no seu lado, ou uma campanha de SMS no painel, que aceita planilha e variáveis no texto.
Montando a chamada
O corpo tem to (array com pelo menos um número), text, e os opcionais route e sender. Para comunicados, use route: "marketing", que também é o padrão. O mesmo formato de número do envio individual vale aqui: E.164 com + ou nacional com DDD, com Brasil assumido quando não há +.
curl -X POST https://api.d-api.cloud/api/v1/sms/bulk \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": ["11999999999", "21988888888", "+5531977777777", "4133334444"],
"text": "Academia Fit Centro: amanha, feriado, funcionamos das 8h as 14h.",
"route": "marketing"
}'
O texto passa pela conversão para GSM-7 antes de sair, o que remove acentos e troca emoji por ?. Até 160 caracteres, cada SMS ocupa um segmento; acima disso, partes de 153. Num envio em massa, uma palavra a mais que quebra o segundo segmento dobra o custo do lote inteiro, então a contagem de caracteres na tela de composição do seu produto é um recurso de economia para o seu cliente.
Lendo a resposta
A resposta é síncrona e resume o lote:
{
"success": true,
"sent": 2,
"failed": 1,
"skipped": 1,
"results": [
{ "to": "+5511999999999", "messageId": "3f8c2a1e-...", "status": "sent" },
{ "to": "+5521988888888", "messageId": "9b1d7e40-...", "status": "sent" },
{ "to": "+5531977777777", "status": "failed", "error": "..." },
{ "to": "+554133334444", "status": "skipped" }
]
}
Os três estados pedem tratamentos diferentes no seu produto:
status |
O que aconteceu | Cobrança | O que fazer |
|---|---|---|---|
sent |
Aceito para envio | Debitado no aceite | Gravar o messageId e esperar o webhook |
failed |
Rejeitado na saída | Estornado | Mostrar o motivo e revisar o número |
skipped |
Passou do saldo disponível | Sem cobrança | Avisar o cliente e reenviar após recarga |
Números que não podem ser normalizados nem entram no lote e não aparecem em results. Se nenhum número da lista for válido, a resposta é HTTP 400 com BAD_PHONE; se o saldo não cobrir nenhum envio, HTTP 402 com INSUFFICIENT_CREDITS. Valide e normalize a lista antes de chamar a API, e compare o tamanho de results com o que você enviou para detectar descartes.
O saldo define o tamanho real do lote
O envio em massa calcula o custo por mensagem a partir dos segmentos do texto e da rota, divide o saldo da carteira por esse valor e envia para os primeiros números que cabem. O resto volta como skipped, sem débito. Para um SaaS que revende SMS, isso protege a conta de saldo negativo, mas exige um cuidado de interface: o cliente precisa ver, antes de clicar em enviar, quanto a campanha vai custar e se o saldo cobre. Mostrar skipped como erro silencioso numa tabela gera ticket de suporte; mostrar como “312 números aguardando recarga” gera recarga.
O débito acontece no aceite de cada mensagem. Se a saída rejeitar uma mensagem do lote, o valor dela é estornado e o item volta como failed. Se o envio do lote inteiro falhar, todos os débitos são estornados e a API responde HTTP 502.
Do lote ao relatório de entrega
Cada mensagem com status: "sent" gera, mais tarde, um evento no webhook de SMS da conta: sms.delivered, sms.undelivered, sms.failed ou sms.expired, com data.messageId igual ao messageId da resposta. Grave os messageId de results com o identificador do envio em massa e do tenant, e o relatório da campanha se monta sozinho conforme os eventos chegam: entregues, não entregues por número inválido ou fixo, sem cobertura, expirados.
Esse webhook de conta tem fila durável com retentativas. As campanhas criadas no painel podem ter, além dele, um webhook próprio, que recebe só os destinatários daquela campanha com campaignId e recipientId, mas é entregue numa única tentativa. Para o seu backend, o de conta é a fonte da verdade. A diferença entre os dois canais está detalhada na documentação da D-API.
Boas práticas para SaaS com muitos clientes
- Envie de um worker. A tela do cliente grava a campanha e responde rápido; o worker chama
/sms/bulke persiste os resultados. - Quebre listas grandes em lotes. Como a chamada é síncrona, lotes menores mantêm o tempo de resposta estável e facilitam retomar de onde parou.
- Remova duplicados antes. A API envia para cada item do array, então o mesmo número duas vezes vira dois SMS cobrados.
- Use o SMS como etapa da régua. Num comunicado importante, o SMS em massa pode vir depois do WhatsApp para quem não leu, ou antes de um disparo de voz em massa para quem precisa de confirmação por tecla.
O artigo API de SMS para SaaS mostra como combinar o envio em massa com o fallback individual dentro do mesmo produto.
Time D-API. Atualizado em .
Perguntas frequentes
Existe limite de números por chamada no /sms/bulk?
A validação exige pelo menos um número e não fixa um teto por chamada. O limite prático é o saldo da carteira: o que passa dele volta como skipped. Para listas grandes, quebrar em lotes no seu worker mantém o tempo de resposta previsível.
Consigo personalizar a mensagem com o nome de cada pessoa?
O /sms/bulk envia o mesmo texto para todos. Para personalizar, chame /sms/send por destinatário a partir de um worker, ou use uma campanha de SMS no painel, que aceita planilha e variáveis no texto.
O que acontece com números em formato errado na lista?
Números que não podem ser normalizados para E.164 ficam fora do lote e não aparecem em results. Se nenhum número da lista for válido, a API responde HTTP 400 com BAD_PHONE.
Qual rota usar para comunicados em massa?
A rota marketing, que também é o padrão quando o campo route não é enviado. A rota otp é para envios transacionais, como códigos de verificação.
Quanto custa o SMS em massa?
A cobrança é por segmento, no saldo da carteira, e varia com a rota e o volume. O preço não está publicado no site; fale com o time comercial para receber a tabela do seu volume.