Guia de integração de API de mensagens: REST, SMPP e webhooks

Este guia é para desenvolvedores backend, arquitetos de soluções e CTOs que integram uma aplicação a um provedor de mensagens para WhatsApp, SMS ou e-mail. Ele explica qual interface usar e como tratar autenticação, idempotência, relatórios de entrega, novas tentativas, limites de taxa e testes, com formatos ilustrativos de requisição e resposta. Para sincronizar conversas com um CRM, consulte o guia complementar sobre como conectar um CRM com webhooks.

Qual interface usar: REST, SMPP ou webhooks?

Use REST para enviar, webhooks para receber e SMPP apenas para SMS de alto volume quando você já opera SMPP. Eles são complementares, não concorrentes: a maioria das integrações combina chamadas REST de saída com webhooks de retorno.

As sessões SMPP (Short Message Peer-to-Peer) começam com um bind (transmitter, receiver ou transceiver), enviam mensagens com submit_sm, recebem relatórios de entrega e SMS recebidos por deliver_sm e se mantêm ativas com enquire_link. É eficiente, mas operacionalmente mais pesado que HTTPS.

Como autenticar?

Use o método mais forte que o provedor oferecer, mantenha segredos fora do código e autentique os dois sentidos.

• Chamadas de saída: chaves de API ou tokens bearer OAuth 2.0 enviados no cabeçalho Authorization sobre TLS. Guarde-os em um gerenciador de segredos e faça a rotação periodicamente e após mudanças na equipe.
• SMPP: ID de sistema e senha no bind, normalmente restritos a endereços IP em lista de permissão e, quando houver suporte, sobre TLS.
• Webhooks recebidos: verifique uma assinatura em todo evento. A Meta assina os payloads de webhook da WhatsApp Cloud API com uma assinatura HMAC-SHA256 no cabeçalho X-Hub-Signature-256, calculada com o segredo do seu app; os provedores costumam oferecer um esquema semelhante. Calcule a assinatura sobre o corpo bruto antes de fazer o parse.

Use credenciais separadas por ambiente, para que uma chave de teste vazada não consiga enviar tráfego de produção.

Como enviar uma mensagem com segurança?

Envie por uma fila, inclua uma chave de idempotência e trate a resposta como "aceita", não como "entregue".

Requisição de envio ilustrativa

O formato abaixo é um pseudo-JSON para ilustração, não a API de um provedor específico.

POST /v1/messages
Authorization: Bearer <token>
Idempotency-Key: 7f3c9a2e-order-55821-shipped

{
  "channel": "whatsapp",
  "to": "+9715XXXXXXXX",
  "template": {
    "name": "order_shipped",
    "language": "ar",
    "variables": ["Layla", "55821", "15 March"]
  },
  "client_reference": "order-55821",
  "callback_url": "https://api.example.com/webhooks/messaging"
}

Resposta ilustrativa

202 Accepted

{
  "message_id": "msg_01HZX...",
  "status": "accepted",
  "client_reference": "order-55821",
  "created_at": "2026-10-09T12:00:00Z"
}

Guarde o message_id imediatamente junto à sua própria referência. Tudo o que acontece depois chega de forma assíncrona.

Por que a idempotência importa?

Porque as redes expiram depois que o servidor já agiu. Se a requisição de envio expira e você tenta de novo às cegas, o cliente pode receber dois OTPs ou dois avisos de envio. Uma chave de idempotência permite que o servidor reconheça a nova tentativa e devolva o resultado original.

Regras que funcionam:

1. Derive a chave do evento de negócio (por exemplo, ID do pedido mais tipo de evento), não de um valor aleatório a cada tentativa.
2. Reutilize a mesma chave em todas as novas tentativas do mesmo envio.
3. Mantenha as chaves por tempo suficiente para cobrir a sua janela de novas tentativas.
4. Se o provedor não oferecer suporte a chaves, elimine duplicatas do seu lado antes de enviar.

O rascunho do IETF para o cabeçalho Idempotency-Key padroniza esse padrão para APIs HTTP; as implementações dos provedores variam, então leia a documentação deles.

Como funcionam os relatórios de entrega?

O status de entrega chega depois, na forma de eventos: por webhooks no WhatsApp e na maioria das APIs REST, e por relatórios de entrega deliver_sm no SMPP. O significado dos status difere por canal; nosso guia sobre status de entrega de mensagens explica cada um.

Webhook de status ilustrativo

POST /webhooks/messaging
X-Signature: sha256=<hmac>

{
  "event_id": "evt_9c1...",
  "type": "message.status",
  "message_id": "msg_01HZX...",
  "client_reference": "order-55821",
  "status": "delivered",
  "timestamp": "2026-10-09T12:00:04Z",
  "error": null
}

Trate os eventos de status de forma defensiva:

• Elimine duplicatas por event_id ou por ID da mensagem mais status.
• Nunca regrida uma mensagem de "read" para "delivered" quando os eventos chegarem fora de ordem.
• Responda 2xx rapidamente e processe depois a partir de uma fila.
• Registre os códigos de erro das mensagens com falha e decida quais admitem nova tentativa.
• Espere lacunas: algumas rotas de SMS devolvem relatórios de entrega limitados, e o status de leitura depende do canal e das configurações do usuário.

Como tratar novas tentativas e limites de taxa?

Repita apenas o que pode dar certo, faça backoff exponencial com jitter e respeite os sinais do servidor.

A RFC 9110 define o cabeçalho Retry-After, que pode trazer segundos ou uma data. Coloque um limitador de taxa no cliente à frente dos seus envios para ficar abaixo dos limites documentados do provedor, em vez de descobri-los por meio de erros. O WhatsApp também tem limites do lado da Meta sobre quantos clientes distintos você pode contatar, descritos em limites de mensagens e classificação de qualidade.

Como testar antes de entrar em produção?

Teste os caminhos de falha, não só o caminho feliz.

Checklist pré-produção

1. Envie cada modelo com valores de tamanho real, incluindo texto em árabe.
2. Force um timeout e confirme que a nova tentativa não duplica.
3. Envie para um número inválido e confirme que o erro é tratado sem nova tentativa.
4. Reenvie um webhook duas vezes e fora de ordem; confirme um único estado final.
5. Envie um webhook com assinatura inválida; confirme que é rejeitado.
6. Provoque 429s com um teste de carga no sandbox, se permitido.
7. Faça a rotação de uma chave de API e confirme que não há indisponibilidade.
8. Verifique se os logs contêm IDs de mensagem, mas não o corpo completo das mensagens nem códigos OTP.
9. Execute um pequeno piloto em produção com números internos em cada canal.

Sandboxes raramente reproduzem com exatidão o comportamento das operadoras e da Meta; por isso, mantenha o monitoramento nas primeiras semanas de produção.

Exemplo prático: um serviço de OTP e notificação de pedidos

A "Qafilah Logistics" (fictícia), uma empresa de encomendas na Arábia Saudita, envia atualizações de pedido pelo WhatsApp com fallback por SMS e OTPs de autenticação.

• Arquitetura: os eventos de pedido vão para uma fila; um worker de envio chama a API REST com uma chave de idempotência shipment-id:event.
• Fallback: se o WhatsApp devolver status de falha para um usuário que não usa WhatsApp, o worker envia um SMS com uma nova chave, shipment-id:event:sms.
• OTP: os códigos expiram rápido, então os envios de OTP não são repetidos depois da janela de expiração; o usuário solicita um novo código. Veja o guia de mensagens de autenticação por OTP.
• Relatórios de entrega: um receptor de webhook verifica assinaturas, elimina eventos duplicados e atualiza uma tabela de status que nunca regride.
• Limites: um limitador token bucket mantém a taxa de envio por canal abaixo dos limites documentados.

Quais são os erros de integração mais comuns?

• Tratar "aceita" como "entregue".
• Tentar de novo com uma nova chave de idempotência a cada tentativa.
• Fazer processamento pesado dentro da requisição do webhook.
• Pular a verificação de assinatura nos webhooks.
• Repetir em loop erros de validação 4xx.
• Registrar nos logs códigos OTP e o conteúdo completo das mensagens.
• Usar credenciais de produção em ambientes de teste.

Como a OmniChannels.ai ajuda

A OmniChannels.ai, com tecnologia da BroadNet Technologies, oferece uma API REST/JSON com documentação pública, especificação OpenAPI 3.1 e SDK em TypeScript, cobrindo SMS, WhatsApp, RCS, Messenger, Instagram, Telegram, e-mail e push, incluindo modelos de autenticação do WhatsApp com OTP one-tap, zero-tap e copy-code. Os webhooks informam os status de entrega em um formato normalizado único, o SMPP 3.4 sobre TLS atende ao SMS de alto volume, e um servidor MCP conecta agentes de IA. Relatórios de entrega com filtros e exportação em CSV ajudam a conciliar o que a sua integração enviou. Comece pela documentação para desenvolvedores e pelo quickstart.