API Pública de Engage Campaigns - Documentação

A API Pública do Engage oferece acesso programático aos dados de campanhas de engajamento enviadas por canais de WhatsApp. Ela permite que desenvolvedores integrem recursos de relatórios, análise e exportação de dados de campanhas em seus aplicativos e sistemas empresariais.

Principais recursos:

Listagem de Campanhas: acesso ao catálogo completo de campanhas dentro de um intervalo de datas, com filtros por tipo de execução (one-time ou recurrent).
Detalhes da Campanha: informações detalhadas por contato individual, incluindo status de entrega, leitura e interação, com suporte a paginação.
Resumo de Métricas: estatísticas agregadas por campanha com percentuais de leitura, interação e erro.
Estatísticas Globais: métricas consolidadas do bot segmentadas por frequência temporal (diária ou semanal).
Exportação de Dados: download do detalhamento de campanhas em formato CSV.

URL Base: https://analytics-engage.agentbot.net

Autenticação: todas as requisições à API exigem dois headers de autenticação.

Header	Tipo	Descrição
X-Token	Token fixo	Identificador do bot (BotID). Define o contexto dos dados a consultar
Authorization	Bearer JWT	Token JWT de sessão do usuário autenticado (formato Bearer)

> Exemplo de Headers

^{X-Token: eExNcFRrUmtOVFJsWkRKa01HRTNaalZrT0dGaFl6...}

^{Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...}

^{Content-Type: application/json}

Nota: o token JWT tem prazo de expiração. Renove-o antes que expire para evitar respostas `401 Unauthorized`. O JWT é obtido por autenticação OAuth junto ao provedor de identidade (Auth0).

Formato de Resposta: as respostas são retornadas em formato JSON por padrão. O endpoint `/campaign/{name}/details` também suporta exportação em CSV usando o parâmetro `output=csv`.

Formato	Content-Type	Aplica-se a
JSON	application/json	Todos os endpoints (padrão)
CSV	text/csv; charset=utf-8	`/campaign/{name}/details` apenas (com `output=csv`)

Parâmetros Comuns

↗️ Parâmetros de Data: a maioria dos endpoints exige um intervalo de datas como query parameters.

Parâmetro	Tipo	Formato	Descrição
from	string	YYYY-MM-DD HH:MM:SS (UTC)	Data e hora de início
to	string	YYYY-MM-DD HH:MM:SS (UTC)	Data e hora de fim

> Exemplo

^{from=2026-04-01 00:00:00
to=}^{2026-04-10 23:59:59}

Nota: os valores devem estar URL-encoded na query string (espaços como , dois-pontos como : )

Filtros Comuns:

Parâmetro	Tipo	Valores permitidos	Descrição
type	string	one-time, recurrent	Filtra campanhas por tipo de execução

Endpoints Disponíveis:

Método	Endpoint	Descrição	from/to	Filtros opcionais
GET	/campaigns	Listagem de campanhas do bot	SIM	type
GET	/campaign/{name}/details	Detalhamento por contato (paginado, exportável em CSV)	SIM	type, output, limit, offset
GET	/campaign/{name}/summary	Resumo de métricas agregadas de uma campanha	SIM
GET	/stats	Estatísticas globais segmentadas por frequência	SIM	frequency, type

Limites de Consulta

Endpoint	Restrição
/campaign/{name}/details	Intervalo máximo de 90 dias entre `from` e `to`
/campaign/{name}/details	LImite máximo de 10.000 registros por requisição

Códigos de status HTTP

Código	Descrição
200	Requisição bem-sucedida
400	Requisição malformada (parâmetros inválidos ou ausentes)
401	Não autenticado (token inválido ou expirado)
403	Não autorizado (sem permissão para o recurso solicitado)
404	Recurso não encontrado (campanha inexistente)
500	Erro interno do servidor

Pela API, você pode obter as informações dos campos abaixo. Para saber como fazer isso, clique nos links de cada título:

GETSummary: retorna as métricas agregadas e o resumo estatístico de uma campanha dentro de um intervalo de datas.
GET Stats: retorna métricas consolidadas de mensagens para um bot dentro de um intervalo de datas. Os dados são segmentados conforme o parâmetro de frequência.
GET Campaigns: retorna a listagem de campanhas para um bot específico dentro de um intervalo de datas.
GET Details: retorna informações detalhadas por contato individual para uma campanha específica. Suporta paginação e exportação em CSV.