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.
| Parameter | Required | Type | Constraints | Description |
|---|---|---|---|---|
| platform | Yes | string | "instagram" | "twitter" | Platform to fetch conversations from. |
| accountId | Yes | string | — | Integration ID of the connected account. |
| limit | No | integer | Default 20; 1 <= value <= 100 | Max conversations to return. |
| after | No | string | — | Pagination cursor from a previous response. |
Exact source contract; origin shown as {{API_BASE_URL}}.
| Field | Required | Type | Description |
|---|---|---|---|
| success | Yes | boolean | — |
| selfId | Yes | string | Participant ID of the connected account in conversations. |
| selfUsername | Yes | string | null | Username of the connected account. |
| conversations | Yes | array<object> | — |
| conversations[].id | Yes | string | Platform conversation ID |
| conversations[].participants | Yes | array<object> | — |
| conversations[].participants[].id | Yes | string | null | — |
| conversations[].participants[].name | Yes | string | null | — |
| conversations[].participants[].username | Yes | string | null | — |
| conversations[].participants[].profilePictureUrl | Yes | string | null | Temporary Instagram profile picture URL. |
| conversations[].lastMessage | Yes | object | null | Most recent message in the conversation. |
| conversations[].lastMessage.id | Yes | string | Platform message ID |
| conversations[].lastMessage.text | Yes | string | null | — |
| conversations[].lastMessage.from | Yes | object | — |
| conversations[].lastMessage.from.id | Yes | string | null | — |
| conversations[].lastMessage.from.name | Yes | string | null | — |
| conversations[].lastMessage.timestamp | Yes | string | null (date-time) | — |
| conversations[].updatedTime | Yes | string | null (date-time) | — |
| nextCursor | Yes | string | null | Pass as after in the next request to paginate. |
Exact source contract for the 200 response.
| Status | Content type | Body fields |
|---|---|---|
| 200 | application/json | success (boolean), selfId (string), selfUsername (string | null), conversations (array<object>), nextCursor (string | null) |
| 400 | application/json | success (boolean), message (string) |
| 402 | application/json | success (boolean), message (string) |
| 403 | application/json | success (boolean), message (string) |
| 404 | application/json | success (boolean), message (string) |
| 502 | application/json | success (boolean), message (string) |
Status codes and body shape only; no error meanings documented in source.
curl -X GET "{{API_BASE_URL}}/v1/messages/?platform=instagram&accountId=string" -H "x-access-key: <token>"{
"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"
}{
"success": true,
"message": "string"
}curl -X GET "{{API_BASE_URL}}/v1/messages/?platform=instagram&accountId=string&limit=20&after=<nextCursor>" -H "x-access-key: <token>"| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| platform#1 | platform | string | __0 | Yes | Platform to fetch conversations from. | kind: schemaValueIn; value: "instagram" | "twitter" |
| accountId#2 | accountId | string | __0 | Yes | Integration ID of the connected account. | |
| limit#3 | limit | integer | __0 | No | Max conversations to return. | kind: schemaDefault; value: 20 | kind: schemaRange; value: 1 <= value <= 100 |
| after#4 | after | string | __0 | No | Pagination cursor from a previous response. | |
| response#5 | response | object | __0 | |||
| response#5 | response.success | boolean | __1 | Yes | ||
| response#5 | response.selfId | string | __2 | Yes | Participant ID of the connected account in conversations. | |
| response#5 | response.selfUsername | string | null | __3 | Yes | Username of the connected account. | |
| response#5 | response.selfUsername[variant1] | string | __3_type:string | Username of the connected account. | ||
| response#5 | response.selfUsername[variant2] | null | __3_type:null | Username of the connected account. | ||
| response#5 | response.conversations | array<object> | __4 | Yes | ||
| response#5 | response.conversations[] | object | __5 | |||
| response#5 | response.conversations[].id | string | __6 | Yes | Platform conversation ID | |
| response#5 | response.conversations[].participants | array<object> | __7 | Yes | ||
| response#5 | response.conversations[].participants[] | object | __8 | |||
| response#5 | response.conversations[].participants[].id | string | null | __9 | Yes | ||
| response#5 | response.conversations[].participants[].id[variant1] | string | __9_type:string | |||
| response#5 | response.conversations[].participants[].id[variant2] | null | __9_type:null | |||
| response#5 | response.conversations[].participants[].name | string | null | __10 | Yes | ||
| response#5 | response.conversations[].participants[].name[variant1] | string | __10_type:string | |||
| response#5 | response.conversations[].participants[].name[variant2] | null | __10_type:null | |||
| response#5 | response.conversations[].participants[].username | string | null | __11 | Yes | ||
| response#5 | response.conversations[].participants[].username[variant1] | string | __11_type:string | |||
| response#5 | response.conversations[].participants[].username[variant2] | null | __11_type:null | |||
| response#5 | response.conversations[].participants[].profilePictureUrl | string | null | __12 | Yes | Temporary Instagram profile picture URL. | |
| response#5 | response.conversations[].participants[].profilePictureUrl[variant1] | string | __12_type:string | Temporary Instagram profile picture URL. | ||
| response#5 | response.conversations[].participants[].profilePictureUrl[variant2] | null | __12_type:null | Temporary Instagram profile picture URL. | ||
| response#5 | response.conversations[].lastMessage | object | null | __13 | Yes | Most recent message in the conversation. | |
| response#5 | response.conversations[].lastMessage[variant1] | object | __13_type:object | Most recent message in the conversation. | ||
| response#5 | response.conversations[].lastMessage[variant1].id | string | __14 | Yes | Platform message ID | |
| response#5 | response.conversations[].lastMessage[variant1].text | string | null | __15 | Yes | ||
| response#5 | response.conversations[].lastMessage[variant1].text[variant1] | string | __15_type:string | |||
| response#5 | response.conversations[].lastMessage[variant1].text[variant2] | null | __15_type:null | |||
| response#5 | response.conversations[].lastMessage[variant1].from | object | __16 | Yes | ||
| response#5 | response.conversations[].lastMessage[variant1].from.id | string | null | __17 | Yes | ||
| response#5 | response.conversations[].lastMessage[variant1].from.id[variant1] | string | __17_type:string | |||
| response#5 | response.conversations[].lastMessage[variant1].from.id[variant2] | null | __17_type:null | |||
| response#5 | response.conversations[].lastMessage[variant1].from.name | string | null | __18 | Yes | ||
| response#5 | response.conversations[].lastMessage[variant1].from.name[variant1] | string | __18_type:string | |||
| response#5 | response.conversations[].lastMessage[variant1].from.name[variant2] | null | __18_type:null | |||
| response#5 | response.conversations[].lastMessage[variant1].timestamp | string | null | __19 | Yes | kind: ; value: date-time | |
| response#5 | response.conversations[].lastMessage[variant1].timestamp[variant1] | string | __19_type:string | kind: ; value: date-time | ||
| response#5 | response.conversations[].lastMessage[variant1].timestamp[variant2] | null | __19_type:null | kind: ; value: date-time | ||
| response#5 | response.conversations[].lastMessage[variant2] | null | __13_type:null | Most recent message in the conversation. | ||
| response#5 | response.conversations[].updatedTime | string | null | __20 | Yes | kind: ; value: date-time | |
| response#5 | response.conversations[].updatedTime[variant1] | string | __20_type:string | kind: ; value: date-time | ||
| response#5 | response.conversations[].updatedTime[variant2] | null | __20_type:null | kind: ; value: date-time | ||
| response#5 | response.nextCursor | string | null | __21 | Yes | Pass as after in the next request to paginate. | |
| response#5 | response.nextCursor[variant1] | string | __21_type:string | Pass as after in the next request to paginate. | ||
| response#5 | response.nextCursor[variant2] | null | __21_type:null | Pass as after in the next request to paginate. | ||
| response#6 | response | object | __0 | |||
| response#6 | response.success | boolean | __1 | Yes | ||
| response#6 | response.message | string | __2 | Yes |