Conversations

Export conversations

Export conversation metadata and public transcript text with your platform API key.

GET/v2/agents//conversations/export

Authenticate with the platform API key and put agent_id in the URL path.

Export behavior

Each item represents one thread. It preserves the information in the dashboard CSV and organizes related values into JSON objects. thread_id identifies the row; conversation_id identifies its parent conversation. Separate threads remain separate rows.

The response includes customer threads across API, widget, standalone and connected messaging channels, including groups and inactive or historical channels. Playground data, deleted resources, private notes, system events and replies still generating are excluded.

Response structure

FieldContents
channelid, type, name
contactid, identifier, name, email, phone_number
assigneeAssigned teammate's id and name
csatCustomer's rating and comment
topicsArray of objects with id and title
messagesArray of messages with id, role, content_text, created_at

Contact fields come from the profile recorded in that channel, matching CSV. A contact's global profile can differ. Missing or inaccessible contacts, unassigned teammates and unanswered CSAT are null; a known contact with an incomplete profile retains its id and has null for unavailable fields. No topics gives []. Counts and ratings are numbers; timestamps are UTC ISO 8601.

The CSV remains flat. For example, its channel_name maps to channel.name, contact_email to contact.email, and csat_comment to csat.comment. topics preserves each title separately, including punctuation. CSV cell escaping and semicolon joining do not apply to JSON.

Filter conversations

Use thread_id for one CSV row, conversation_id for the threads of one parent conversation, channel_id for one channel, or contact_identifier for the identifier recorded in that channel. Filters combine. An inaccessible thread, conversation or channel returns an empty list; an inaccessible agent returns 404.

start_date is inclusive and end_date is exclusive. Both require ISO 8601 date-times with a timezone, for example 2026-10-01T00:00:00Z through 2026-11-01T00:00:00Z for October. They filter thread creation time, matching the CSV row. Date-only or timezone-free values are rejected.

Message text

include=messages is the default. Each message contains only id, role (user, assistant, operator), content_text and created_at. Messages belong to the row's thread and are ordered oldest first. Stored captions or transcripts are included when available; a message without text has an empty content_text. Attachments, parts and internal model/tool metadata are not exported.

Use include=summary for CSV metadata without message bodies. The summary field always means the thread's stored summary; the include option only controls whether messages are fetched.

Pagination and limits

Each page returns up to 20 complete threads. Every thread includes all its eligible public messages in one messages array. Set limit to request fewer threads. The endpoint allows 30 requests per minute per organization; use Retry-After to retry a 429 response.

Without query parameters, you receive the 20 newest threads with include=messages. Threads are sorted by created_at DESC, then by internal ID descending. Each thread's messages remain oldest first. The next page contains older threads; recent activity does not change a thread's position.

Follow pagination.next_cursor until has_more is false to retrieve the remaining threads. Each thread and its messages arrive together; no transcript merging is needed. See Pagination for ordering and consistency.

Complete Python export

Install requests and set MUCHAT_PLATFORM_API_KEY and MUCHAT_AGENT_ID. The example writes one complete thread as JSON per line and retries temporary rate limits. Run python export.py > conversations.jsonl to save the export without keeping every page in memory.

export.py
import json
import os
import time
from urllib.parse import quote

import requests

agent_id = quote(os.environ["MUCHAT_AGENT_ID"], safe="")
url = f"https://api.mu.chat/v2/agents/{agent_id}/conversations/export"
params = {"limit": 20}
headers = {"Authorization": f"Bearer {os.environ['MUCHAT_PLATFORM_API_KEY']}"}
retry_count = 0

while True:
    response = requests.get(url, params=params, headers=headers, timeout=60)
    if response.status_code in (429, 503) and retry_count < 5:
        time.sleep(int(response.headers.get("Retry-After", "5")))
        retry_count += 1
        continue
    response.raise_for_status()
    retry_count = 0
    page = response.json()
    for thread in page["data"]:
        print(json.dumps(thread, ensure_ascii=False))
    if not page["pagination"]["has_more"]:
        break
    params["cursor"] = page["pagination"]["next_cursor"]

Authentication

Authorizationstringheaderrequired
Platform API key from Settings → Developer → API keys. The agent in the URL must belong to the same organization.

Authenticate with a Bearer token in this format: Bearer <token>

Path Parameters

agent_idstringrequired
Agent ID in the platform key’s organization. Supply it in the URL path.
Example: YOUR_AGENT_ID

Query Parameters

channel_idstring | null
Optional channel UUID; omit to include all customer channels.
Format: uuid
conversation_idstring | null
Optional parent conversation UUID; includes its matching threads.
Format: uuid
thread_idstring | null
Optional thread UUID; matches thread_id in the CSV export.
Format: uuid
contact_identifierstring | null
Exact identifier from the contact’s channel snapshot, as in CSV.
Maximum length: 255
start_datestring | null
Inclusive thread creation time; ISO 8601 with timezone.
Format: date-time
end_datestring | null
Exclusive thread creation time; ISO 8601 with timezone.
Format: date-time
cursorstring | null
Opaque next_cursor from the previous response; keep all filters unchanged.
Maximum length: 2048
limitinteger
Maximum complete threads per response (1–20).
Maximum: 20
Minimum: 1
Default: 20
includeenum<string>
messages includes public transcript text; summary skips reading messages.
Available options: messagessummary
Default: messages

Response

– application/json
Successful Response
dataobject[]required
Show child attributes
thread_idstringrequired
Public thread UUID, identical to the CSV thread_id. Each thread appears once with its complete public transcript.
Format: uuid
conversation_idstringrequired
Public UUID of the parent conversation. Different threads can share this ID.
Format: uuid
statusenum<string>required
Status of this thread.
Available options: openpendingresolvedsnoozed
created_atstringrequired
Thread creation time in UTC. Date filters apply to this field.
channelobjectrequired
Channel identity, type and name.
Show child attributes
idstringrequired
Public channel UUID; usable as the channel_id filter.
Format: uuid
typestringrequired
Channel type, such as api, widget or telegram.
namestring | nullrequired
Channel name.
contactobject | nullrequired
Contact identity and profile recorded in this channel. null when the contact or connection is missing, deleted or outside this agent.
Show child attributes
idstringrequired
Public contact UUID.
Format: uuid
identifierstring | nullrequired
Identifier recorded in this channel, matching the CSV contact_identifier.
namestring | nullrequired
Name recorded in this channel.
emailstring | nullrequired
Email recorded in this channel.
phone_numberstring | nullrequired
Phone number recorded in this channel.
assigneeobject | nullrequired
Assigned teammate, or null when unassigned.
Show child attributes
idstringrequired
Assigned teammate’s user ID.
namestring | nullrequired
Assigned teammate’s name.
csatobject | nullrequired
Customer satisfaction response, or null when unanswered. Internal review notes are excluded.
Show child attributes
ratingintegerrequired
Customer satisfaction rating.
commentstring | nullrequired
Customer’s written feedback, or null when absent.
topicsobject[]required
Active topics ordered by title and ID. Empty array when no topics match; archived, pending and merged topics are excluded.
Show child attributes
idstringrequired
Public topic UUID.
Format: uuid
titlestringrequired
Complete topic title. Punctuation and separators remain part of the title.
contact_message_countintegerrequired
Stored count of contact messages in the thread, identical to CSV.
sentimentstring | nullrequired
Thread sentiment, or null when unavailable.
summarystring | nullrequired
Summary of this thread, or null when unavailable.
thread_urlstringrequired
Dashboard inbox URL for this thread.
messagesobject[] | null
All eligible public messages in this thread, oldest first. An empty array means no eligible messages; null when include=summary.
Show child attributes
idstringrequired
Public message UUID. Use it to deduplicate retries.
Format: uuid
roleenum<string>required
Message author: customer, AI assistant or human operator.
Available options: userassistantoperator
content_textstringrequired
Stored message text, including available captions or transcripts. Empty when the message has no text. Attachments and parts are not exported.
created_atstringrequired
Message creation time in UTC.
paginationobjectrequired
Show child attributes
has_morebooleanrequired
next_cursorstring | nullrequired
snapshot_atstringrequired
UTC creation-time watermark fixed on the first page. Not a transactional database snapshot.
MuChat documentation