Export messages - Mindo API

curl -s \
  -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.mindosoftware.com/api/v1/qualitative-export/messages?company_id=42&from=2026-04-01T00:00:00Z&to=2026-04-07T00:00:00Z"

{
  "message_id": "msg_a1b2c3d4e5f6a1b2c3d4e5f6",
  "conversation_id": "conv_f6e5d4c3b2a1f6e5d4c3b2a1",
  "occurred_at": "2026-04-05T12:30:45.123456",
  "channel": "META_WHATSAPP",
  "direction": "inbound",
  "author": {
    "type": "contact",
    "id": "ctc_a1b2c3d4e5f6a1b2c3d4e5f6",
    "display_name": null
  },
  "agent": null,
  "content": {
    "type": "text",
    "text": "Hi, I want to check my order status",
    "media_url": null,
    "media_mime": null
  },
  "context": {
    "reply_to_message_id": null,
    "thread_position": null
  },
  "metadata": {
    "client_id": "cmp_d4c3b2a1f6e5d4c3b2a1f6e5",
    "company_id": 42,
    "exported_at": "2026-05-05T18:30:00.000000Z",
    "schema_version": "1.0"
  },
  "classifications": [
    { "label": "Intent", "value": "order_inquiry" }
  ]
}

GET

api

qualitative-export

messages

curl -s \
  -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.mindosoftware.com/api/v1/qualitative-export/messages?company_id=42&from=2026-04-01T00:00:00Z&to=2026-04-07T00:00:00Z"

{
  "message_id": "msg_a1b2c3d4e5f6a1b2c3d4e5f6",
  "conversation_id": "conv_f6e5d4c3b2a1f6e5d4c3b2a1",
  "occurred_at": "2026-04-05T12:30:45.123456",
  "channel": "META_WHATSAPP",
  "direction": "inbound",
  "author": {
    "type": "contact",
    "id": "ctc_a1b2c3d4e5f6a1b2c3d4e5f6",
    "display_name": null
  },
  "agent": null,
  "content": {
    "type": "text",
    "text": "Hi, I want to check my order status",
    "media_url": null,
    "media_mime": null
  },
  "context": {
    "reply_to_message_id": null,
    "thread_position": null
  },
  "metadata": {
    "client_id": "cmp_d4c3b2a1f6e5d4c3b2a1f6e5",
    "company_id": 42,
    "exported_at": "2026-05-05T18:30:00.000000Z",
    "schema_version": "1.0"
  },
  "classifications": [
    { "label": "Intent", "value": "order_inquiry" }
  ]
}

Description

Exports chat messages as an NDJSON (Newline-Delimited JSON) stream for qualitative analysis. All person IDs are automatically anonymized using HMAC-SHA256.

The response is an NDJSON stream (application/x-ndjson), not standard JSON. Each line is an independent JSON object.

Authentication header

X-API-Key

string

required

Your Mindo API Key. Two types are accepted:

Global (cross-company): mindo_global_<key> — access to all companies
Company-scoped: mindo_xxxxxxxxxxxxxxxxxxxxxxxx — limited to the associated company

Query parameters

company_id

string

required

Company ID. Accepts a single integer or comma-separated list: 42 or 42,57.

from

string

required

Start date/time (ISO-8601, inclusive). Example: 2026-04-01T00:00:00Z.

string

required

End date/time (ISO-8601, exclusive). Must be greater than from. Maximum 31-day range.

channel

string

default:"all"

Platform filter: whatsapp, instagram, messenger, all.

agent_id

string

Filter by AI agent. A single integer or CSV list: 5 or 5,12.

direction

string

default:"all"

Message direction: incoming, outgoing, all.

include

string

default:"classifications"

Extra fields to include (CSV): classifications, extractions, tool_calls, trace_id.

cursor

string

Pagination cursor obtained from next_cursor in the previous response.

limit

integer

default:"5000"

Maximum number of rows per call. Range: 1–10000.

Response

The response is an NDJSON stream. Each line is a JSON object with the following fields:

message_id

string

Anonymized message ID (msg_<24 hex chars>).

conversation_id

string

Anonymized chat ID (conv_<24 hex chars>).

occurred_at

string

ISO-8601 timestamp of when the message was sent.

channel

string

Platform: META_WHATSAPP, WHATSAPP_EVOLUTION, INSTAGRAM, MESSENGER, MANYCHAT_WHATSAPP, MANYCHAT_INSTAGRAM.

direction

string

"inbound" (from contact) or "outbound" (from system/agent/operator).

author

object

Who sent the message.

Show Author properties

type

string

Author type: contact, agent, human_operator, system.

string

Anonymized author ID (ctc_, agt_, op_ depending on type). null for system.

display_name

string

Visible author name. Only present for agent.

agent

object

AI agent data (only if the message was generated by an agent).

Show Agent properties

integer

Real AI agent ID (not anonymized).

name

string

Agent name.

version

string

Agent version.

content

object

Message content.

Show Content properties

type

string

Type: text, image, video, audio, file, sticker, location, contact, system, notification_template, carousel, story_mention, story_reply, ice_breaker_response.

text

string

Text content of the message.

media_url

string

Multimedia file URL (if applicable).

media_mime

string

Media MIME type (e.g., image/jpeg).

context

object

Conversation context.

Show Context properties

reply_to_message_id

string

Anonymized ID of the quoted message (msg_<hash>).

thread_position

null

Reserved for future use.

metadata

object

Export data.

Show Metadata properties

client_id

string

Anonymized company ID (cmp_<hash>).

company_id

integer

Real company ID.

exported_at

string

UTC timestamp of when this record was generated.

schema_version

string

Schema version ("1.0").

Optional fields (`include` parameter)

These fields only appear if requested in the include parameter.

classifications

array

Classifications applied to the message (included by default).

Show Classification properties

label

string

Classifier name.

value

any

Classification result.

extractions

array

Data extracted from the message by custom field extractors.

Show Extraction properties

key

string

Custom field name.

value

any

Extracted value.

tool_calls

array

Tools executed by the AI agent during message generation.

Show Tool call properties

tool_name

string

Tool name.

success

boolean

Whether the execution was successful.

execution_time_ms

integer

Execution time in milliseconds.

trace_id

string

Langfuse trace ID for debugging. Only has a value for outgoing messages generated by an AI agent.

Pagination

Pagination is cursor-based. If there are more results, the last line of the stream is a sentinel:

{"_truncated": true, "next_cursor": "<cursor_string>"}

Send the next request with cursor=<next_cursor> to get the next page. When there is no sentinel, all data has been returned.

ID anonymization

Prefix	Represents
`msg_`	Message ID
`conv_`	Conversation ID
`ctc_`	Contact ID
`agt_`	Agent ID (in author)
`op_`	Human operator ID
`cmp_`	Company ID (in metadata)

Anonymization is deterministic per company, irreversible, and consistent across exports.

curl -s \
  -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.mindosoftware.com/api/v1/qualitative-export/messages?company_id=42&from=2026-04-01T00:00:00Z&to=2026-04-07T00:00:00Z"

{
  "message_id": "msg_a1b2c3d4e5f6a1b2c3d4e5f6",
  "conversation_id": "conv_f6e5d4c3b2a1f6e5d4c3b2a1",
  "occurred_at": "2026-04-05T12:30:45.123456",
  "channel": "META_WHATSAPP",
  "direction": "inbound",
  "author": {
    "type": "contact",
    "id": "ctc_a1b2c3d4e5f6a1b2c3d4e5f6",
    "display_name": null
  },
  "agent": null,
  "content": {
    "type": "text",
    "text": "Hi, I want to check my order status",
    "media_url": null,
    "media_mime": null
  },
  "context": {
    "reply_to_message_id": null,
    "thread_position": null
  },
  "metadata": {
    "client_id": "cmp_d4c3b2a1f6e5d4c3b2a1f6e5",
    "company_id": 42,
    "exported_at": "2026-05-05T18:30:00.000000Z",
    "schema_version": "1.0"
  },
  "classifications": [
    { "label": "Intent", "value": "order_inquiry" }
  ]
}

Channel mapping

`channel` parameter value	Included platforms
`whatsapp`	META_WHATSAPP, WHATSAPP_EVOLUTION, MANYCHAT_WHATSAPP
`instagram`	INSTAGRAM, MANYCHAT_INSTAGRAM
`messenger`	MESSENGER
`all`	All platforms

Mid-stream errors

If an error occurs after the stream has already started, it is emitted as an additional NDJSON line:

{"_error": {"code": "ERROR_CODE", "message": "error description"}}

Limits

Restriction	Value
Maximum date range	31 days
Maximum rows per request	10,000
Default rows per request	5,000
Deleted messages	Automatically excluded

Use cases

Agent response quality analysis

Export only outgoing messages from a specific agent with tool_calls to evaluate which tools were used and how successfully:

GET /api/v1/qualitative-export/messages?company_id=42&from=2026-04-01T00:00:00Z&to=2026-04-07T00:00:00Z&agent_id=5&direction=outgoing&include=classifications,tool_calls,trace_id

Training dataset for classifiers

Export incoming messages with their classifications to evaluate or retrain models:

GET /api/v1/qualitative-export/messages?company_id=42&from=2026-04-01T00:00:00Z&to=2026-04-30T00:00:00Z&direction=incoming&include=classifications,extractions

Cross-platform audit

Export all messages from multiple companies for comparative audit:

GET /api/v1/qualitative-export/messages?company_id=42,57&from=2026-04-01T00:00:00Z&to=2026-04-07T00:00:00Z&include=classifications

Agent debugging with Langfuse

Export messages with trace_id to correlate with Langfuse traces:

GET /api/v1/qualitative-export/messages?company_id=42&from=2026-04-05T10:00:00Z&to=2026-04-05T12:00:00Z&include=tool_calls,trace_id

List bulk sends

​Description

​Authentication header

​Query parameters

​Response

​Optional fields (include parameter)

​Pagination

​ID anonymization

​Channel mapping

​Mid-stream errors

​Limits

​Use cases

Description

Authentication header

Query parameters

Response

Optional fields (`include` parameter)

Pagination

ID anonymization

Channel mapping

Mid-stream errors

Limits

Use cases