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.
Routes
Section titled “Routes”| 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.
identityis an exact match on phone number (digits only), BSUID, Instagram @username, IGSID or PSID.qmatches the start of the contact’s name (up to 64 characters).sourcesays where the message came from:customer(the contact),api,campaign,business_app(the phone app, under coexistence) orhistory(imported history);campaign_idreturns only the messages of one campaign.- Media shows up as part of the message, with an
id. The file is atGET /v1/media/{id}/content.
Cursor pagination
Section titled “Cursor pagination”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.
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 →
400invalid_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);}Time range and retention
Section titled “Time range and retention”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); withoutuntil, now; - a
sinceolder 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.