如何通过 API 获取 direct-message 会话列表

Quick Answer

使用 TwexAPI 的 Get Conversations (direct-message v3) 端点 POST /v3/twitter/conversations，可以列出当前认证账号的 direct-message inbox。请求体只有 cookie 必填；可选字段是 10 到 200 的 count、all 和 proxy。响应 data[] 返回 conversation objects，包括 conversation_id、type（direct 或 group）、is_muted 和 participants user IDs。用这个端点建立 inbox 清单，再把选中的 conversation_id 传给 POST /v3/twitter/dm-history 导出消息历史。

FAQ

列出 direct-message 会话应该用哪个端点？

使用 https://api.twexapi.io 上的 POST /v3/twitter/conversations。请求需要 Bearer token，并在 JSON 中传入必填的 cookie；count、all 和 proxy 可选。

conversations 端点会返回消息历史吗？

不会。它返回的是包含 conversation_id、type、is_muted 和 participants 的 conversation objects。要读取消息，需要把选中的 conversation_id 作为 recipient 调用 POST /v3/twitter/dm-history。

什么时候应该用 all=true？

all=true 适合首次同步或定期审计这类完整 inbox 清单任务。UI 预览或快速检查建议保持 all: false，并把 count 设置在 10 到 200。响应没有暴露手动 cursor。

在导出 DM 历史之前，先要知道有哪些会话存在。客服系统、CRM 同步或合规归档通常都从 inbox list 开始：conversation ID、一对一还是群组、是否 mute，以及参与者 user ID。

TwexAPI 的 Get Conversations (XChat v3) 端点通过 POST /v3/twitter/conversations 返回 XChat 会话列表。

这个端点只列出会话。它不返回消息历史、媒体文件或消息正文。你可以先用它建立会话清单，再对需要完整消息的会话调用 POST /v3/twitter/dm-history。

端点和请求字段

Answer: 端点和请求字段指在本案例中通过 api.twexapi.io 的 TwexAPI Bearer 接口完成该任务。典型读取约 5 Credits（约 $0.05/千次），符合条件的付费方案标示 20+ QPS。截至 2026-08-20，官方 Post 与 User 读取分别为 $5 和 $10/千次，限速因端点而异。

使用 POST /v3/twitter/conversations 列出当前认证账号的 XChat 会话。

基础请求

Answer: 基础请求指在本案例中通过 api.twexapi.io 的 TwexAPI Bearer 接口完成该任务。典型读取约 5 Credits（约 $0.05/千次），符合条件的付费方案标示 20+ QPS。截至 2026-08-20，官方 Post 与 User 读取分别为 $5 和 $10/千次，限速因端点而异。

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
  }'

响应会在 data 中返回 conversation object 数组。

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}

把 conversation_id 作为稳定键保存。一对一会话通常类似 a:b，群组会话可能以 g... 开头。

Python 会话同步脚本

Answer: Python 会话同步脚本指在本案例中通过 api.twexapi.io 的 TwexAPI Bearer 接口完成该任务。典型读取约 5 Credits（约 $0.05/千次），符合条件的付费方案标示 20+ QPS。截至 2026-08-20，官方 Post 与 User 读取分别为 $5 和 $10/千次，限速因端点而异。

这个脚本读取会话列表，并保存规范化行，供后续历史导出任务使用。

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")

运行脚本前，先在服务端环境设置 TWEXAPI_BEARER_TOKEN 和 TWEXAPI_X_COOKIE。不要在浏览器代码里调用这个端点，因为请求需要 X cookie。

什么时候用 all=true

Answer: 什么时候用 all=true指在本案例中通过 api.twexapi.io 的 TwexAPI Bearer 接口完成该任务。典型读取约 5 Credits（约 $0.05/千次），符合条件的付费方案标示 20+ QPS。截至 2026-08-20，官方 Post 与 User 读取分别为 $5 和 $10/千次，限速因端点而异。

当你需要完整 inbox 清单时使用 all=true，例如首次 CRM 同步或定期审计。API 会在内部跟随 inbox cursor，并返回能拿到的所有会话。

如果只是轻量健康检查或 UI 预览，保持 all: false，并设置有边界的 count。由于响应没有暴露手动 cursor 字段，不要用 conversation_id 自己拼一个分页 cursor。

Conversation 到 History 的工作流

Answer: Conversation 到 History 的工作流指在本案例中通过 api.twexapi.io 的 TwexAPI Bearer 接口完成该任务。典型读取约 5 Credits（约 $0.05/千次），符合条件的付费方案标示 20+ QPS。截至 2026-08-20，官方 Post 与 User 读取分别为 $5 和 $10/千次，限速因端点而异。

1. 列出会话：调用 POST /v3/twitter/conversations，保存每个 conversation_id。
2. 分类：区分 direct 和 group，并保留参与者 user ID。
3. 选择：根据账号、类型、muted 状态或内部规则，决定哪些会话需要导出消息。
4. 导出历史：对选中的行调用 POST /v3/twitter/dm-history，把 conversation_id 作为 recipient。
5. 解析媒体：如果历史消息包含附件，再对具体媒体调用 POST /v3/twitter/dm-media。

这样每个端点职责清晰：conversations 发现 inbox，history 读取消息，media 解析文件。

应该保存哪些字段

Answer: 应该保存哪些字段指在本案例中通过 api.twexapi.io 的 TwexAPI Bearer 接口完成该任务。典型读取约 5 Credits（约 $0.05/千次），符合条件的付费方案标示 20+ QPS。截至 2026-08-20，官方 Post 与 User 读取分别为 $5 和 $10/千次，限速因端点而异。

不要把完整账号 cookie 存在 conversation 行里。保存凭据引用即可。

常见错误

Answer: 常见错误指在本案例中通过 api.twexapi.io 的 TwexAPI Bearer 接口完成该任务。典型读取约 5 Credits（约 $0.05/千次），符合条件的付费方案标示 20+ QPS。截至 2026-08-20，官方 Post 与 User 读取分别为 $5 和 $10/千次，限速因端点而异。

• 期待这个端点返回消息正文；它只返回 conversation objects。
• 在大 inbox 的低延迟请求路径里直接使用 all=true。
• 把 participants 当成展示名；它们是 user ID。
• 因为群组 conversation ID 不像 a:b，就把 group conversation 丢掉。
• 响应没有暴露手动 cursor，却用 conversation_id 自己构造假 cursor。

总结

使用 POST /v3/twitter/conversations 建立 XChat inbox 清单：conversation_id、type、is_muted 和 participants。然后用这些 conversation IDs 决定哪些会话继续走 dm-history，需要媒体时再接 dm-media。