message.comDevelopers
Developers/Tutorials/Export conversation data

Export conversation data

Download conversations and messages for warehousing, compliance audits, or external analytics. Three flavours: a full workspace export, a per-conversation export, or a programmatic pull with pagination over the conversations API.

Full workspace export

The reports export endpoint returns CSV only, for the date range and record type you ask for.

bash
curl -X GET 'https://app.message.com/api/v1/reports/export?range=last30d&type=conversations&format=csv' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT' \
  -o conversations-30d.csv

Query params:

  • range. today, yesterday, last7d, last30d, last_month, or current_month. For a custom interval pass valid ISO from and to timestamps.
  • type. One of conversations, tickets, calls, tags, satisfaction, agents, agent-activity, campaigns, messaging. There is no messages or visitors type.
  • format. csv is the only supported value; anything else returns 400 unsupported_format.

Export another record type

Same endpoint, different type. There is no separate messages export and no JSON option here.

bash
curl -X GET 'https://app.message.com/api/v1/reports/export?range=last30d&type=tickets&format=csv' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT' \
  -o tickets-30d.csv

Export a single conversation

For a single record (compliance request, customer asks for their data), use the conversation-level export instead, which is JSON, not CSV:

bash
curl -X GET 'https://app.message.com/api/v1/conversations/:id/export?format=json' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT' \
  -o conversation-12345.json

Returns the conversation record directly in the response body (no signed URL), including tags, rating, and visitor info. PDF is not implemented; only format=json works today.

Programmatic pull

For incremental record-level fetches into a warehouse, use the reports drill-down list rather than the CSV export, which is meant for one-shot downloads, not paging:

bash
curl 'https://app.message.com/api/v1/reports/conversations?limit=200' -H 'Authorization: Bearer YOUR_WORKSPACE_JWT'

This endpoint is offset-paginated (limit / offset, capped at 500), not cursor-paginated: there is no nextCursor here.

Schedule

A few cron-job patterns:

  • Weekly archive. Sunday night, export the past week to S3 with the date in the filename.
  • Monthly compliance. First of the month, export the prior month, encrypt with GPG, store off-site.
  • Continuous to warehouse. Export a bounded date range and upsert by conversation ID. This report endpoint has offset pagination, not an incremental change cursor.

Common pitfalls

  • JWT lifetime. These report exports require an authorized agent session. Do not assume a Verify or iMessage key can read reports. Handle expired sessions explicitly; use the documented MCP read tools for supported external-agent access.
  • Large exports timeout client-side. Use streaming HTTP clients (curl, Python requests.get(stream=True), Node fetch with response body iteration). Loading the whole response in memory will OOM on 1GB+ exports.
  • PII handling. Exports include visitor emails, names, custom attributes. Store accordingly.
  • Time zone. All timestamps in exports are UTC ISO 8601. Convert at consumption time.

Next steps