Skip to content

API and SDK

History

Conversations, contacts and messages stored by Messajo: filters, cursor pagination and how retention limits the time range.

Messajo stores what goes through the connections and lets you query it through the API with the read permission. Everything respects the key’s connections: a key restricted to some connections only sees what belongs to them.

Route Filters Order
GET /v1/conversations connection_id, contact_id, window=open|closed, since, until (on last_message_at) most recent last_message_at first
GET /v1/conversations/{id}/messages direction, type, since, until, order=desc|asc created_at
GET /v1/messages connection_id, contact_id, conversation_id, direction, status, type, source, campaign_id, since, until, order created_at
GET /v1/contacts connection_id, channel, identity, q, since most recent last_seen_at first

Each one has a by-id version (GET /v1/conversations/{id}, GET /v1/messages/{id}, GET /v1/contacts/{id}). Dates in ISO 8601.

  • identity is an exact match on phone number (digits only), BSUID, Instagram @username, IGSID or PSID.
  • q matches the start of the contact’s name (up to 64 characters).
  • source says where the message came from: customer (the contact), api, campaign, business_app (the phone app, under coexistence) or history (imported history); campaign_id returns only the messages of one campaign.
  • Media shows up as part of the message, with an id. The file is at GET /v1/media/{id}/content.

Every list returns { data, next_cursor }. Pass limit (up to 100) and, for the next page, the next_cursor you received as cursor. You are done when next_cursor is null.

Janela do terminal
curl "https://api.messajo.com/v1/messages?conversation_id=cnv_...&limit=100" \
-H "Authorization: Bearer $MESSAJO_API_KEY"
{
"data": [
{
"id": "msg_...",
"conversation_id": "cnv_...",
"contact_id": "ctc_...",
"direction": "inbound",
"type": "text",
"text": { "body": "Hi! Is the coupon still valid?" },
"source": "customer",
"status": "received",
"campaign": null,
"created_at": "2026-11-10T14:03:11.000Z"
}
],
"next_cursor": "eyJ2IjoxLCJrIjpbIjIwMjYtMTEtMTBUMTQ6MDM6MTEuMDAwWiIsIm1zZ18uLi4iXX0"
}
  • The cursor is opaque: do not build or change it. A broken cursor → 400 invalid_cursor.
  • The cursor stores a position, not a snapshot of the list: what arrives later does not duplicate or skip items already read.
  • Use the same filters on every page.

With the SDK, paginate follows the cursor for you:

for await (const message of messajo.paginate(messajo.messages.list, {
conversation_id: "cnv_...",
})) {
console.log(message.id);
}

Messages are stored by month. Every message query has a since/until range:

  • without since, the start of the organization’s retention applies (90 days by default); without until, now;
  • a since older than the retention is clamped to the limit, without an error: whatever passed the deadline has already been deleted;
  • short ranges respond faster.

Retention counts from when the data was stored in Messajo. The 6 months of history imported under coexistence are stored on the import day and leave together with the rest when the deadline passes.