Do primeiro request à operação real.

Resposta curta: uma API para WhatsApp conecta seu sistema ao canal de mensagens. A integração confiável precisa receber o pedido, persistir em fila, evitar duplicação, enviar, acompanhar o status final e avisar seu sistema por webhook.

O que é uma API para WhatsApp?

É uma interface para que CRM, ERP, e-commerce, chatbot ou sistema próprio envie e receba mensagens sem depender de alguém digitando no aplicativo. Em vez de clicar em “enviar”, o sistema faz uma requisição HTTP com o número e o conteúdo. A API devolve um identificador e o processamento continua.

Essa última parte é importante: a resposta inicial normalmente não prova que o destinatário recebeu a mensagem. Ela prova que a plataforma aceitou o trabalho. Na Relya, HTTP 202 significa aceito ou enfileirado. Envio, entrega, leitura e falha são estados posteriores.

Os dois modelos de integração

Antes do código, escolha a arquitetura. Há dois caminhos principais: a API oficial da Meta e uma conexão independente por QR Code, como a Relya. Nenhum deles é “melhor” em qualquer cenário.

Se sua operação exige canal oficial, escala regulamentada e fluxos aderentes ao ecossistema da Meta, avalie a API oficial. Se precisa integrar rapidamente um número existente e aceita o modelo de dispositivo vinculado, a conexão por QR Code pode ser adequada. Veja a comparação detalhada.

O fluxo completo, sem caixa-preta

1. Seu sistema autentica. A credencial identifica a instância e deve ficar somente no servidor.
2. A API valida o corpo. Número, tipo de mídia e campos obrigatórios são conferidos.
3. A idempotência é aplicada. Repetir a mesma ação de negócio não deve criar um segundo envio.
4. A mensagem entra em fila persistente. Reiniciar um processo não pode apagar o trabalho.
5. O transporte tenta enviar. A sessão precisa estar conectada e saudável.
6. Os estados são registrados. Enfileirada, enviada, entregue, lida ou falha.
7. Seu sistema recebe webhooks. O evento é assinado, repetido em falha e deduplicado pelo consumidor.

Uma demonstração costuma validar apenas o passo cinco. Produção precisa provar os sete.

Primeiro envio de texto

Na Relya, a base de produção é https://relya.com.br. Envie a credencial do número no cabeçalho token e uma chave única da ação no cabeçalho idempotency-key.

curl -X POST \
  -H 'token: SUA_CREDENCIAL' \
  -H 'content-type: application/json' \
  -H 'idempotency-key: pedido-123' \
  -d '{"number":"5521999999999","text":"Olá"}' \
  https://relya.com.br/send/text

Não gere uma chave aleatória a cada nova tentativa técnica. A chave deve representar a ação de negócio — por exemplo, cobranca-fatura-9842. Se seu servidor perder a resposta e repetir o request, a plataforma pode devolver a operação original sem criar outra mensagem.

Texto, áudio, imagem, vídeo e documento

O endpoint de mídia usa /send/media. O campo type define o formato. O arquivo pode vir de URL HTTPS, data URI ou base64. URL é mais leve para requests grandes, desde que o arquivo esteja disponível com segurança durante o processamento.

curl -X POST \
  -H 'token: SUA_CREDENCIAL' \
  -H 'content-type: application/json' \
  -H 'idempotency-key: contrato-456' \
  -d '{
    "number":"5521999999999",
    "type":"document",
    "file":"https://exemplo.com/contrato.pdf",
    "fileName":"contrato.pdf",
    "caption":"Contrato"
  }' \
  https://relya.com.br/send/media

Para áudio, use type: "audio". O campo ptt: true apresenta como mensagem de voz; false, como arquivo de áudio. O tutorial de envio de áudio mostra MIME type, URL e erros comuns.

Webhooks, retry e idempotência

Webhook é uma chamada da Relya para seu servidor quando algo acontece. Seu endpoint deve validar a assinatura HMAC, registrar o identificador da entrega, responder rápido com 2xx e processar trabalho demorado em uma fila própria.

A configuração padrão faz até seis tentativas no total: imediata e, em caso de falha, após 5, 10, 20, 40 e 80 segundos. Todas mantêm o mesmo x-relya-delivery-id. Isso permite deduplicar mesmo quando um timeout acontece depois de seu sistema já ter processado o evento.

Leia o guia de webhooks, assinatura e repetição antes de colocar automações financeiras, suporte ou pedidos em produção.

Checklist antes de produção

• Token fora do frontend e de repositórios públicos.
• Chave de idempotência derivada da ação de negócio.
• Fila persistente e política clara de novas tentativas.
• Status final acompanhado por webhook, não inferido pelo 202.
• Assinatura HMAC validada usando o corpo bruto.
• delivery-id gravado para impedir duplicação.
• Teste de desconexão, timeout, resposta repetida e retomada.
• Logs sem conteúdo sensível desnecessário.
• Contatos que reconhecem a empresa e esperam a mensagem.
• Plano de pausa quando aumentarem falhas ou respostas negativas.

A documentação pública da Relya mostra autenticação, exemplos e o catálogo de 139 rotas, sendo 125 diretas e 14 adaptadas. A página de boas práticas cobre os sinais operacionais que pedem redução ou pausa.