List Conversations

POST/tw-v2/xchat/conversations

Description

Get X Chat conversations in your inbox with participant metadata and pagination info.

This endpoint does not require /xchat/setup because it only returns metadata (no decrypted message content).

Request Body

Parameter	Type	Required	Description
authToken	string	required	Account authentication token (auth_token cookie value)
cursor	string	optional	Pagination cursor from the previous response. Pass this together with graphSnapshotId for page 2+.
graphSnapshotId	string	optional	Graph snapshot ID from the previous response. Required together with cursor for pagination.
limit	number	optional	Number of conversations per page (1-100, default 50).
proxy	string	optional	Proxy in format 'hostname:port@username:password'

Code Examples

const firstPage = await fetch('https://api.tweetapi.com/tw-v2/xchat/conversations', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ authToken: 'YOUR_AUTH_TOKEN' })
});

const firstData = await firstPage.json();
console.log(firstData.cursor, firstData.graphSnapshotId);

// Fetch next page
if (firstData.cursor) {
  const secondPage = await fetch('https://api.tweetapi.com/tw-v2/xchat/conversations', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      authToken: 'YOUR_AUTH_TOKEN',
      cursor: firstData.cursor,
      graphSnapshotId: firstData.graphSnapshotId
    })
  });

  const secondData = await secondPage.json();
  console.log(secondData);
}

Response

Success Response (200 OK)

200

{
  "conversations": [
    {
      "conversationId": "1234567890:9876543210",
      "participants": [
        {
          "userId": "9876543210",
          "name": "JohnDoe",
          "screenName": "JohnDoe"
        }
      ],
      "lastMessageTimestamp": 1769173580397,
      "type": "one_to_one"
    },
    {
      "conversationId": "g5001680743694518742",
      "participants": [
        {
          "userId": "1234567890",
          "name": ".",
          "screenName": "JaneSmith"
        },
        {
          "userId": "9876543210",
          "name": "JohnDoe",
          "screenName": "JohnDoe"
        }
      ],
      "lastMessageTimestamp": 1768483844743,
      "type": "group"
    }
  ],
  "cursor": "50",
  "graphSnapshotId": "bf0310dd-d428-4de1-9815-435bc90061686"
}

Response Fields

Parameter	Type	Required	Description
conversations	array	required	Array of conversation objects
conversations[].conversationId	string	required	Conversation identifier (use with /xchat/history)
conversations[].participants	array	required	Conversation participants included in the response
conversations[].participants[].userId	string	required	platform user ID of participant
conversations[].participants[].name	string	optional	Display name of participant
conversations[].participants[].screenName	string	optional	@ handle of participant
conversations[].lastMessageTimestamp	number	optional	Last message timestamp in milliseconds (when available)
conversations[].type	string	required	'one_to_one' or 'group'
cursor	string \| null	required	Pagination cursor for the next page. Pass this back as request cursor together with graphSnapshotId. null when there are no more pages.
graphSnapshotId	string \| null	required	Graph snapshot ID. Pass this back with cursor for pagination.

Typical Workflow

List conversations using this endpoint (no params needed for the first page).
Paginate by passing back both cursor and graphSnapshotId from the response.
Stop when cursor is null — there are no more pages.
Read messages using /xchat/history and a selected conversationId.

Error Responses

400s Errors

401UNAUTHORIZED

400BAD_REQUEST

429TOO_MANY_REQUESTS