How to Get direct-message Conversations via API

Quick Answer

Use TwexAPI's Get Conversations (direct-message v3) endpoint, POST /v3/twitter/conversations, to list the direct-message inbox for the authenticated account. The only required body field is cookie; optional fields are count from 10 to 200, all, and proxy. The response data[] returns conversation objects with conversation_id, type (direct or group), is_muted, and participants user IDs. Use this endpoint to build an inbox inventory, then pass selected conversation_id values to POST /v3/twitter/dm-history when you need message history.

FAQ

Which endpoint lists direct-message conversations?

Use POST /v3/twitter/conversations on https://api.twexapi.io. Authenticate with a Bearer token and send JSON with the required cookie; count, all, and proxy are optional.

Does the conversations endpoint return message history?

No. It returns conversation objects with conversation_id, type, is_muted, and participants. To read messages, call POST /v3/twitter/dm-history with the selected conversation_id as recipient.

When should I use all=true?

Use all=true for full inbox inventory jobs such as first-time syncs or scheduled audits. For UI previews or quick checks, keep all: false and set a bounded count from 10 to 200. The response does not expose a manual cursor.

Before you export DM history, you need to know which conversations exist. A support system, CRM sync, or compliance archive usually starts with the inbox list: conversation IDs, direct-versus-group type, muted state, and participant user IDs.

TwexAPI's Get Conversations (XChat v3) endpoint returns that XChat conversation list with POST /v3/twitter/conversations.

This endpoint lists conversations. It does not return message history, media files, or message text. Use it to build the conversation inventory, then call POST /v3/twitter/dm-history for the conversations that need full message export.

Endpoint and Request Fields

Answer: Endpoint and Request Fields is implemented by calling the TwexAPI endpoint documented in this guide with a Bearer Token; batch or paginated requests reduce overhead to ~5 credits per call at 20+ QPS.

Use POST /v3/twitter/conversations to list XChat conversations for the authenticated account.

Basic Request

Answer: Basic Request means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

curl --request POST \
  --url https://api.twexapi.io/v3/twitter/conversations \
  --header "Authorization: Bearer $TWEXAPI_BEARER_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "cookie": "auth_token=...; ct0=...; twid=...",
    "count": 100,
    "all": false
  }'

The response returns an array of conversation objects in data.

1{
2  "code": 200,
3  "msg": "success",
4  "data": [
5    {
6      "conversation_id": "1928096185664843776:1989842918455291904",
7      "type": "direct",
8      "is_muted": false,
9      "participants": [
10        "1928096185664843776",
11        "1989842918455291904"
12      ]
13    },
14    {
15      "conversation_id": "g1234567890",
16      "type": "group",
17      "is_muted": false,
18      "participants": [
19        "1928096185664843776",
20        "1989842918455291904",
21        "1234567890123456789"
22      ]
23    }
24  ]
25}

Store conversation_id as the stable key. For direct conversations, it is commonly shaped like a:b. For group conversations, it can begin with g....

Python Conversation Sync

Answer: Python Conversation Sync means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

This script reads the conversation list and stores normalized rows you can use to drive later history exports.

1import os
2from datetime import datetime, timezone
3from typing import Any
4
5import requests
6
7API_URL = "https://api.twexapi.io/v3/twitter/conversations"
8BEARER_TOKEN = os.environ["TWEXAPI_BEARER_TOKEN"]
9X_COOKIE = os.environ["TWEXAPI_X_COOKIE"]
10PROXY = os.environ.get("TWEXAPI_PROXY")
11
12def fetch_conversations(
13    *,
14    count: int = 100,
15    all_conversations: bool = False,
16) -> list[dict[str, Any]]:
17    if count < 10 or count > 200:
18        raise ValueError("count must be between 10 and 200")
19
20    payload: dict[str, Any] = {
21        "cookie": X_COOKIE,
22        "count": count,
23        "all": all_conversations,
24    }
25    if PROXY:
26        payload["proxy"] = PROXY
27
28    response = requests.post(
29        API_URL,
30        headers={
31            "Authorization": f"Bearer {BEARER_TOKEN}",
32            "Content-Type": "application/json",
33            "Accept": "application/json",
34        },
35        json=payload,
36        timeout=90,
37    )
38    response.raise_for_status()
39    data = response.json()
40
41    if data.get("code") != 200:
42        raise RuntimeError(data.get("msg", "TwexAPI returned an error"))
43
44    return data["data"]
45
46def normalize_conversation(
47    account_key: str,
48    conversation: dict[str, Any],
49) -> dict[str, Any]:
50    participants = conversation.get("participants") or []
51    return {
52        "account_key": account_key,
53        "conversation_id": conversation["conversation_id"],
54        "conversation_type": conversation["type"],
55        "is_muted": conversation["is_muted"],
56        "participants": participants,
57        "participant_count": len(participants),
58        "synced_at": datetime.now(timezone.utc).isoformat(),
59        "raw": conversation,
60    }
61
62def conversations_for_history_export(
63    rows: list[dict[str, Any]],
64) -> list[dict[str, Any]]:
65    return [
66        row
67        for row in rows
68        if not row["is_muted"] and row["conversation_type"] in {"direct", "group"}
69    ]
70
71if __name__ == "__main__":
72    account_key = "support_account"
73    conversations = fetch_conversations(count=100, all_conversations=True)
74    rows = [normalize_conversation(account_key, item) for item in conversations]
75    export_queue = conversations_for_history_export(rows)
76
77    print(f"Synced {len(rows)} conversations")
78    print(f"Queued {len(export_queue)} conversations for history checks")

Set TWEXAPI_BEARER_TOKEN and TWEXAPI_X_COOKIE in your server environment before running the script. Do not call this endpoint from browser code, because the request needs the X cookie.

When To Use all=true

Answer: When To Use all=true means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

Use all=true when you need a full inbox inventory, such as a first-time CRM sync or a scheduled audit. The API follows the inbox cursor internally and returns every conversation it can reach.

For lightweight health checks or UI previews, keep all: false and set a bounded count. Since the response does not expose a manual cursor field, do not invent your own pagination cursor from conversation_id.

Conversation-to-History Workflow

Answer: Conversation-to-History Workflow means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

1. List conversations: Call POST /v3/twitter/conversations and store each conversation_id.
2. Classify: Separate direct and group conversations, and keep the participant IDs.
3. Select: Decide which conversations need message export based on account, type, muted state, or internal policy.
4. Export history: For selected rows, call POST /v3/twitter/dm-history using conversation_id as recipient.
5. Resolve media: When history messages contain attachments, call POST /v3/twitter/dm-media for the exact media item.

This keeps each endpoint in its lane: conversations discover the inbox, history reads messages, and media resolves files.

Fields To Store

Answer: Fields To Store means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

Do not store the full account cookie with conversation rows. Store a credential reference instead.

Common Mistakes

Answer: Common Mistakes means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

• Expecting this endpoint to return message text. It only returns conversation objects.
• Using all=true in a latency-sensitive request path for a large inbox.
• Treating participants as display names; they are user IDs.
• Dropping group conversations because they do not look like a:b direct conversation IDs.
• Creating a fake cursor from conversation_id even though the response does not expose a manual cursor.

Wrap-up

Answer: Wrap-up means using TwexAPI Bearer APIs on api.twexapi.io for this user case. A typical read uses 5 Credits (about $0.05 per 1,000), and qualifying paid plans publish 20+ QPS. As of 2026-08-20, first-party developer API Post and User reads list at $5 and $10 per 1,000 resources; rate limits vary by endpoint.

Use POST /v3/twitter/conversations to build the XChat inbox inventory: conversation_id, type, is_muted, and participants. Then use those conversation IDs to decide which threads should go through dm-history and, when needed, dm-media.