Saúde de Entregas

O que reportar

Reportar status

curl --request POST 'https://api.hookcloud.app/functions/v1/swift-worker' \
  --header 'apikey: SUA_PUBLISHABLE_KEY' \
  --header 'Authorization: Bearer hc_partner_live_SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --data '{
    "route": "report-partner-message-status",
    "phone_number_id": "PHONE_NUMBER_ID",
    "message_id": "wamid.xxxxx",
    "status": "delivered",
    "template_name": "confirmacao_agendamento",
    "template_language": "pt_BR",
    "campaign_id": "campanha_456",
    "occurred_at": "2026-07-21T12:00:00Z"
  }'

131049 — healthy ecosystem engagement

• Não faça retentativa automática imediata.
• Aguarde ao menos 24 horas para nova tentativa manual.
• Revise opt-in, segmentação, frequência e engajamento recente.
• Não alterne números para contornar a proteção.

{
  "route": "report-partner-message-delivery-failure",
  "phone_number_id": "PHONE_NUMBER_ID",
  "message_id": "wamid.xxxxx",
  "client_message_id": "msg_local_123",
  "template_name": "campanha_marketing",
  "campaign_id": "campanha_456",
  "error_code": 131049,
  "error_title": "This message was not delivered to maintain a healthy ecosystem engagement",
  "error_message": "Detalhe retornado pela Meta",
  "recipient_hash": "HMAC_SHA256_HEX_COM_64_CARACTERES",
  "occurred_at": "2026-07-21T12:00:00Z"
}

131042 — pagamento da WABA na Meta

• Verifique cartão cadastrado no WhatsApp Manager.
• Verifique linha de crédito e conta de pagamento.
• Regularize restrições financeiras antes de reenviar.
• Use client_message_id quando a falha ocorrer antes do waMID.

Outros códigos classificados

Consultar métricas

GET https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-delivery-health&window_hours=24

Retorna totais, taxa de falha, contagens 131049/131042, top erros, top templates e alertas abertos.

Privacidade

• Não envie conteúdo da mensagem
• Não envie nome do destinatário
• Não envie telefone em texto puro
• Use HMAC-SHA256 em recipient_hash
• Envie somente metadados técnicos necessários; o BSUID é aceito e convertido em hash pelo Partner

Reportar status com BSUID

O relatório opcional de saúde aceita recipient_user_id, user_id ou recipient com um BSUID. Também reconhece status_payload.recipient_user_id. A HookCloud trata esse identificador como texto opaco e o separa da identidade por telefone antes de gerar o hash. Nunca remova o prefixo do país nem extraia apenas os dígitos.

{
  "route": "report-partner-message-status",
  "phone_number_id": "PHONE_NUMBER_ID",
  "message_id": "wamid.DA_MENSAGEM",
  "status": "delivered",
  "recipient_user_id": "BR.BSUID_RECEBIDO_DA_META",
  "occurred_at": "1789055123"
}

occurred_at aceita ISO 8601 ou timestamp Unix em segundos, numérico ou string, como o enviado pela Meta. Valores inválidos retornam 400. Envie Idempotency-Key quando disponível; o servidor também possui uma chave determinística para evitar repetir o mesmo evento quando o timestamp é omitido.

O endpoint não envia mensagens nem altera os eventos no sistema externo. Ele registra os status informados pelo backend do parceiro para a Saúde de Entregas.

Filtros, datas e permissões

get-partner-delivery-health exige window_hours inteiro entre 1 e 2160 (padrão 24). A busca de eventos exige page de 1 a 1.000.000 e page_size de 1 a 200. Filtros de cliente, instância e parceiro devem ser UUIDs válidos.

date_from e date_to aceitam uma data válida YYYY-MM-DD ou data/hora ISO 8601 com fuso, como 2026-09-10T12:00:00Z ou 2026-09-10T09:00:00-03:00. Datas impossíveis, horários sem fuso e intervalos invertidos retornam 400. Para um limite horário preciso, envie timestamp com fuso em vez de presumir que uma data simples representa o dia inteiro.

Consultas exigem o escopo meta_risk.read. Relatórios de status exigem API Key com instances.write, ou um membro owner/admin/developer. Agent e viewer não podem registrar status e recebem 403 delivery_report_forbidden.