List Conversations

POST/tw-v2/xchat/conversations

Description

Get a list of all X Chat conversations in your inbox. Returns conversation metadata including participants and timestamps.

This endpoint does not require /xchat/setup since it only returns metadata, not decrypted message content.

Request Body

Parameter	Type	Required	Description
authToken	string	required	Twitter authentication token (auth_token cookie value)
proxy	string	optional	Proxy in format 'hostname:port@username:password'

Code Examples

const body = {
  authToken: 'YOUR_AUTH_TOKEN'
};

const response = 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(body)
});

const data = await response.json();
console.log(data);

// List all conversations
for (const conv of data.conversations) {
  const participants = conv.participants.map(p => p.screenName || p.userId).join(', ');
  console.log(`Conversation ${conv.conversationId} with: ${participants}`);
}

Response

Success Response (200 OK)

200

{
  "conversations": [
    {
      "conversationId": "1234567890123456789:9876543210987654321",
      "participants": [
        {
          "userId": "9876543210987654321",
          "name": "John Doe",
          "screenName": "johndoe"
        }
      ],
      "lastMessageTimestamp": 1736847291525,
      "type": "one_to_one"
    },
    {
      "conversationId": "1234567890123456789:1111111111111111111:2222222222222222222",
      "participants": [
        {
          "userId": "1111111111111111111",
          "name": "Alice",
          "screenName": "alice"
        },
        {
          "userId": "2222222222222222222",
          "name": "Bob",
          "screenName": "bob"
        }
      ],
      "lastMessageTimestamp": 1736840000000,
      "type": "group"
    }
  ]
}

Response Fields

Parameter	Type	Required	Description
conversations	array	required	Array of conversation objects
conversations[].conversationId	string	required	Unique conversation identifier (use with /xchat/history)
conversations[].participants	array	required	Array of participants in the conversation (excludes yourself)
conversations[].participants[].userId	string	required	Twitter 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	Timestamp of last message in milliseconds
conversations[].type	string	required	'one_to_one' for DMs, 'group' for group chats

Typical Workflow

List conversations using this endpoint to see all X Chat conversations
Check recipient using /xchat/can-dm before starting a new conversation
Setup keys using /xchat/setup (only needed once per session)
Send messages using /xchat/send
Read history using /xchat/history with the conversationId

Error Responses

400s Errors

401UNAUTHORIZED

429TOO_MANY_REQUESTS