Reports API

Authentication and date filters

Reports require an agent-session JWT. Results are scoped to the caller; report families also check product/channel permissions. Product API keys do not grant access.

Supported range tokens are today, yesterday, last7d (default), last30d, last_month and current_month. Valid from/to timestamps override the token. The interval is [from, to). Invalid tokens or invalid custom ranges fall back to the default; validate your input before sending it. The response range has from, to, label and days.

departmentId and agentId filters apply where supported. Setting a filter does not expand your permissions. Time-series endpoints support grain; do not assume all endpoints share the same response shape.

Conversation volume

GET /api/v1/reports/chats/total returns total, series, grain, heatmap and range. GET /api/v1/reports/tickets/total returns total, byDay, grain, heatmap and range. Do not use a generic series parser for both.

GET /api/v1/reports/conversations provides the underlying scoped records. Use the response-time tutorial below for a complete request and response example.

curl 'https://app.message.com/api/v1/reports/chats/total?range=last7d' \
  -H "Authorization: Bearer $MESSAGE_AGENT_TOKEN"

Ticket response times and satisfaction

GET /api/v1/reports/tickets/response-times returns rows and range. Each row contains agentId, name, firstResponseSecP50, firstResponseSecP95, resolutionSecP50, resolutionSecP95 and ticketsHandled. Durations are elapsed seconds; closed hours are included. Missing measurements are null.

GET /api/v1/reports/tickets/satisfaction returns totalRated, positive, negative, avgCsat, satisfactionScore, comments, byDay and range. Satisfaction score is a percentage (0–100), while avgCsat is the numeric rating average. They are not interchangeable.

Agent performance

GET /api/v1/reports/agents/performance returns rows, dataLogged and range. Rows include agentId, name, chats, tickets, calls, total, chatsHandled (legacy alias for total), avgResponseSec, avgCsat, ratedCount and hoursOnline. avgResponseSec is a mean, not a median. dataLogged.hoursOnline tells you whether online-session records were available.

Download CSV

GET /api/v1/reports/export streams CSV directly with a Content-Disposition attachment filename. It does not return a signed download URL. Only format=csv is supported. type defaults to conversations; unsupported types return 400 unsupported_type with the supported list. Other formats return 400 unsupported_format.

Exports retain caller scoping and channel checks. Messaging exports require an administrator or supervisor. Store downloaded files securely: they may contain customer data.

curl --fail-with-body 'https://app.message.com/api/v1/reports/export?type=conversations&range=last30d&format=csv' \
  -H "Authorization: Bearer $MESSAGE_AGENT_TOKEN" \
  --output conversations.csv