Conversations

All endpoints on this page use your API key in the x-api-key header. The full endpoint list is on the Direct Messages overview.

List Conversations

Endpoint: GET /api/v1/conversations Query params:

teamId (required)
platform (optional) - INSTAGRAM or FACEBOOK
socialAccountId (optional)
status (optional) - OPEN or ARCHIVED
limit (max 500), and either offset or cursor

Conversations come back with the most recent activity first.

curl "https://api.bundle.social/api/v1/conversations?teamId=team_123&status=OPEN&limit=20" \
  -H "x-api-key: YOUR_KEY"

{
  "items": [
    {
      "id": "conv_abc",
      "teamId": "team_123",
      "socialAccountId": "sa_789",
      "platform": "INSTAGRAM",
      "externalConversationId": "aWdfdGhyZWFk...",
      "externalParticipantId": "1789000000000000",
      "participantUsername": "janedoe",
      "participantDisplayName": "Jane Doe",
      "participantAvatarUrl": "https://...",
      "status": "OPEN",
      "lastMessageAt": "2026-09-26T09:30:00.000Z",
      "lastActivityAt": "2026-09-26T09:30:00.000Z",
      "lastMessagePreview": "Hi! Do you ship to Poland?",
      "lastReadAt": null,
      "unreadCount": 1,
      "platformSeenAt": null,
      "platformData": {
        "lastInboundAt": "2026-09-26T09:30:00.000Z"
      },
      "socialAccount": { "id": "sa_789", "type": "INSTAGRAM", "username": "mybrand" },
      "createdAt": "2026-09-26T09:30:00.000Z",
      "updatedAt": "2026-09-26T09:30:00.000Z"
    }
  ],
  "total": 1,
  "nextCursor": "eyJ0IjoiMjAyNi0wOS0yNlQwOTozMDowMC4wMDBaIiwiaWQiOiJjb252X2FiYyJ9"
}

Useful fields:

unreadCount / lastReadAt - your side’s read state, see Mark As Read.
platformSeenAt - when the participant last read your messages.
lastActivityAt - what the list is sorted by.
platformData.lastInboundAt / canReply - the 24-hour rule.
socialAccount - the connected account the conversation belongs to.
externalConversationId / externalParticipantId - the platform’s own IDs for the thread and the person.

GET /api/v1/conversations/:id returns the same object for a single conversation.

Pagination

Both list endpoints support two styles, pick one per request:

Offset: offset + limit. Simple, good for page numbers.
Cursor: pass the previous response’s nextCursor back as cursor. For messages it stays stable while new ones keep arriving, so this is what you want for infinite scroll.

The conversation list is sorted by lastActivityAt, which changes with every new message. A conversation that gets a new message while you page through the list moves to the top, so it can be missing from later pages. Refresh the first page (or use webhooks) to catch it. limit defaults to 10 (max 500). total is only returned on the first page (when you don’t send a cursor). Sending a cursor together with a non-zero offset returns 400. When nextCursor is empty, you’ve reached the end.

Read Messages

Endpoint: GET /api/v1/conversations/:id/messages Pages walk backwards in time (the first page has the newest messages), but messages inside a page are ordered oldest first, so you can render them top to bottom without sorting.

{
  "items": [
    {
      "id": "msg_1",
      "conversationId": "conv_abc",
      "teamId": "team_123",
      "socialAccountId": "sa_789",
      "platform": "INSTAGRAM",
      "direction": "INBOUND",
      "status": "DELIVERED",
      "source": "DM",
      "externalMessageId": "aWdfZG1faWQ...",
      "text": "Hi! Do you ship to Poland?",
      "attachments": [],
      "sentAt": "2026-09-26T09:30:00.000Z",
      "seenAt": null,
      "failedAt": null,
      "error": null,
      "replyTo": null,
      "privateReplyContext": null,
      "platformData": {},
      "createdAt": "2026-09-26T09:30:01.000Z",
      "updatedAt": "2026-09-26T09:30:01.000Z"
    },
    {
      "id": "msg_2",
      "conversationId": "conv_abc",
      "platform": "INSTAGRAM",
      "direction": "OUTBOUND",
      "status": "SEEN",
      "source": "API",
      "text": "We do! Shipping takes 2-3 days.",
      "attachments": [],
      "sentAt": "2026-09-26T09:31:10.000Z",
      "seenAt": "2026-09-26T09:32:00.000Z",
      "replyTo": { "messageId": "msg_1", "externalMessageId": "aWdf...", "isSelfReply": false },
      "platformData": {
        "reactions": [{ "senderId": "1789000000000000", "reaction": "love", "emoji": "❤️" }]
      }
    }
  ],
  "total": 2,
  "nextCursor": null
}

Useful fields:

attachments[] - type (IMAGE, VIDEO, AUDIO, FILE, POST, UNKNOWN) and a url when the platform gives one. POST is shared content on Messenger (a link or a shared post). On Instagram, shared posts, reels and story mentions currently arrive as UNKNOWN, with a url when Meta provides one.
replyTo - set when the message is a reply to an earlier one. messageId points to our message if we have it.
privateReplyContext - for private replies: the comment it answered (text, authorName, postPermalink, postThumbnailUrl, …).
platformData.reactions - reactions on the message.
platformData.isEdited / editedAt - the participant edited their message. text already holds the new version.
platformData.isUnsent / unsentAt - the participant unsent it. We clear text and attachments on our side. If you stored the content from an earlier webhook, delete or hide your copy too.
platformData.quickReplies, buttons, carousel - the rich content of messages you sent.
platformData.isPostback / postbackPayload - the participant tapped a POSTBACK button, an ice breaker or a menu item, and this is the payload behind it.
platformData.isEcho - the account owner sent this from the Instagram or Messenger app.
error / failedAt - why and when an outbound message failed.

Platform-hosted attachment URLs (images someone sent you) are signed by Meta and expire. If you need them long-term, download and store them yourself.

Mark As Read

Endpoint: POST /api/v1/conversations/:id/read

{ "readAt": "2026-09-26T09:35:00.000Z" }

readAt is optional (defaults to now). It resets unreadCount and also tries to show the participant a “seen” marker on the platform. That marker is best effort: it’s skipped when messaging isn’t enabled for the account or sending is paused on our side, and a platform error doesn’t fail the call. If you send a readAt older than the last message, we only move lastReadAt and keep the counter, since you hadn’t seen the newest message at that point.

Archive And Reopen

POST /api/v1/conversations/:id/archive - move it out of the active inbox,
POST /api/v1/conversations/:id/open - bring it back,
PATCH /api/v1/conversations/:id with { "status": "ARCHIVED" } - same thing, generic form.

Archiving is a bundle.social inbox state, it doesn’t archive the thread inside Instagram or Messenger. A new incoming message reopens an archived conversation automatically, so nobody gets lost in the archive.

API Documentation

Platforms

Guides

Endpoints

List Conversations

Read Messages

Mark As Read

Archive And Reopen

​List Conversations

​Pagination

​Read Messages

​Mark As Read

​Archive And Reopen

List Conversations

Pagination

Read Messages

Mark As Read

Archive And Reopen