Como integrar RCS, WhatsApp, SMS e voz no seu produto com uma única API

Integrar mensageria costuma virar quatro integrações: uma por canal, cada uma com autenticação, formatos e webhooks diferentes. A abordagem da API da Nexfy é outra: um endpoint, um payload e o canal como parâmetro. Este guia mostra o desenho recomendado.

1. Autenticação e ambientes

Gere chaves separadas para teste e produção, com permissões por chave. Envie no header Authorization: Bearer. Em teste, nenhum envio real é feito e os webhooks são simulados para o seu endpoint.

2. Envio unificado

POST /v1/messages
{
  "channel": "whatsapp",        // "rcs" | "sms" | "voice"
  "to": "+5511999999999",
  "template": "pedido_confirmado",
  "variables": { "pedido": "1042", "entrega": "amanhã" },
  "fallback": { "channel": "sms" }
}

A resposta traz o id da mensagem e o status inicial (queued). Guarde o id: é a chave para correlacionar eventos.

3. Webhooks assinados

Cadastre uma URL para receber eventos: message.sent, message.delivered, message.read, message.failed, message.clicked e message.received (respostas). Cada evento chega com uma assinatura no header; valide antes de processar.

• Responda 2xx rápido e processe de forma assíncrona.
• Trate eventos como idempotentes: o mesmo evento pode chegar mais de uma vez.
• Não confie na ordem: um delivered pode chegar antes do sent.

4. Idempotência no envio

Se o seu sistema tentar de novo por timeout, um segundo SMS seria custo e ruído. Envie um identificador único por requisição (Idempotency-Key); requisições repetidas com a mesma chave retornam a mesma mensagem.

5. Retentativas e limites

Use backoff exponencial em erros 5xx e respeite o Retry-After em 429. Configure alertas por chave para consumo e taxa de falha.

6. Observabilidade

Registre o id da mensagem no seu domínio (pedido, usuário) e use os logs por requisição do painel para investigar. Um dashboard com envios, entregas e falhas por canal evita surpresas.