API de SMS para SaaS como canal ao lado do WhatsApp
Use uma API de SMS no mesmo provedor do WhatsApp para fallback, códigos de verificação e avisos críticos dentro do seu SaaS, com status por webhook.
Time D-API. Atualizado em .9 min de leitura.
Uma API de SMS no mesmo provedor do WhatsApp resolve um problema que todo SaaS de comunicação encontra cedo ou tarde: o que fazer quando a mensagem precisa chegar e o WhatsApp não é o caminho. O destinatário pode não ter WhatsApp naquele número, o código de verificação precisa sair mesmo assim, ou o aviso é importante demais para depender de um único canal. Com SMS integrado à mesma conta, o seu produto oferece um plano B sem que o seu time precise de outro fornecedor, outro contrato e outro formato de webhook.
Para o cliente do seu SaaS, isso aparece como uma opção a mais na régua: “se não entregar no WhatsApp, mandar por SMS”. Para o seu time técnico, aparece como dois endpoints e um webhook com o mesmo envelope que você já trata nos outros canais da D-API.
Este artigo mostra como encaixar SMS na arquitetura de um SaaS, em quais cenários ele rende mais, como usar os endpoints /api/v1/sms/send e /api/v1/sms/bulk e como transformar os eventos de entrega em decisões de produto.
Onde o SMS rende mais num SaaS
O SMS tem uma característica que o torna útil como complemento: ele chega em qualquer celular com linha ativa, sem depender de aplicativo instalado. Isso o coloca em três papéis claros dentro de um produto.
Fallback quando o WhatsApp não entrega
O caso mais comum é a régua com segunda tentativa. O seu sistema envia pelo WhatsApp e acompanha o status pelo webhook. Se a mensagem não chegou dentro do prazo que faz sentido para aquele aviso, o SMS assume. Como os dois canais estão na mesma conta, a regra de fallback vive inteira no seu backend, com um único conjunto de credenciais.
Códigos de verificação e confirmações
Login, troca de senha, confirmação de cadastro e validação de telefone pedem uma mensagem curta que precisa chegar rápido. A API de SMS da D-API tem uma rota específica para esse tipo de envio: route: "otp", descrita como transacional. Se o seu SaaS já usa a categoria de autenticação da API Oficial para códigos no WhatsApp, o SMS entra como alternativa para quem não recebeu ou não usa o app.
Avisos críticos em paralelo
Alguns avisos merecem dois canais ao mesmo tempo: queda de serviço, alteração de agendamento em cima da hora, alerta de segurança na conta. Nesses casos o SMS sai junto com o WhatsApp, e o seu sistema registra qual dos dois foi entregue primeiro.
Os dois endpoints de envio
O SMS da D-API usa a mesma autenticação do resto da API (Authorization: SUA_API_KEY) e não depende de sessionId, porque o envio sai pela conta e não por uma sessão de WhatsApp. Isso simplifica o código: não há conexão para manter ativa nem QR code para parear.
Envio individual com /api/v1/sms/send
Os campos obrigatórios são to e text. Opcionalmente você informa route (otp ou marketing, sendo marketing o padrão) e sender.
curl -X POST https://api.d-api.cloud/api/v1/sms/send \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+5511999999999",
"text": "Seu código de acesso é 482913. Ele expira em 10 minutos.",
"route": "otp"
}'
A resposta confirma o aceite e já traz o identificador que liga o envio aos eventos de entrega. Estes são os campos que importam para a sua aplicação:
{
"success": true,
"messageId": "3f8c2a1e-5b7d-4c9a-9e21-7d4b6f0a8c13",
"segments": 1,
"status": "sent"
}
Grave o messageId: ele volta como data.messageId em todos os webhooks daquela mensagem. O campo to aceita o número em E.164 (+5511999999999) ou no formato nacional com DDD (11999999999 ou 5511999999999); sem o +, a D-API assume Brasil e normaliza para E.164. Um número que não pode ser normalizado retorna HTTP 400 com o código BAD_PHONE. O sender troca o remetente exibido (alpha tag) e, quando omitido, vale o remetente padrão. Sem saldo de SMS, a chamada retorna HTTP 402 (INSUFFICIENT_CREDITS) e nada é enviado, e um envio rejeitado na saída tem o valor estornado.
Mesmo texto para vários números com /api/v1/sms/bulk
O envio em massa recebe to como uma lista de números e um único text. É o formato certo para avisos que vão para muitos destinatários com o mesmo conteúdo: comunicado de manutenção, mudança de horário de funcionamento, alerta operacional.
{
"to": ["+5511999999999", "+5521988888888", "+5531977777777"],
"text": "A clínica atende em horário reduzido amanhã, das 8h às 12h.",
"route": "marketing"
}
Para mensagens personalizadas por destinatário (nome, valor, data), o caminho é chamar /api/v1/sms/send por destinatário a partir de um worker, com limite de concorrência definido no seu lado.
A validação exige ao menos um número em to e não fixa um teto de destinatários por chamada. O limite prático é o saldo: os números que passam do saldo disponível voltam como skipped, sem cobrança. A resposta resume o lote e traz o resultado de cada número:
{
"success": true,
"sent": 2,
"failed": 0,
"skipped": 1,
"results": [
{ "to": "+5511999999999", "messageId": "3f8c2a1e-...", "status": "sent" },
{ "to": "+5521988888888", "messageId": "9b1d7e40-...", "status": "sent" },
{ "to": "+5531977777777", "status": "skipped" }
]
}
Números que não podem ser normalizados ficam fora do lote e não aparecem em results, então valide a lista antes de enviar. Como a chamada é síncrona, quebrar listas grandes em lotes no seu worker mantém o tempo de resposta previsível.
Tamanho do texto e segmentos
A cobrança é por segmento, por isso o tamanho do texto pesa no custo. Antes do envio, a D-API converte o texto para o alfabeto GSM-7: acentos são removidos e caracteres fora do alfabeto, como emoji, viram ?. O código do exemplo acima sai como “Seu codigo de acesso e 482913”. Um SMS de até 160 caracteres ocupa um segmento; acima disso, a mensagem é dividida em partes de 153 caracteres. Alguns símbolos, como €, [ e {, contam como dois caracteres.
Webhooks de entrega: o status que alimenta a régua
O SMS só vira canal confiável dentro do produto quando o seu sistema sabe o que aconteceu com cada mensagem. A D-API notifica o status final de entrega por webhook, com quatro eventos:
| Evento | Quando dispara | status resultante |
|---|---|---|
sms.delivered |
A mensagem foi entregue | delivered |
sms.undelivered |
A operadora reportou que não foi entregue | undelivered |
sms.failed |
Falha de rede após o aceite | undelivered |
sms.expired |
A mensagem expirou antes da entrega | expired |
O envio é aceito e cobrado no momento do disparo, por isso o evento sms.sent não é entregue aos webhooks. O que chega é sempre o status final, o que simplifica o modelo de estados no seu banco: uma mensagem nasce como “enviada” na sua aplicação e muda uma única vez quando o webhook chega.
Este é o payload de um sms.undelivered no webhook de conta, conforme a documentação:
{
"event": "sms.undelivered",
"channel": "sms",
"data": {
"messageId": "a1b2c3d4-...",
"to": "+5511999999999",
"status": "undelivered",
"errorCode": "INVALID_NUMBER",
"segments": 1,
"timestamp": "2026-01-24T23:00:00.000Z"
},
"timestamp": "2026-01-24T23:00:00.000Z"
}
Transformando errorCode em ação
O campo errorCode vem normalizado, o que permite tratar falhas com regras simples em vez de interpretar mensagens de operadora. Alguns mapeamentos úteis para o produto:
INVALID_NUMBEReLANDLINE: o número não recebe SMS. Marque o contato para revisão e não tente de novo por esse canal.BLACKLIST: o número consta em blacklist. Respeite e remova das próximas campanhas.NETWORK_ERROR,NO_COVERAGEeNOT_RECEIVED: falhas de entrega que podem justificar outro canal, como WhatsApp ou uma ligação de URA.CONTENT_BLOCKEDeREJECTED: revise o texto. Vale mostrar esse motivo para o cliente do seu SaaS na tela da campanha.
O campo segments informa em quantas partes o SMS foi dividido. Mostrar esse número na interface ajuda o seu cliente a escrever textos mais curtos.
Conta ou campanha: escolhendo o webhook
Há dois canais de webhook independentes. O webhook de conta é configurado uma vez e recebe o status de todos os envios (API avulsa, disparos em massa e fluxos). Ele usa o envelope com data, tem fila durável com retentativas, circuit breaker por URL e logs de entrega. O webhook por campanha é configurado na própria campanha de disparo em massa, chega com os campos no nível raiz e inclui campaignId e recipientId para correlação, mas é entregue numa única chamada HTTP, sem retentativa.
Para um SaaS, a recomendação prática é usar o webhook de conta como fonte da verdade e tratar o de campanha, se usado, como conveniência. Os dois enviam o header X-DAPI-Signature com HMAC-SHA256 do corpo bruto quando há um secret configurado; valide sempre antes de processar. A referência completa está na documentação da D-API.
Modelando SMS num SaaS multi-tenant
Como o webhook de conta concentra os envios de todos os clientes do seu SaaS, a separação por tenant acontece no seu banco. Grave o messageId retornado no envio junto com o identificador do cliente e do objeto de negócio (o login, a fatura, o agendamento). Quando o webhook chegar, o lookup por messageId resolve tudo. É o mesmo padrão multi-tenant que você aplica aos eventos de WhatsApp, explicado no artigo sobre webhooks da API de WhatsApp.
Algumas práticas deixam a integração estável:
- Fallback com prazo explícito. Defina, por tipo de aviso, quanto tempo esperar a confirmação do WhatsApp antes de acionar o SMS. Código de verificação pede segundos; lembrete de consulta tolera mais.
- Chave de idempotência no seu lado. Antes de disparar o SMS de fallback, verifique se já existe um envio para aquele evento de negócio. Isso evita mensagem duplicada quando o webhook do WhatsApp chega atrasado.
- Envio fora do request. A ação do usuário grava a intenção de envio; um worker chama a API.
- Webhook que responde rápido. Grave o evento numa fila sua e processe em seguida.
SMS, WhatsApp e voz no mesmo provedor
A vantagem de ter SMS na D-API vai além do próprio SMS. A mesma conta oferece WhatsApp pela API não-oficial e pela API Oficial da Meta na mesma implementação (o artigo sobre API oficial e não oficial na mesma integração explica como), além de voz com URA e disparo em massa, detalhados no artigo sobre URA e disparo de voz por API. São 1.875 conexões em 4 datacenters no Brasil, com 99,9% de uptime garantido em contrato e suporte humano.
Na prática, isso permite oferecer ao seu cliente uma régua completa: WhatsApp como canal principal, SMS como fallback e para códigos, voz para os avisos que precisam de confirmação por tecla. Se a régua usa templates da API Oficial, as tarifas de mensagem da Meta são cobradas na conta Meta do seu cliente, e a tabela de preços da Meta mostra a tarifa de cada categoria para comparar o custo de cada etapa.
Por onde começar
O caminho mais curto é começar pelo cenário em que o SMS já faz falta no seu produto. Para a maioria dos SaaS, é o código de verificação ou o fallback de um aviso importante. Configure o webhook de conta com secret, implemente a validação da assinatura e o mapeamento de errorCode, e só então ligue o envio com /api/v1/sms/send usando a rota adequada. Quando o fluxo individual estiver redondo, /api/v1/sms/bulk cobre os comunicados para muitos destinatários.
Os 14 dias de teste que o time libera para SaaS, com o grupo de onboarding, servem para validar exatamente isso: do primeiro envio ao primeiro webhook tratado, com o nosso time técnico acompanhando. O preço por conexão de WhatsApp continua caindo com o volume, como mostra a tabela em /#preco.
Veja também: Ligações no WhatsApp, Telefonia e URA, SMS.
Perguntas frequentes
Dá para receber respostas de SMS pela API?
Não. O SMS da D-API é outbound-only: você envia e recebe o status de entrega por webhook, mas não existe evento de SMS recebido. Para conversa de mão dupla, use o WhatsApp.
Qual a diferença entre as rotas otp e marketing?
O campo route aceita otp para envios transacionais, como códigos de verificação, e marketing para comunicações promocionais. Quando o campo não é enviado, a rota padrão é marketing.
Como sei se o SMS foi entregue?
Os webhooks notificam o status final: sms.delivered, sms.undelivered, sms.failed ou sms.expired. Em caso de falha, o campo errorCode traz um código normalizado, como INVALID_NUMBER ou LANDLINE.
Webhook de conta ou webhook por campanha?
O webhook de conta recebe o status de todos os envios e tem fila durável com retentativas. O webhook por campanha recebe só os destinatários daquela campanha e é fire-and-forget, sem retentativa. Para entrega confiável, prefira o de conta.
O SMS usa a mesma API key do WhatsApp?
Sim, a autenticação é a mesma da API da D-API, com o header Authorization. O SMS não depende de sessionId, porque o envio é feito pela conta e não por uma conexão de WhatsApp.