Skip to content

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.

Query parameters field map
ParameterTypeRequiredDescription
platformstringYesinstagram or twitter
accountIdstringYesIntegration ID from list_integrations
limitintegerNoMax conversations to return (1–100, default 20)
afterstringNoPagination cursor from a previous response

Exact documented contract for GET /v1/messages

Response field map
FieldExample typeDescription
successboolean (example)Whether the request succeeded
selfIdstring (example)The connected account's own participant ID
selfUsernamestring (example)The connected account's username
conversationsarray (example)List of direct message conversations
conversations[].idstring (example)Conversation identifier
conversations[].participantsarray (example)Participants in the conversation
conversations[].participants[].idstring (example)Participant identifier; use the id that is not selfId as recipientId for a reply
conversations[].participants[].namestring (example)Participant display name
conversations[].participants[].usernamestring (example)Participant username
conversations[].participants[].profilePictureUrlstring or null (example)Participant profile picture URL, or null
conversations[].lastMessageobject (example)Most recent message in the conversation
conversations[].lastMessage.idstring (example)Most recent message identifier
conversations[].lastMessage.textstring (example)Most recent message text
conversations[].lastMessage.fromobject (example)Sender of the most recent message, with id and name
conversations[].lastMessage.timestampstring (example)Timestamp of the most recent message
conversations[].updatedTimestring (example)When the conversation was last updated
nextCursorstring 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

Permissions and credit notes
PlatformPermission requiredRead costNotes
instagraminstagram_business_manage_messagesFreeFor a connected Instagram Business or Creator account; link the account again if a permission was approved after first linking
twitterdm.read1 credit per read callTwitter/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.

List conversations request
GET {{API_BASE_URL}}/v1/messages?platform=instagram&accountId=YOUR_ACCOUNT_ID&limit=20
x-access-key: YOUR_ACCESS_KEY
List conversations response example
{
	"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"
}
List conversations pagination request
GET {{API_BASE_URL}}/v1/messages?platform=instagram&accountId=YOUR_ACCOUNT_ID&limit=20&after=cursor_abc123
x-access-key: YOUR_ACCESS_KEY
Contract example 1
GET /v1/messages
x-access-key: YOUR_ACCESS_KEY