SMS transacional: como enviar via API sem montar campanha

Código de verificação, confirmação de pedido, alerta de segurança: são mensagens que o seu sistema dispara para uma pessoa só, no instante em que algo acontece — não para uma lista inteira, num horário agendado. Esse é o SMS transacional. Este guia explica a diferença para o SMS em massa, mostra exemplos e como disparar via API.

O que é SMS transacional

SMS transacional é a mensagem individual disparada por um evento do seu sistema — um código gerado, um pedido criado, um pagamento confirmado — para um único número de telefone, no momento em que o evento acontece. Não depende de lista nem de agendamento: quem dispara o gatilho é a própria ação do usuário no seu produto.

SMS transacional x SMS em massa

Exemplos de SMS transacional

• Código de verificação (OTP) para login ou confirmação de cadastro.
• Confirmação de pedido, reserva ou agendamento.
• Alerta de segurança — login em novo dispositivo, alteração de senha.
• Aviso de entrega ou mudança de status de um pedido.
• Lembrete de fatura vencendo, quando enviado a um único cliente (na régua de cobrança, ver o guia de cobrança automática).
• Link de pagamento gerado sob demanda, fora de uma régua agendada.

Como funciona o envio via API

No three-pulse, um SMS transacional é um único chamado a POST /api/v1/messages:send — a mesma "campanha de um" usada para e-mail transacional, só que com to_phone em vez de to_email (a API infere o canal pelo campo preenchido, ou aceita um channel explícito). A chamada leva um name para identificar o envio na lista de campanhas, o template_id, o to_phone em E.164 e um objeto attributes com as variáveis do evento — como o código gerado ou o número do pedido — que substituem os placeholders do template no momento do envio.

Fila dedicada, sem esperar a fila de campanha

O envio via messages:send entra numa fila dedicada e prioritária, separada da fila de disparo em lote das campanhas em massa — assim, uma campanha de milhões de contatos disparada por outro cliente não atrasa o código de verificação de ninguém. A regra vale para qualquer canal, incluindo SMS.

Quantos segmentos sua mensagem consome

SMS é cobrado por segmento, não por mensagem — e o alfabeto usado no texto decide quanto cabe em cada segmento. Um corpo só com o alfabeto GSM-7 (letras sem acento, números, pontuação básica) cabe em 160 caracteres num segmento único; um único caractere fora dele — e á, ã, õ, ç minúsculo e boa parte dos acentos do português não fazem parte do GSM-7 básico — reclassifica a mensagem inteira para UCS-2, que cabe só 70 caracteres por segmento. Isso é fácil de esquecer justamente porque o pt-BR usa acento o tempo todo: um texto de 100 caracteres sem acento é 1 segmento, mas 100 caracteres com acentuação normal já pode virar 2.

Para códigos e confirmações curtas, escrever sem acento é a forma mais simples de garantir 1 segmento só — o preflight da campanha mostra a estimativa de segmentos antes do disparo, então dá para testar as duas versões do texto e comparar.

Quanto custa enviar SMS transacional

O envio transacional consome o mesmo saldo de créditos pré-pagos do disparo em massa, ao mesmo preço por segmento — não existe tarifa separada por usar a API em vez da interface de campanhas.

Recargas a partir de 1.000 créditos (R$ 49,90), sem preço por usuário e sem validade de crédito.

De qual número a mensagem sai

Por padrão, o envio sai de um remetente compartilhado da plataforma — não é preciso configurar nada para começar a disparar. Se o volume justificar, dá para registrar um remetente próprio nas configurações do workspace, para que os envios do seu negócio saiam de um número dedicado em vez do remetente compartilhado.

Boas práticas de entrega para SMS transacional

• Dispare no momento do evento, não em lote horas depois — o valor do SMS transacional é a proximidade com a ação do usuário.
• Use o campo message_type para rotular o tipo de mensagem (ex.: "sms-otp", "pedido-confirmado") e identificar cada fluxo nos relatórios.
• Prefira texto sem acento em códigos e confirmações curtas para manter 1 segmento só.
• Um número já suprimido para SMS é recusado no próprio chamado da API, antes de qualquer cobrança — trate esse retorno no seu backend em vez de tentar reenviar.
• Teste o template com dados reais de attributes antes de ligar o gatilho em produção — um placeholder sem valor chega em branco para o destinatário.

Base legal do SMS transacional e LGPD

SMS transacional normalmente se apoia em execução de contrato ou cumprimento de obrigação legal, não em consentimento de marketing — são bases legais diferentes das campanhas promocionais (veja o guia de LGPD em marketing multicanal para o comparativo completo). Isso não dispensa boas práticas: identifique claramente o remetente e mantenha a lista de contatos transacionais separada da lista de marketing. Consulte seu jurídico para o enquadramento do seu caso.

Como implementar em 5 passos

1. Crie um template com as variáveis do evento (código, número do pedido, valor, link).
2. Gere uma chave de API do workspace.
3. No seu backend, chame POST /api/v1/messages:send no momento do evento, com name, template_id, to_phone (E.164) e attributes preenchidos com os dados reais.
4. Rotule o disparo com message_type para separar os fluxos nos relatórios.
5. Consulte GET /api/v1/campaigns/{id} com o ID retornado: a resposta traz counts com o total por status (queued, sent, delivered, failed, suppressed, skipped) — para um envio único, o status aparece com contagem 1.

Perguntas frequentes