List Conversations API
The List Conversations API returns direct message conversations belonging to one connected Instagram or Twitter/X account. Every returned thread carries its participant list plus a preview of the newest message, which gives an inbox screen enough detail to rank threads, show who wrote last, and open the right conversation.
List Conversations API overview and supported platforms
List Conversations fetches threads for a single linked account. Callers specify a platform and an account, then receive data suited to an inbox layout: the people involved in each thread, a preview of the newest message, and a timestamp showing recent activity. Two platform values are accepted: instagram and twitter, with twitter covering Twitter/X. Access differs by platform. Instagram accounts need instagram_business_manage_messages, whereas Twitter/X accounts need dm.read. If a permission was approved after the account was first linked, linking that same account again is the documented way to pick it up. For Twitter/X, thread listings are built from recent DM events. Billing also differs: a Twitter/X read, covering either a list call or a thread call, is charged 1 credit, and Instagram reads carry no charge.
Request: GET {{API_BASE_URL}}/v1/messages
Issue a GET request to {{API_BASE_URL}}/v1/messages and include the x-access-key header carrying your access key. The List conversations request example sends platform=instagram together with an accountId placeholder and limit=20. Substitute the integration ID belonging to the linked account you intend to inspect. Both platform and accountId must accompany every call, since platform determines the allowed enum and accountId determines the specific linked account. Treat a call missing either required value as incomplete and correct it before sending again.
Query parameters field map
Four query parameters govern the call: platform, accountId, limit, and after. platform is mandatory, typed as string, and limited to instagram or twitter. accountId is also mandatory and string-typed, holding the integration ID obtained from list_integrations. limit is optional and integer-typed; it caps how many conversations come back, allowing values from 1 through 100, and defaults to 20 when omitted. after is optional and string-typed, carrying a cursor handed back by an earlier response. Consult the Query parameters field map table for a compact check of type and requiredness, and pick a modest limit for an initial inbox render.
Response field map and worked example
A successful payload exposes success, selfId, selfUsername, conversations, and nextCursor. selfId identifies the linked account among the participants, while selfUsername gives that account's username. Inside conversations, each entry supplies id, participants, lastMessage, and updatedTime. A participant entry contains id, name, username, and profilePictureUrl, with the last of these permitted to be null. A lastMessage entry contains id, text, from (an object holding id and name), and timestamp. For a reply, select the participant whose id differs from selfId and pass that value as recipientId in a send operation. This distinction prevents addressing a reply to the linked account itself, because participants include both sides of the thread. For paging, feed nextCursor back as after on a follow-up call; a null nextCursor signals that no further pages exist. The List conversations response example and the List conversations pagination request example demonstrate those field names and that paging sequence.
Building an inbox view and replying
Assemble an inbox in stages. Begin with a first-page call supplying platform, accountId, and a limit suited to the screen. Render threads from participants, lastMessage, and updatedTime, and retain selfId so reply addressing can skip the linked account. While nextCursor is non-null, request another page by sending it as after, continuing until it becomes null. Opening a thread is a separate step that loads its history, and answering it is a further step that needs the non-self participant id as recipientId. A null profilePictureUrl is a legitimate value, not a failure, so the interface should tolerate it gracefully.
Permissions, reconnect guidance, and credit notes
Verify access before investigating paging or empty results. Instagram Business or Creator accounts must hold instagram_business_manage_messages. Twitter/X accounts must hold dm.read. When approval arrived after the account was first linked, link that same account again so the newer approval takes effect. Confirm platform matches the account kind: instagram for Instagram Business or Creator accounts, twitter for Twitter/X. Plan polling with the billing split in mind: Twitter/X reads are charged 1 credit apiece across list and thread calls, while Instagram reads are free, so repeated Twitter/X refreshes draw credits more quickly.
| Parameter | Type | Required | Description |
|---|---|---|---|
| platform | string | Yes | instagram or twitter |
| accountId | string | Yes | Integration ID from list_integrations |
| limit | integer | No | Max conversations to return (1–100, default 20) |
| after | string | No | Pagination cursor from a previous response |
Exact documented contract for GET /v1/messages
| Field | Example type | Description |
|---|---|---|
| success | boolean (example) | Whether the request succeeded |
| selfId | string (example) | The connected account's own participant ID |
| selfUsername | string (example) | The connected account's username |
| conversations | array (example) | List of direct message conversations |
| conversations[].id | string (example) | Conversation identifier |
| conversations[].participants | array (example) | Participants in the conversation |
| conversations[].participants[].id | string (example) | Participant identifier; use the id that is not selfId as recipientId for a reply |
| conversations[].participants[].name | string (example) | Participant display name |
| conversations[].participants[].username | string (example) | Participant username |
| conversations[].participants[].profilePictureUrl | string or null (example) | Participant profile picture URL, or null |
| conversations[].lastMessage | object (example) | Most recent message in the conversation |
| conversations[].lastMessage.id | string (example) | Most recent message identifier |
| conversations[].lastMessage.text | string (example) | Most recent message text |
| conversations[].lastMessage.from | object (example) | Sender of the most recent message, with id and name |
| conversations[].lastMessage.timestamp | string (example) | Timestamp of the most recent message |
| conversations[].updatedTime | string (example) | When the conversation was last updated |
| nextCursor | string or null (example) | Pass as after for the next page; null means no more pages |
Field names exactly as documented; example types observed in the documented response example, not separately typed in source
| Platform | Permission required | Read cost | Notes |
|---|---|---|---|
| instagram_business_manage_messages | Free | For a connected Instagram Business or Creator account; link the account again if a permission was approved after first linking | |
| dm.read | 1 credit per read call | Twitter/X; conversations are derived from recent DM events; each read call, list or thread, costs 1 credit |
Exactly as documented in the source contract
Frequently asked questions
What parameters does the List Conversations API require?
Send platform as instagram or twitter, accountId as the integration ID from list_integrations, and optionally limit and after. The x-access-key header is required on the request.
How do I paginate through conversation results?
Pass the returned nextCursor value as the after parameter on the next request. A null nextCursor means there are no more pages to fetch.
Which participant should I use as the reply recipient?
Choose the participant whose id differs from selfId and supply that value as recipientId for a reply. selfId marks the connected account's own entry in the participants list.
What permissions are required for Instagram and Twitter/X?
Instagram needs instagram_business_manage_messages, while Twitter/X needs dm.read. If approval for a permission arrived after the account was first linked, link that account again so the newer approval takes effect.
How are reads charged on each platform?
For Twitter/X, thread listings come from recent DM events, and every read operation — listing or opening a thread — is charged 1 credit. Instagram reads carry no charge.
GET {{API_BASE_URL}}/v1/messages?platform=instagram&accountId=YOUR_ACCOUNT_ID&limit=20
x-access-key: YOUR_ACCESS_KEY{
"success": true,
"selfId": "17841400000000000",
"selfUsername": "yourbrand",
"conversations": [
{
"id": "aWdfZG1fdGhyZWFkXzE",
"participants": [
{
"id": "17841400000000001",
"name": "Jane Doe",
"username": "jane_doe",
"profilePictureUrl": "https://scontent.cdninstagram.com/..."
},
{
"id": "17841400000000000",
"name": "Your Brand",
"username": "yourbrand",
"profilePictureUrl": null
}
],
"lastMessage": {
"id": "mid.aWdfbXNnXzk5OQ",
"text": "An example comment.",
"from": { "id": "17841400000000001", "name": "Jane Doe" },
"timestamp": "2026-08-05T16:40:00.000Z"
},
"updatedTime": "2026-08-05T16:40:00.000Z"
}
],
"nextCursor": "cursor_abc123"
}GET {{API_BASE_URL}}/v1/messages?platform=instagram&accountId=YOUR_ACCOUNT_ID&limit=20&after=cursor_abc123
x-access-key: YOUR_ACCESS_KEYGET /v1/messages
x-access-key: YOUR_ACCESS_KEY