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

voz e sms

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_NUMBER e LANDLINE: 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_COVERAGE e NOT_RECEIVED: falhas de entrega que podem justificar outro canal, como WhatsApp ou uma ligação de URA.
  • CONTENT_BLOCKED e REJECTED: 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.

Teste com o time técnico do seu lado

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time da D-API acompanha a integração no seu produto.

Leia também

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.