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=90d&type=conversations&format=csv' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT' \
  -o conversations-90d.csv

Query params:

  • range. 7d | 30d | 90d | custom (with from and to).
  • 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=90d&type=tickets&format=csv' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT' \
  -o tickets-90d.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. Every 15 minutes, pull conversations modified since last cursor, upsert into Snowflake / BigQuery / Postgres.

Common pitfalls

  • JWT lifetime. Workspace JWTs expire in 7 days. For long-running cron jobs, refresh the token or wait for API keys (planned).
  • 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