Partner API v1

1. Dados de acesso

Para iniciar a homologação, o integrador recebe por canal seguro uma API key Partner, os client_id e channel_id autorizados e, quando webhooks forem habilitados, o segredo individual de assinatura.

Todos os endpoints protegidos usam Authorization: Bearer <API_KEY>. Credenciais da Meta nunca são fornecidas ao integrador.

2. Validar acesso

GET /status

curl -sS "https://disparador.net/index.php?url=api/v1/status" \
  -H "Authorization: Bearer $DISPARADOR_API_KEY" \
  -H "Accept: application/json"

HTTP 200 retorna o Partner e somente os canais autorizados àquela credencial. Guarde client_id e channel_id.

3. Consultar templates

GET /templates?client_id=123&channel_id=456

curl -sS "https://disparador.net/index.php?url=api/v1/templates&client_id=123&channel_id=456" \
  -H "Authorization: Bearer $DISPARADOR_API_KEY" \
  -H "Accept: application/json"

Somente templates ativos e aprovados do cliente/canal solicitado são retornados. Use o campo id retornado como template.id no envio.

4. Enviar mensagem

Todo POST /messages exige Idempotency-Key de 8 a 120 caracteres, usando letras, números, ponto, hífen, sublinhado ou dois-pontos. Gere uma chave para cada intenção de envio.

Texto livre

Exige janela de atendimento de 24 horas aberta.

curl -sS -X POST "https://disparador.net/index.php?url=api/v1/messages" \
  -H "Authorization: Bearer $DISPARADOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-20261002-000001" \
  --data '{"client_id":123,"channel_id":456,"to":"5541999999999","type":"text","text":{"body":"Olá! Como posso ajudar?"}}'

Template

Fora da janela de 24 horas, utilize um template aprovado.

{
  "client_id": 123,
  "channel_id": 456,
  "to": "5541999999999",
  "type": "template",
  "template": {"id": 789, "variables": {"1": "Maria"}}
}

Uma requisição aceita retorna HTTP 202 com message_id, local_message_id, status: accepted e type.

5. Enviar mídia

Imagem, PDF, áudio e vídeo usam duas etapas. Primeiro faça upload:

curl -sS -X POST "https://disparador.net/index.php?url=api/v1/media" \
  -H "Authorization: Bearer $DISPARADOR_API_KEY" \
  -F "client_id=123" -F "channel_id=456" -F "type=image" -F "file=@foto.jpg"

O HTTP 201 retorna um media_id. Depois utilize esse identificador em POST /messages.

{
  "client_id":123, "channel_id":456, "to":"5541999999999",
  "type":"image", "image":{"media_id":"MEDIA_ID","caption":"Foto"}
}

Mídia livre também exige janela de atendimento de 24 horas.

6. Receber eventos por webhook

Eventos disponíveis: message.received, message.sent, message.delivered, message.read, message.failed e message.reaction.

O endpoint deve ser HTTPS público na porta 443. Localhost, endereços privados/reservados e credenciais embutidas na URL não são aceitos. Redirects HTTP não são seguidos.

X-Disparador-Event-Id: evt_...
X-Disparador-Timestamp: 1790956800
X-Disparador-Signature: sha256=<hex>

A assinatura é HMAC-SHA256(WEBHOOK_SECRET, TIMESTAMP + "." + RAW_HTTP_BODY). Compare-a em tempo constante, valide a idade do timestamp e persista o event_id para ignorar duplicidades.

Responda com HTTP 2xx somente depois de aceitar/persistir o evento. Respostas fora de 2xx são consideradas falha e podem ser reenviadas. Há até 6 tentativas com backoff.

Coexistence e intervenção humana

Ações manuais no WhatsApp Business App podem gerar message.sent ou message.reaction com {"source":"business_app","human":true}. Use esses campos para pausar automações ou sincronizar a conversa.

7. Mídia recebida

Eventos recebidos de áudio, imagem ou documento podem incluir data.media.download_url. A URL pertence ao Disparador.net e deve ser acessada com a mesma API key.

curl -sS "$DOWNLOAD_URL" \
  -H "Authorization: Bearer $DISPARADOR_API_KEY" \
  -o arquivo

A URL não expõe token nem URL temporária da Meta.

8. Idempotência, limites e retries

Mesma Idempotency-Key + mesmo corpo reproduz a resposta armazenada; a mesma chave com corpo diferente retorna HTTP 409. Uma requisição ainda em processamento também retorna HTTP 409.

Em HTTP 429, respeite Retry-After. Respostas autenticadas informam X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.

9. Tratamento de erros

{"error":{"code":"validation_error","message":"..."}}

Códigos relevantes incluem unauthorized, invalid_json, invalid_idempotency_key, validation_error, unsupported_message_type, channel_not_authorized, channel_not_ready, customer_care_window_closed, template_not_available, meta_send_failed, media_upload_failed, media_not_found, media_unavailable, rate_limit_exceeded, rate_limit_unavailable, payload_too_large, idempotency_conflict, request_in_progress, method_not_allowed e internal_error.

Não faça retry cego em 4xx. Para 429, aguarde Retry-After.

10. Checklist de homologação

1. GET /status retorna 200 e o canal esperado.
2. GET /templates retorna os templates aprovados.
3. Template é enviado e eventos de status chegam ao webhook.
4. Após uma mensagem recebida abrir a janela, texto livre é enviado.
5. Áudio, imagem e PDF são testados nos sentidos necessários.
6. HMAC é validado sobre o corpo bruto.
7. Duplicidade de event_id é ignorada.
8. Retry de POST /messages reutiliza a mesma Idempotency-Key.
9. HTTP 429 respeita Retry-After.
10. source=business_app e human=true são tratados quando Coexistence estiver ativo.