Skip to content

List conversations API

The List conversations API lists DM conversations for a connected account. Use it to retrieve conversation identifiers, participants, the most recent message, and update times before opening a specific conversation or sending a message. Instagram connections require instagram_business_manage_messages for Instagram Login or instagram_manage_messages for Facebook Login. Twitter/X connections require the dm.read scope, and conversations are derived from recent DM events.

List conversations API — operation summary, supported platforms and permission requirements

This endpoint returns the direct-message threads belonging to one linked social account. Before calling it, confirm the link carries the messaging permission that matches the platform in use. For Instagram, that permission is instagram_business_manage_messages when the account was linked through Instagram Login, and instagram_manage_messages when it was linked through Facebook Login. For Twitter/X, the link needs the dm.read scope, and the threads returned are built from recent DM events rather than from a separate conversation store. A typical workflow is to call this endpoint first, pick a thread using its id, participants and lastMessage preview, and then load that thread's messages or compose a reply.

Authorization: x-access-key header

Send the access key in the x-access-key header. The header name is x-access-key and the value is the token. Include this header on every request to this endpoint.

Query parameters: platform, accountId, limit, after

The request uses GET {{API_BASE_URL}}/v1/messages/ with query parameters. The platform parameter is required and must be instagram or twitter. The accountId parameter is required and is the integration ID of the connected account. The limit parameter is optional, is an integer, defaults to 20, and must be between 1 and 100 inclusive. The after parameter is optional and is a string pagination cursor from a previous response. See the Query parameters table for the complete input contract.

Response body field map

A successful 200 response returns success, selfId, selfUsername, a conversations array, and nextCursor. Each conversation contains id, participants, lastMessage, and updatedTime. Each participant contains id, name, username, and profilePictureUrl. The lastMessage field carries the most recent message in the conversation and can be null; when present it contains id, text, from, and timestamp. The nextCursor field is used for pagination: pass its value as the after parameter on the next request. See the Response field map table for exact names, types, and requiredness, and the 200 success response example for a worked payload.

200 application/json success response

The 200 application/json response contains success set to true, selfId as a string, selfUsername as a string or null, the conversations array, and nextCursor as a string or null. Each conversation object contains id as a string, participants as an array of participant objects, lastMessage as an object or null, and updatedTime as a string or null in date-time format. Participant objects contain id, name, username, and profilePictureUrl, each a string or null. When lastMessage is an object, it contains id as a string, text as a string or null, from as an object with id and name as strings or null, and timestamp as a string or null in date-time format. See the 200 success response example for the full shape.

400 application/json error response

The 400 application/json response uses the documented body shape containing success and message. The source documents the status code and body shape without describing a specific trigger for this status, so do not assume a particular cause. Check the request parameters against the Query parameters table, including the platform enum, the required accountId, and the limit range, before retrying.

402 application/json error response

The 402 application/json response uses the documented body shape containing success and message. The source documents the status code and body shape without describing a specific trigger for this status, so do not assume a particular cause. Record the status and message for diagnosis rather than inventing a retry rule.

403 application/json error response

The 403 application/json response uses the documented body shape containing success and message. The source documents the status code and body shape without describing a specific trigger for this status, so do not assume a particular cause. Verify the x-access-key header and the platform permission requirements for the connected account before retrying.

404 application/json error response

The 404 application/json response uses the documented body shape containing success and message. The source documents the status code and body shape without describing a specific trigger for this status, so do not assume a particular cause. Verify the accountId value and the request path before retrying.

502 application/json error response

The 502 application/json response uses the documented body shape containing success and message. The source documents the status code and body shape without describing a specific trigger for this status, so do not assume a particular cause. Record the status and message for diagnosis rather than inventing a retry rule.

Query parameters
ParameterRequiredTypeConstraintsDescription
platformYesstring"instagram" | "twitter"Platform to fetch conversations from.
accountIdYesstring—Integration ID of the connected account.
limitNointegerDefault 20; 1 <= value <= 100Max conversations to return.
afterNostring—Pagination cursor from a previous response.

Exact source contract; origin shown as {{API_BASE_URL}}.

200 response field map
FieldRequiredTypeDescription
successYesboolean—
selfIdYesstringParticipant ID of the connected account in conversations.
selfUsernameYesstring | nullUsername of the connected account.
conversationsYesarray<object>—
conversations[].idYesstringPlatform conversation ID
conversations[].participantsYesarray<object>—
conversations[].participants[].idYesstring | null—
conversations[].participants[].nameYesstring | null—
conversations[].participants[].usernameYesstring | null—
conversations[].participants[].profilePictureUrlYesstring | nullTemporary Instagram profile picture URL.
conversations[].lastMessageYesobject | nullMost recent message in the conversation.
conversations[].lastMessage.idYesstringPlatform message ID
conversations[].lastMessage.textYesstring | null—
conversations[].lastMessage.fromYesobject—
conversations[].lastMessage.from.idYesstring | null—
conversations[].lastMessage.from.nameYesstring | null—
conversations[].lastMessage.timestampYesstring | null (date-time)—
conversations[].updatedTimeYesstring | null (date-time)—
nextCursorYesstring | nullPass as after in the next request to paginate.

Exact source contract for the 200 response.

Response status matrix
StatusContent typeBody fields
200application/jsonsuccess (boolean), selfId (string), selfUsername (string | null), conversations (array<object>), nextCursor (string | null)
400application/jsonsuccess (boolean), message (string)
402application/jsonsuccess (boolean), message (string)
403application/jsonsuccess (boolean), message (string)
404application/jsonsuccess (boolean), message (string)
502application/jsonsuccess (boolean), message (string)

Status codes and body shape only; no error meanings documented in source.

List conversations request example
curl -X GET "{{API_BASE_URL}}/v1/messages/?platform=instagram&accountId=string" -H "x-access-key: <token>"
200 success response example
{
  "success": true,
  "selfId": "string",
  "selfUsername": "string",
  "conversations": [
    {
      "id": "string",
      "participants": [
        {
          "id": "string",
          "name": "string",
          "username": "string",
          "profilePictureUrl": "string"
        }
      ],
      "lastMessage": {
        "id": "string",
        "text": "string",
        "from": {
          "id": "string",
          "name": "string"
        },
        "timestamp": "2019-08-24T14:15:22Z"
      },
      "updatedTime": "2019-08-24T14:15:22Z"
    }
  ],
  "nextCursor": "string"
}
Error response body shape for 400, 402, 403, 404 and 502
{
  "success": true,
  "message": "string"
}
Pagination request using nextCursor as after
curl -X GET "{{API_BASE_URL}}/v1/messages/?platform=instagram&accountId=string&limit=20&after=<nextCursor>" -H "x-access-key: <token>"
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
platform#1platformstring__0YesPlatform to fetch conversations from.kind: schemaValueIn; value: "instagram" | "twitter"
accountId#2accountIdstring__0YesIntegration ID of the connected account.
limit#3limitinteger__0NoMax conversations to return.kind: schemaDefault; value: 20 | kind: schemaRange; value: 1 <= value <= 100
after#4afterstring__0NoPagination cursor from a previous response.
response#5responseobject__0
response#5response.successboolean__1Yes
response#5response.selfIdstring__2YesParticipant ID of the connected account in conversations.
response#5response.selfUsernamestring | null__3YesUsername of the connected account.
response#5response.selfUsername[variant1]string__3_type:stringUsername of the connected account.
response#5response.selfUsername[variant2]null__3_type:nullUsername of the connected account.
response#5response.conversationsarray<object>__4Yes
response#5response.conversations[]object__5
response#5response.conversations[].idstring__6YesPlatform conversation ID
response#5response.conversations[].participantsarray<object>__7Yes
response#5response.conversations[].participants[]object__8
response#5response.conversations[].participants[].idstring | null__9Yes
response#5response.conversations[].participants[].id[variant1]string__9_type:string
response#5response.conversations[].participants[].id[variant2]null__9_type:null
response#5response.conversations[].participants[].namestring | null__10Yes
response#5response.conversations[].participants[].name[variant1]string__10_type:string
response#5response.conversations[].participants[].name[variant2]null__10_type:null
response#5response.conversations[].participants[].usernamestring | null__11Yes
response#5response.conversations[].participants[].username[variant1]string__11_type:string
response#5response.conversations[].participants[].username[variant2]null__11_type:null
response#5response.conversations[].participants[].profilePictureUrlstring | null__12YesTemporary Instagram profile picture URL.
response#5response.conversations[].participants[].profilePictureUrl[variant1]string__12_type:stringTemporary Instagram profile picture URL.
response#5response.conversations[].participants[].profilePictureUrl[variant2]null__12_type:nullTemporary Instagram profile picture URL.
response#5response.conversations[].lastMessageobject | null__13YesMost recent message in the conversation.
response#5response.conversations[].lastMessage[variant1]object__13_type:objectMost recent message in the conversation.
response#5response.conversations[].lastMessage[variant1].idstring__14YesPlatform message ID
response#5response.conversations[].lastMessage[variant1].textstring | null__15Yes
response#5response.conversations[].lastMessage[variant1].text[variant1]string__15_type:string
response#5response.conversations[].lastMessage[variant1].text[variant2]null__15_type:null
response#5response.conversations[].lastMessage[variant1].fromobject__16Yes
response#5response.conversations[].lastMessage[variant1].from.idstring | null__17Yes
response#5response.conversations[].lastMessage[variant1].from.id[variant1]string__17_type:string
response#5response.conversations[].lastMessage[variant1].from.id[variant2]null__17_type:null
response#5response.conversations[].lastMessage[variant1].from.namestring | null__18Yes
response#5response.conversations[].lastMessage[variant1].from.name[variant1]string__18_type:string
response#5response.conversations[].lastMessage[variant1].from.name[variant2]null__18_type:null
response#5response.conversations[].lastMessage[variant1].timestampstring | null__19Yeskind: ; value: date-time
response#5response.conversations[].lastMessage[variant1].timestamp[variant1]string__19_type:stringkind: ; value: date-time
response#5response.conversations[].lastMessage[variant1].timestamp[variant2]null__19_type:nullkind: ; value: date-time
response#5response.conversations[].lastMessage[variant2]null__13_type:nullMost recent message in the conversation.
response#5response.conversations[].updatedTimestring | null__20Yeskind: ; value: date-time
response#5response.conversations[].updatedTime[variant1]string__20_type:stringkind: ; value: date-time
response#5response.conversations[].updatedTime[variant2]null__20_type:nullkind: ; value: date-time
response#5response.nextCursorstring | null__21YesPass as after in the next request to paginate.
response#5response.nextCursor[variant1]string__21_type:stringPass as after in the next request to paginate.
response#5response.nextCursor[variant2]null__21_type:nullPass as after in the next request to paginate.
response#6responseobject__0
response#6response.successboolean__1Yes
response#6response.messagestring__2Yes