Skip to main content

​
O que são os relatórios operacionais

Os relatórios operacionais expõem eventos em nível de linha do seu workspace no endpoint GET /v1/reports/{report}. Diferente do analytics agregado, aqui cada linha é um evento individual — pronto para investigação, auditoria ou reconciliação no seu próprio destino. O primeiro relatório é o message_errors: as falhas de entrega de mensagens no WhatsApp (webhooks de status failed da Cloud API da Meta), com o código e a descrição do erro reportado pela Meta.
Cada relatório reutiliza o mesmo motor de paginação por cursor da exportação de entidades: mesmo envelope { data, next_cursor, count }, mesma semântica de upsert por id, mesma chave de acesso do workspace.

​
Janela de tempo obrigatória

Ao contrário da exportação de entidades, o relatório message_errors exige uma janela de tempo limitada. Você informa updated_since (limite inferior, inclusivo) e, opcionalmente, to (limite superior; padrão: agora).
updated_since é obrigatório em message_errors. Uma chamada sem ele é rejeitada com 400. A janela (to − updated_since) não pode exceder 31 dias — para períodos maiores, faça várias chamadas em janelas consecutivas.
A janela mantém o relatório rápido e previsível — por isso o teto de 31 dias.

​
Como paginar

1

Defina a janela

Escolha updated_since (e opcionalmente to), respeitando o teto de 31 dias. Use o timestamp da última sincronização como updated_since.
2

Puxe a primeira página

Chame GET /v1/reports/message_errors?updated_since=<ISO 8601>. Aplique os filtros que precisar (deal_id, conversation_id, agent_id, external_id, error_code).
3

Grave e pagine

Faça upsert por id das linhas de data. Se next_cursor não for null, chame de novo passando cursor=<next_cursor> até next_cursor retornar null.
4

Avance a janela

Na próxima sincronização, use como updated_since o maior cursor_at já processado. Para varrer um histórico longo, itere janelas de até 31 dias.

​
Filtros do relatório

Os filtros abaixo são ANDados após o escopo do workspace. Chaves de filtro desconhecidas são simplesmente ignoradas.
Os filtros por índice (deal_id, conversation_id) são os mais eficientes: eles ajudam a podar a consulta cedo. external_id e error_code são filtros residuais — úteis, mas aplicados sobre as linhas com falha da janela.
O significado de cada coluna retornada está na referência do endpoint Falhas de mensagens.
recipient_id é o telefone do seu cliente final (E.164). Ele é liberado porque o dado de contato é do seu workspace — mas é PII: trate-o com o mesmo cuidado dos demais dados de contato ao gravar e compartilhar.

​
Referência e playground

Consulte Falhas de mensagens para todos os parâmetros, formatos de resposta e códigos de erro — e para testar a chamada direto no playground.