O envio começa antes da operadora
Uma integração confiável não trata o HTTP 202 como prova de entrega. Esse retorno confirma que o Mandaí aceitou uma intenção válida para processamento. A partir daí, a mensagem ganha uma identidade estável, passa por reserva de capacidade, tentativa no provedor e coleta de evidências. Cada mudança fica disponível na aba Mensagens, na API e nos webhooks.
Essa separação evita duas confusões comuns: considerar uma requisição aceita como SMS entregue e repetir uma escrita quando a resposta ao cliente se perde. No Mandaí, a mesma Idempotency-Key representa a mesma intenção. Repetir o comando com a chave original recupera o resultado conhecido sem criar um segundo envio.
Um contrato pequeno e verificável
O caminho de produção precisa de poucos elementos, todos explícitos:
- destinatário em E.164 brasileiro;
- conteúdo transacional dentro do limite aceito;
- credencial pertencente ao mesmo ambiente da requisição;
- capacidade mensal disponível;
- Idempotency-Key estável para aquela intenção.
Antes de enviar, o endpoint de preview informa encoding, quantidade de caracteres, segmentos e consumo máximo estimado. Assim, a aplicação pode mostrar o custo operacional correto antes de confirmar uma escrita externa.
Estados são evidências, não decoração
O estado queued informa que a intenção foi aceita. provider_acknowledged registra que o provedor reconheceu a tentativa. delivered depende de uma confirmação posterior. failed representa uma falha terminal conhecida. unknown é preservado quando não há evidência suficiente para declarar sucesso ou falha.
O estado unknown não autoriza um novo SMS. Reenviar nessa situação pode duplicar uma mensagem que já chegou ao aparelho. O comportamento seguro é consultar a mesma mensagem, guardar o identificador e investigar a linha do tempo.
Webhooks que podem ser auditados
O Mandaí assina webhooks sobre o corpo bruto. O consumidor valida timestamp, assinatura e janela de tolerância antes de interpretar o JSON. Como a entrega é at-least-once, o identificador do evento também precisa ser deduplicado.
O resultado é um fluxo em que dashboard, API, SDK e agentes de IA enxergam a mesma verdade. Não existe um ledger paralelo para o chat nem uma contagem especial para a integração tradicional: qualquer SMS de produção reserva e consome a mesma capacidade contratada.
Onde começar
Use primeiro a Sandbox para validar idempotência, falhas e webhooks sem alcançar uma operadora. Depois, contrate a capacidade mensal adequada, confira a janela operacional exibida no produto e troque a origem e a chave para Produção. A documentação do Mandaí mantém exemplos completos para HTTP e SDK JavaScript/TypeScript.