如何通过 API 检查 X 私信可达性

Quick Answer

用 TwexAPI 检查 Twitter/X 私信可达性指在发送前向 POST /v2/dm/status 提交用户名或 user ID 数组，读取 can_dm、dm_blocking、can_dm_on_xchat 和 passes_premium_check 等字段。它是查询时刻的发送前预检：can_dm: true 可进入发送队列；false、阻断或 null 状态应改为复查、换渠道或人工处理。

FAQ

检查 DM 可达性应该用哪个端点？

使用 POST /v2/dm/status。请求体是字符串数组，每个元素可以是用户名或 user ID。响应的 data 数组会返回 user_id、screen_name、can_dm、dm_blocking、can_dm_on_xchat、passes_premium_check 和认证相关上下文。

can_dm: true 是否保证私信一定送达？

不保证。它只说明目标账号在查询时看起来可达。真正发送前，账号设置、关注关系、Premium 条件、cookie 或平台规则都可能变化。建议保存 checked_at，并在发送高价值联系人前即时复查。

遇到 false、blocked 或 null 状态应该怎么办？

不要自动发送。false 状态可以改走其他渠道或稍后复查；dm_blocking: true 应阻断发送；null 字段应按未知处理，不要当作许可。保存原始响应，方便后续审计每次决策。

私信外联最容易被低估的一步，不是写消息，而是确认对方当前是否能收到这条消息。很多账号关闭了 DM，只允许关注者私信，或者触发了额外的认证、Premium、XChat 条件。直接发送会让流程变得难解释：到底是文案没回应，还是消息根本没送达？

TwexAPI 的 POST /v2/dm/status 适合做发送前预检。你提交一组用户名或 user ID，接口返回每个账号的 can_dm、dm_blocking、can_dm_on_xchat 以及认证相关字段。把这一步放在 CRM、客服队列或增长自动化之前，可以先判断“当前是否适合发 DM”，再决定是发送、换渠道，还是进入人工复核。

什么时候要先查 DM 状态

DM 状态预检 指在发送私信前，用 API 批量确认目标账号在当前条件下是否可达。它不是营销名单质量评分，也不是保证送达的最终凭证，而是发送动作前的一道可解释检查。

适合放在这些场景里：

• 销售或合作外联：名单进入发送队列前，先过滤 can_dm 不为 true 的账号。
• 客服和社群运营：当用户在公开帖里求助时，先判断是否能转入私信沟通。
• CRM 同步：把 DM 可达性保存成联系人字段，帮助销售选择 Twitter/X、邮件或其他渠道。
• 活动名单清洗：达人、KOL、合作账号批量入库时，记录一次可达性快照。

不要把 can_dm: false 写成“这个账号永远不能私信”。它只代表这次查询返回的当前状态。账号设置、关注关系、认证条件和平台规则都可能变化，所以生产流程里要保存查询时间，并给关键联系人设置重新检查规则。

API 端点

API 端点 指当前官方 OpenAPI 中的 V2 DM 状态检查接口：POST /v2/dm/status。请求体是字符串数组，每个元素可以是 X 用户 ID，也可以是用户名。

POST https://api.twexapi.io/v2/dm/status
Authorization: Bearer <your_token>
Content-Type: application/json

["1696160451770429440", "elonmusk", "openai"]

响应的核心结构是：

1{
2  "code": 200,
3  "msg": "success",
4  "data": [
5    {
6      "user_id": "1696160451770429440",
7      "screen_name": "example_user",
8      "is_blue_verified": false,
9      "is_verified_organization_affiliate": false,
10      "verified": false,
11      "can_dm": true,
12      "can_dm_on_xchat": null,
13      "dm_blocking": false,
14      "passes_premium_check": true
15    }
16  ]
17}

字段建议按下面的方式理解：

Python 示例

Python 示例 指一个服务端批量预检脚本：清洗输入、请求 V2 端点、规范化返回字段，并给每个联系人生成下一步动作。示例只做可达性判断，不负责真正发送私信。

1import os
2from datetime import datetime, timezone
3
4import requests
5
6API_URL = "https://api.twexapi.io/v2/dm/status"
7TOKEN = os.environ["TWEXAPI_BEARER_TOKEN"]
8
9def clean_targets(targets):
10    cleaned = []
11    seen = set()
12
13    for target in targets:
14        value = str(target).strip().lstrip("@")
15        if not value or value.lower() in seen:
16            continue
17
18        cleaned.append(value)
19        seen.add(value.lower())
20
21    return cleaned
22
23def check_dm_reachability(targets):
24    cleaned = clean_targets(targets)
25    if not cleaned:
26        return []
27
28    response = requests.post(
29        API_URL,
30        headers={
31            "Authorization": f"Bearer {TOKEN}",
32            "Content-Type": "application/json",
33            "Accept": "application/json",
34        },
35        json=cleaned,
36        timeout=30,
37    )
38    response.raise_for_status()
39    payload = response.json()
40
41    if payload.get("code", 200) >= 400:
42        raise RuntimeError(payload.get("msg", "TwexAPI returned an error"))
43
44    checked_at = datetime.now(timezone.utc).isoformat()
45    rows = []
46
47    for item in payload.get("data") or []:
48        can_dm = item.get("can_dm") is True
49        blocked = item.get("dm_blocking") is True
50
51        if can_dm and not blocked:
52            decision = "READY_TO_MESSAGE"
53        elif blocked:
54            decision = "DO_NOT_MESSAGE"
55        else:
56            decision = "RECHECK_OR_USE_OTHER_CHANNEL"
57
58        rows.append({
59            "user_id": item.get("user_id"),
60            "screen_name": item.get("screen_name"),
61            "can_dm": item.get("can_dm"),
62            "dm_blocking": item.get("dm_blocking"),
63            "can_dm_on_xchat": item.get("can_dm_on_xchat"),
64            "passes_premium_check": item.get("passes_premium_check"),
65            "verified": item.get("verified"),
66            "decision": decision,
67            "checked_at": checked_at,
68            "raw": item,
69        })
70
71    return rows
72
73targets = ["elonmusk", "@openai", "1696160451770429440"]
74
75for row in check_dm_reachability(targets):
76    print(row["screen_name"], row["decision"], row["can_dm"])

生产环境里，建议把返回结果拆成两层保存：规范化字段供 CRM、看板和规则引擎使用；原始 JSON 供后续排查字段变化、平台状态变化或误判。

放进外联流程

外联流程 指把 DM 状态检查放在发送前，而不是发送失败后再补救。最实用的流程通常是“名单入库、状态预检、规则分流、发送前复查、结果回写”。

一个稳定的流程可以这样设计：

1. 名单入库：保存 screen_name、user_id、名单来源、活动 ID 和负责人。
2. 批量预检：调用 /v2/dm/status，保存 can_dm、dm_blocking、passes_premium_check 和原始响应。
3. 规则分流：can_dm === true 且没有阻断信号的账号进入发送队列；其他账号改走邮件、公开回复或人工复核。
4. 发送前复查：对高价值联系人，在真正发送前重新查一次，避免用过期状态决策。
5. 结果回写：把发送结果、失败原因和最后一次 DM 状态一起写回 CRM。

这样做的价值不只是减少失败发送。更重要的是，每个联系人为什么进入或退出 DM 队列都有记录，团队可以复盘规则，而不是靠“这批名单效果不好”这种模糊结论。

状态如何解释

状态解释 指把 API 字段转成业务动作时要保守。can_dm 是主要信号，但不要脱离 dm_blocking、Premium 检查、认证字段和查询时间单独解释。

如果你的发送账号、cookie、关注关系或 Premium 状态会变化，就不要长期缓存 DM 状态。对于普通外联名单，可以按小时或天级别刷新；对于高价值联系人，最好在发送前即时复查。

最小生产实现

最小生产实现 指只保留必要能力：批量请求、去重、超时、错误处理、状态保存和重查策略。不要一开始就把它做成复杂监控系统。

建议至少保存这些字段：

错误处理上，401 通常是 Token 问题，应该立即停止任务并提醒配置；422 多半是请求体格式问题，应该记录失败批次；网络超时可以重试，但不要无限重试同一批联系人。

常见误区

常见误区 指把 DM 可达性当作静态事实，或者把认证字段当作发送许可。更稳妥的做法是把它当成“查询时刻的发送前证据”。

• 以当前 OpenAPI 的 V2 路径 /v2/dm/status 为准，不要沿用旧版 DM 状态示例。
• 以 V2 响应里的 can_dm、dm_blocking 和相关上下文字段为准，不要沿用旧版布尔字段口径。
• 不要把 can_dm: true 写成“保证送达”。真正发送时仍可能因为账号关系、平台策略或状态变化失败。
• 不要把 can_dm: false 写成“永远不可联系”。它只代表这次查询下不适合直接发 DM。

小结

小结 指把 DM 状态检查当成发送前的可达性预检：向 POST /v2/dm/status 提交用户名或 user ID 数组，读取 can_dm、dm_blocking、passes_premium_check 等字段，保存原始响应和查询时间，再把结果写入 CRM、客服队列或外联规则。这样私信自动化不会只追求“发出去”，而是能解释每一次为什么发、为什么不发、什么时候需要复查。