WeBridge 插件内置 HTTP 接口

本文档版次为 8080，沿用 8079 的业务接口约定；当前插件主版本为 8.0.80，本次构建为 8.0.80-2。用户已确认现有全部业务功能在微信 8.0.80 验证通过；下文保留旧版本的具体真机记录。新增的设置页检查更新仍需单独完成真机弹窗与浏览器下载联调。示例中的当前版本和构建标记用于说明格式，排错时以设备实际返回为准。

本文适用插件 8.0.80。调用方直接访问手机的 HTTP 服务；配置、鉴权、接口、事件、结果判断和排错均在本篇内。Apifox 是同一 HTTP 协议的可导入调试形式。

目录

• 1. 接口与接入准备
• 2. 请求、鉴权与功能开关
• 3. 返回结果与错误
• 4. 健康检查与事件接收
• 5. 完整端点索引
• 6. 消息发送
• 7. 消息操作
• 8. 媒体下载与上传
• 9. 联系人与好友
• 10. 群聊管理
• 11. 会话管理
• 12. 红包与转账
• 13. 账号资料与个人二维码
• 14. 朋友圈
• 15. 收藏
• 16. 公众号
• 17. 状态查询与后台保活
• 18. 调试与诊断接口
• 19. 兼容与已移除接口
• 附录：常见接入问题

1. 接口与接入准备

插件在你的 iPhone 上开了一个 HTTP 服务，默认监听 19088 端口、绑定所有网卡。你用任何能发 HTTP 请求的语言调用它，就能让微信发消息、查联系人、同意好友申请等。

和"长轮询 / WebSocket"的关系：那个是插件主动连你的服务器；这个是你主动连插件。本地 HTTP 除了发送和查询，还可通过 POST /events 主动拉取微信事件。三者的事件队列独立，调用 /events 不会消费或改变长轮询、WebSocket 的事件。不同模式的选型对比可另看《接入总览与模式选择》，不影响按本文独立接入。

首次接入按以下顺序验证：先请求 GET /health 检查端口与 auth_authorized，确认微信登录及插件已启用，再向 filehelper 发送一条文本；需要接收事件时按第 4 节维护自己的游标。第 5 节可按业务查找入口。文中手机 IP、账号、消息 ID、资源地址和凭据示例均须替换为实际值。

2. 请求、鉴权与功能开关

这一节里的每一条都是插件实际强制的行为，写客户端前请务必看完。

2.1 长连接

插件不支持 HTTP keep-alive。 每一个响应都带 Connection: close，连接用完即断。你的 HTTP 客户端必须容忍这一点——不要依赖连接复用，也不要因为连接被关闭而误判为错误。

2.2 请求体大小

上限 1 MiB。 超过会返回 413：

{ "ok": false, "error": "请求体过大，最大允许 1 MiB" }

⚠️ 实践影响：图片、视频、语音、文件不要用 Base64 塞进请求体。这些接口设计上都是传路径或 URL，由插件自己去取。真要塞大文件，请改用"传 URL"的形式。

2.3 并发与超时

普通微信业务调用默认串行，批量发消息时请自行控制节奏。创建群聊、直接加人和发送入群邀请使用独立的后台等待路径，等待回包只占用当前连接，不阻塞其他业务请求；同群操作仍由业务服务限制并发，详见群操作。其他长等待接口的并发方式以各自章节为准。

2.4 请求体必须合法

• 必须是 UTF-8 编码的 JSON 对象。
• body 解析失败或JSON不是对象时，插件会当作空参数继续走业务流程，不会独立返回JSON语法错误。多数旧接口表现为 400 加业务错误；创建群聊、直接加人和发送入群邀请返回 200 的完整参数失败结果。无论状态码如何，参数失败时都应先检查JSON是否合法。
• 建议始终显式带上 Content-Type: application/json。

2.5 参数的类型转换很宽松

多数接口对参数类型做过兼容处理，这对你是好消息也是陷阱：

⚠️ 陷阱：因为转换宽松，类型写错不会报错，只会得到意想不到的结果。例如把数字 limit 写成 "abc" 会被当作 0，而不是报参数错误。

资料设置接口和资料预校验探针使用严格类型校验：sex 只接受整数 0/1/2，拒绝布尔值、小数（包括 1.0）、字符串和 null；文本必须是字符串。签名保持原始文本，拍一拍由微信原生规则处理空白，均不适用上面的通用字符串裁剪规则。

收藏三项接口同样严格校验参数，详见收藏用法，不适用上面的自动转换和裁剪规则。

2.6 方法严格匹配

每个端点的 HTTP 方法都是固定的。用错方法（例如对 GET /account_status 发 POST）会直接落进 404。

2.7 GET 接口的参数位置

GET 类接口（/health、/account_status、/debug/device_status 等）不接受任何查询参数，路径后面的 ?xxx=yyy 会被忽略。媒体读取的operation_id放在路径内，分段范围通过Range请求头传入。

2.8 鉴权

插件有一套授权检查。未授权时，除下列 7 个路径外，所有请求都会被拒绝（返回 403）：

这意味着：你可以用 /health 判断插件是否在线，但未授权时几乎什么都做不了。 授权状态会在响应里以 auth_status 返回。

这里检查的是插件自身的授权资格，当前 HTTP 接口不校验调用方 API Key 或 Bearer Token；应通过可信网络限制谁能访问手机端口。

这里检查的是手机插件自身的授权状态；本地 HTTP 不校验调用方请求 Token，不要求添加 Authorization 请求头。已授权也仍需满足微信登录和对应业务条件。

2.9 功能开关

插件设置页里有若干开关，关闭后多数旧接口返回 400 和 <接口名> is disabled。创建群聊、直接加人和发送入群邀请的新请求返回 200、ok:false、error_code:WRITE_DISABLED；已登记同ID结果的读取先于该开关检查。旧接口示例：

{ "ok": false, "error": "send_message is disabled" }

本文各业务中提到的“发送／转发开关”表示底层有效状态，当前都跟随插件总开关；调用方如需分别控制发送与接收，应自行限制对应操作。

例外（不做开关检查的接口）：/download_message_image、所有 /debug/* 探针、/livephoto_probe、/livephoto_diagnostics、/room_members、/get_group_notice、/get_chatroom_qrcode、/get_self_qrcode、/get_group_invitation、/friend_pay_name、/friends*、/groups_all 不受发送开关拦截。

后台保活另有独立设置，不改变上述业务接口开关：

两种通道可单独或同时开启。audio_enabled/location_enabled 表示保存的选择，实际运行看 保活状态接口 的 enabled/active/audio_playing/location_updates_requested/location_active/timer_active；总开关关闭后子配置仍为 true 属于正常行为。查询该接口不会开启保活。

3. 返回结果与错误

所有 HTTP JSON 响应（包括成功和错误）都会带顶层 version 字段，当前为 "8.0.80-2"。下方业务示例省略这一公共字段；build_marker 用于区分同版本的不同构建，接入时保存设备实际返回值；示例中的历史构建标记不代表当前安装包。当前源码标记为 webridge_build_20261106_settings_update_8080。

3.1 状态码总表

排错提示：404 的响应体里回显了你实际请求的 method 和 path。路径拼错时直接看这两个字段，比猜快得多。

3.2 传输成功、业务受理与最终完成

不要只看 HTTP 状态码，也不要只看 ok。

多项接口会在业务失败时保留完整结果并返回 HTTP 200；异步任务和发送操作还可能先返回“已受理”。因此先检查传输状态和 ok，再按该接口的 status、确认字段判断最终结果。

推荐的判断顺序：

1. HTTP 状态码是 200
2. 且响应体里 ok == true

好友支付姓名和群二维码查询会等待终态，分别检查 pay_name_status 和 status，详见支付姓名查询及群二维码查询。朋友圈等异步动作还必须等待终态；媒体上传需upload_completed=true，不能用首次ok=true判断完成。详见本篇朋友圈流程。

收藏发送的 accepted 仅表示本地链路受理；删除成功须 status:"deleted" 且 server_confirmed:true，详见收藏状态与重试。

3.3 error 字段

• 成功时可能是空字符串 ""，也可能不存在在响应里（取决于接口）。
• 失败时是非空字符串，内容是原因描述。
• 最外层的错误原因来自统一封装；个别接口失败时，响应体会直接采用业务层返回的完整结果对象（可能额外带 uploaded、message_id 等字段），此时 error 依然是字符串。

不要精确匹配 error 的文案做流程分支，它可能随版本调整。有 error_code 时优先按该接口的错误码处理；同时检查 HTTP 状态码、ok 和业务状态，把 error 留作日志。

4. 健康检查与事件接收

GET / 与 GET /health

两者完全等价，返回同一份内容。它们均免鉴权，适合作为连通性探针；其他免鉴权路径见第 2 节。

响应示例：

{
  "ok": true,
  "plugin": "webridge",
  "version": "8.0.80-2",
  "command_poll_url": "",
  "long_poll_interval_seconds": 20,
  "auth": {},
  "auth_authorized": true,
  "auth_status": "authorized",
  "bind_address": "0.0.0.0",
  "listen_port": 19088,
  "plugin_enabled": true,
  "receive_enabled": true,
  "send_enabled": true,
  "forward_enabled": true,
  "mock_enabled": true,
  "log_capture_enabled": true,
  "log_entry_count": 0,
  "build_marker": "webridge_build_20261106_settings_update_8080"
}

注意：/health 不会告诉你"长轮询/WebSocket 哪个在生效"，只会给你 command_poll_url。判断传输模式请以插件设置页为准。

4.1 主动拉取微信事件

POST /events

供只使用插件本地 HTTP 接口的调用方主动拉取收到的微信消息、好友申请、群成员变化等事件。该接口始终可用，不参与“长轮询 / WebSocket”模式选择。

事件捕获后会复制一份到独立的 HTTP 事件缓冲区，同时继续走当前长轮询或 WebSocket 链路：

微信事件
  ├─ HTTP 事件缓冲区 -> POST /events 拉取
  └─ 当前传输模式
       ├─ 长轮询 -> POST /agent/event
       └─ WebSocket -> event 帧

调用 /events 不会删除长轮询或 WebSocket 队列中的消息，也不会影响发送、查询等其他 HTTP 接口。多个 HTTP 客户端各自保存自己的 offset，读取时互不抢占。

请求字段：

调用方自身的 HTTP 超时必须大于 timeout_seconds，建议至少多留 5 秒，例如请求等待 20 秒时把客户端超时设为 25 ~ 30 秒。

首次请求：

curl -X POST http://192.168.0.100:19088/events \
  -H "Content-Type: application/json" \
  -d '{"offset":0,"limit":50,"timeout_seconds":20}'

有事件时响应：

{
  "ok": true,
  "events": [
    {
      "update_id": 1780000000101,
      "device_id": "webridge_device_xxx",
      "session_id": "sess_xxx",
      "account_id": "wxid_self",
      "runtime_version": "8.0.80-2",
      "build_marker": "webridge_build_20261106_settings_update_8080",
      "ts_ms": 1780000000101,
      "event_name": "message",
      "event_id": "msg:7307587870543245070",
      "captured_at_ms": 1780000000090,
      "enqueued_at_ms": 1780000000100,
      "body": {
        "message_id": "7307587870543245070",
        "msg_type": "text",
        "chat_id": "wxid_friend",
        "room_id": "",
        "sender_id": "wxid_friend",
        "is_group": false,
        "content": "你好"
      }
    }
  ],
  "next_offset": 1780000000102,
  "earliest_offset": 1780000000101,
  "latest_offset": 1780000000101,
  "has_more": false
}

客户端应在整批事件处理成功后保存响应中的 next_offset，下一次原样回传：

curl -X POST http://192.168.0.100:19088/events \
  -H "Content-Type: application/json" \
  -d '{"offset":1780000000102,"limit":50,"timeout_seconds":20}'

如果暂时没有事件，请求会等待，事件到达后立即返回；等待到期仍没有事件时正常返回空数组：

{
  "ok": true,
  "events": [],
  "next_offset": 1780000000102,
  "earliest_offset": 1780000000101,
  "latest_offset": 1780000000101,
  "has_more": false
}

收到空数组不是错误。客户端应立即使用相同 offset 发起下一轮请求。

消费语义：

• 接口提供至少一次（at-least-once）读取语义，不承诺 exactly-once。
• 客户端处理成功后才保存 next_offset；处理中途失败时继续使用旧 offset，事件会再次返回。
• 调用方应按 event_id 做业务去重。
• limit 只限制单次响应条数；has_more: true 时应使用 next_offset 立即继续拉取。
• /events 本身不删除消息；事件只会因最大条数、最大暂存时间或用户手动清空而淘汰。

offset 已过期：

HTTP 事件缓冲区复用设置页的“最大暂存条数”和“最大暂存时间”。请求位置已经被淘汰、进程重启导致旧事件消失，或者设置页手动清空后，接口返回 HTTP 200 和：

{
  "ok": false,
  "error": "offset_expired",
  "message": "请求位置已超出当前事件保留范围，请从 next_offset 重新拉取",
  "requested_offset": 1780000000001,
  "earliest_offset": 1780000000101,
  "latest_offset": 1780000000120,
  "next_offset": 1780000000101,
  "events": [],
  "has_more": false
}

这表示中间可能有事件已丢失。调用方应记录告警，再根据业务选择从 next_offset 继续，不能把它当成普通空队列静默忽略。恢复方式见 4.2。

暂存设置：

• 默认最多保留 500 条，硬上限 5000 条。
• 默认最长保留 2 分钟，设置为 0 表示不过期。
• “断线后启用暂存”只控制长轮询和 WebSocket 的失败补发，关闭它不会关闭 HTTP 事件缓冲区。
• 设置页分别显示“当前传输暂存”和“HTTP 事件暂存”。
• “一键清空暂存”会清理当前传输队列和 HTTP 事件缓冲区，不会清理当前未启用的另一种传输队列。

4.2 游标、分页与客户端循环

offset 是本次希望读取的起始位置，不会删除服务端事件。首次传 0，之后只使用响应中的 next_offset；正常响应须在整批处理成功后再保存，网络异常和业务处理失败时保留原游标，重读后按完整 event_id 去重。

4.2.1 事件解析

每种事件的完整 body 定义见 4.3。不要把红包、转账或好友申请套入普通 message 字段。还需注意：

• 本机发出的消息也可能入队，结合 sender_id 和事件信封的 account_id 判断方向。
• 消息 ID 按字符串保存，不假设固定长度；文件和链接属于 msg_type=app，由 msg_subtype 区分。
• 图片事件提供媒体引用，不包含可由电脑直接读取的图片文件；获取文件使用 媒体接口。
• is_at 与 at_user_list 的含义不同，按事件字段说明处理；去重须比较完整 event_id，不能只取其数字后缀。

4.2.2 当前游标和分页规则

空批次与 has_more:false 均正常；处理完后立即开始下一轮。has_more:true 时已有积压可继续读取，下一次也可以仍带原等待参数：已有事件时不会等待。

4.2.3 游标过期和连接异常

• 只有 HTTP 200、ok:false 且 error=offset_expired 时，才记录可能丢失事件的告警，并按响应的 next_offset 恢复。继续用旧游标会反复收到同一错误。
• 响应不提供丢失条数，不能用游标差或 latest_offset-earliest_offset+1 计算准确丢失量或队列长度；重启、空缓冲和淘汰都会影响这些数值。
• HTTP 400／403／429、其他 ok:false、网络超时或响应缺少合法 next_offset 时，不推进游标；分别修正参数、处理授权、减少等待并发或退避重试。
• /health.http_event_queue_count 是另一次状态快照，不能替代本批返回的事件和游标。
• 正常响应会关闭连接；等待中提前断线按瞬时网络异常处理，保留游标重试。客户端超时须大于 timeout_seconds，建议多留 5～10 秒。

历史 0.8.76 联调曾观察到少量事件下 has_more 始终为 false，这不能证明当前实现固定返回 false。上述规则按当前事件存储实现核对；本次文档整理未重新进行真机联调。

4.2.4 客户端循环

单个客户端串行拉取；正在等待新事件的请求全局最多 4 个。UTF-8 解析响应，整批处理成功后持久化 next_offset。Windows 排错时可先保存响应原文再按 UTF-8 查看，避免把终端编码问题当成接口内容错误。

offset = 0 或本客户端上次保存的 next_offset
循环:
    resp = POST /events {offset, limit, timeout_seconds}
    若网络异常或 HTTP 非 200:
        保留 offset；按状态处理授权、参数或限流，必要时退避重试
    否则若 resp.ok == true:
        校验 events 和 next_offset
        按 event_id 去重并处理整批事件
        整批成功后保存 offset = resp.next_offset
    否则若 resp.error == "offset_expired" 且 next_offset 合法:
        告警：保留范围外的事件可能已丢失，响应不提供丢失条数
        保存 offset = resp.next_offset
    否则:
        保留 offset，记录错误并处理原因，不静默跳过事件

4.3 完整事件类型与 body 字段

以下示例仅展示 /events 响应中 events[] 的 event_name、event_id 和 body 部分；update_id、账号／设备标识及时间戳仍按4.1读取。消息方向结合 sender_id 与事件信封的 account_id 判断，本机发送的消息也可能入队。本节包含纯 HTTP 接入所需的全部事件定义，无需查阅 WebSocket 或长轮询文档。

4.3.1 事件类型总表

4.3.2 message 事件

{
  "event_name": "message",
  "event_id": "msg:7307587870543245070",
  "body": {
    "message_id": "7307587870543245070",
    "msg_type": "text",
    "raw_message_type": 1,
    "chat_id": "50136399923@chatroom",
    "room_id": "50136399923@chatroom",
    "sender_id": "wxid_member",
    "is_group": true,
    "is_at": false,
    "at_user_list": [],
    "at_all": false,
    "create_time": 1774772029,
    "content": "你好"
  }
}

恒有字段（一定会出现）

消息类型对照

⚠️ 注意一个真实差异：代码里的 msg_type 实际取值包含 contact_card 和 app，没有 file 和 link。文件和链接是 app 类型下的子分类，靠 msg_subtype 区分。请不要按 msg_type == "file" 来判断文件消息。

条件字段（只在满足条件时出现，不满足则整个字段不存在）

⚠️ 判断文件消息的正确方式：msg_type == "app" 且 msg_subtype == "file"。

被主动剥掉的字段（不会出现在 body 里）

from_user、to_user、sender_id_type、real_chat_user、source、hook_selector、hook_type、self_user、以及内部的 msg_id（已被改名为 message_id）。

这意味着服务端拿不到"这条消息是发给谁的"直接的收发方向字段，只能靠 chat_id / room_id / sender_id / is_group 自己推断方向。这是设计如此，不是 bug。

群内 @ 字段的精确语义

三条必须知道的约定：

1. @所有人 时微信写入的是协议标记 notify@all 而不是 wxid，插件按原样透出并同时给出 at_all: true，不会展开成全部群成员（消息时刻的成员列表无法还原，展开会失真）
2. is_at 与 at_user_list 相互独立：is_at 以微信自身判断为准，at_user_list 是消息里的原始名单。@所有人 或消息未携带相关数据时，可能出现 is_at: true 而 at_user_list 为空
3. 群消息中 chat_id 与 room_id 相同且 is_group 为 true；私聊中 room_id 为空串、is_group 为 false

4.3.3 拍一拍

msg_type 为 pat，走系统消息通道，raw_message_type 为 0：

{
  "event_name": "message",
  "event_id": "msg:7307587870543245070",
  "body": {
    "message_id": "7307587870543245070",
    "msg_type": "pat",
    "raw_message_type": 0,
    "chat_id": "wxid_friend",
    "room_id": "",
    "sender_id": "wxid_friend",
    "is_group": false,
    "create_time": 1774772029,
    "content": "你拍了拍自己",
    "pat_from_user": "wxid_friend",
    "pat_patted_user": "wxid_self",
    "pat_template": "你拍了拍自己"
  }
}

注意两个字段的区别：content 是把 ${wxid} 占位符替换成显示名之后的文案（给人看的）；pat_template 是未解析的原始模板。要展示请用 content。

4.3.4 红包事件

{
  "event_name": "red_packet_received",
  "event_id": "red_packet:rp_msg_7307587870543245070",
  "body": {
    "red_packet_id": "rp_msg_7307587870543245070",
    "message_id": "7307587870543245070",
    "chat_id": "50136399923@chatroom",
    "room_id": "50136399923@chatroom",
    "sender_id": "wxid_sender",
    "from_user": "wxid_sender",
    "to_user": "wxid_self",
    "create_time": 1774772029,
    "raw_message_type": 49,
    "send_id": "1000039501202603311234567890",
    "channel_id": "1",
    "msg_type": "1",
    "native_url": "…",
    "sign": "",
    "scene_id": 1002,
    "session_user_name": "…",
    "nick_name": "…",
    "head_img": "",
    "is_group": true,
    "is_openim": false,
    "is_group_sender": false,
    "in_way": "0",
    "timing_identifier": "",
    "status": "received",
    "created_at_ms": 1774772029000,
    "updated_at_ms": 1774772029000
  }
}

⚠️ 红包事件 body 里没有 content / content_xml，也没有 app_msg_* 系列字段——它是独立构造的，不复用消息字段。

4.3.5 转账事件

{
  "event_name": "transfer_received",
  "event_id": "transfer:1000050001202604140530193566598",
  "body": {
    "transfer_id": "1000050001202604140530193566598",
    "message_id": "8871556727500760296",
    "chat_id": "wxid_demo_account",
    "room_id": "",
    "sender_id": "wxid_demo_account",
    "from_user": "wxid_demo_account",
    "to_user": "wxid_demo_friend",
    "real_chat_user": "wxid_demo_account",
    "current_user": "wxid_demo_friend",
    "receiver_username": "wxid_demo_friend",
    "payer_username": "",
    "control_transaction_id": "53010002669213202604143932510122",
    "amount_text": "￥0.02",
    "amount_value": "0.02",
    "amount_fen": 2,
    "memo": "",
    "remark": "",
    "nickname": "…",
    "app_msg_type": 2000,
    "app_msg_title": "微信转账",
    "app_msg_desc": "",
    "app_msg_url": "",
    "msg_subtype": "…",
    "content": "",
    "content_xml": "<msg>...</msg>",
    "native_url": "",
    "create_time": 1774772029,
    "raw_message_type": 49,
    "status": "received",
    "created_at_ms": 1774772029000,
    "updated_at_ms": 1774772029000,
    "pay_info_class": "…",
    "pay_info_probe": {}
  }
}

金额字段说明（三个都有，别搞混）：

身份字段说明（六个高度重叠，按需取用）：

建议至少持久化：transfer_id、message_id、control_transaction_id、amount_text、amount_fen、sender_id、chat_id。 推荐用 transfer_id 去重。

注意：

转账退还结果事件 transfer_refund_result

本事件沿本模式标准事件外壳传输。HTTP 通过 /events 拉取；WebSocket 使用 event 帧；长轮询上报到 /agent/event。下面展示本节相关字段，公共时刻、设备、账号与队列字段按本模式事件约定携带：

{
  "event_name": "transfer_refund_result",
  "event_id": "transfer_refund:refund_result_example",
  "body": {
    "ok": true,
    "transfer_id": "transfer_example",
    "message_id": "message_example",
    "accepted": true,
    "confirmed": true,
    "status": "refunded",
    "native_status": 2002,
    "ret_code": 0,
    "error_code": "",
    "error": "",
    "refund_result_id": "refund_result_example",
    "source": "webridge_live"
  }
}

body 保留退还业务结果的全部基础字段：ok、transfer_id、message_id、accepted、confirmed、status、native_status、ret_code、error_code、error，另有非空 string refund_result_id（本次结果事件的独立标识）及 string source（来源诊断字段，不用于业务判断）。微信错误回包还可能带 wx_error_type（integer 或 null）。字段类型、所有状态与错误码见本文 转账退还与查询。event_id 为 transfer_refund:<refund_result_id>，消费时按完整 event_id 去重，不按 transfer_id 去重，以免把查询或后续结果吞掉。

事件名不代表成功：只有 native_status=2002 且 status="refunded" 才确认已退还。已进入退还提交且操作结束时才可能产生事件，可能是成功、失败或 refund_unknown；仅返回 refund_pending 时还未结束，后续回包或主动查询查到终态可能完成原动作并产生事件。在 refund_unknown／failed 等已结束动作之后再查询，只保证返回状态和回收占用，不保证补发第二个退款结果事件。 未提交就被拒绝、预检发现已经退还均不发此事件；账号会话变化后的旧结果不投递给新账号。因此客户端必须保留主动查询路径，不能只等事件。

4.3.6 群成员变更事件

{
  "event_name": "group_member_join",
  "event_id": "msg:group_member_join:50136399923@chatroom:wxid_member:1775000001123",
  "body": {
    "room_id": "50136399923@chatroom",
    "member_id": "wxid_member",
    "member_nick_name": "张三",
    "member_remark": "",
    "member_alias": "",
    "member_display_name": "张三",
    "room_nick_name": "项目群",
    "room_remark": "",
    "message_id": "group_member_join:50136399923@chatroom:wxid_member:1775000001123",
    "snapshot_before_count": 23,
    "snapshot_after_count": 24,
    "create_time": 1775000001,
    "is_group": true
  }
}

group_member_leave 使用相同的群／成员字段，表示成员离开；snapshot_before_count、snapshot_after_count 分别为变更前后成员数。

昵称变更事件额外带：

{
  "event_name": "group_member_nickname_change",
  "body": {
    "old_room_nick_name": "lumen",
    "new_room_nick_name": "lumen123",
    "snapshot_before_count": 23,
    "snapshot_after_count": 23
  }
}

注意：

4.3.7 好友申请事件

event_name 为 friend_request。

这个事件的 body 结构有明显的不确定性：event_id 会按以下优先级生成，说明至少存在三种数据形态：

1. 有申请 ID → friend_request:<申请ID>
2. 否则有消息 ID → msg:<消息ID>
3. 都取不到 → 兜底 evt:<毫秒>

恒有字段：

条件字段（取不到则不出现）：

⚠️ 同意好友申请前请先校验 encrypt_username 和 ticket 是否都存在，缺失时不要盲调 accept_friend_request。

识别条件：只有满足特定特征的消息才会成为 friend_request 事件，否则会退回普通 message 事件。所以不要假设每个好友申请都一定会以 friend_request 出现。

4.3.8 HTTP 拉取的可靠性

HTTP 事件缓冲区独立、有界且只在当前进程内保留；不套用远程事件的磁盘补发规则。所有事件按完整 event_id 去重，同一客户端串行拉取，全部处理成功后再保存 next_offset；游标过期按 offset_expired 恢复，具体容量、TTL、等待和恢复流程见本篇第 4 节。不要根据游标数值差推算精确丢失条数。

5. 完整端点索引

按业务查找入口；完整参数、成功判断和重试边界见对应章节。通用诊断列表见第 18 节，旧路径与已移除入口见第 19 节。

5.1 健康与事件

5.2 消息发送与操作

5.3 媒体

5.4 好友与联系人

5.5 群聊

5.6 会话、红包与转账

5.7 账号资料与个人二维码

5.8 朋友圈

5.9 收藏

5.10 公众号

5.11 状态与专题诊断

6. 消息发送

以下接口共用同一个接收方参数：receiver。

receiver 的取值：

部分接口为了兼容旧调用方，还接受 toUser、to、chatId、target 等别名。新接入请统一用 receiver，别用别名。

POST /send_message

用途：发送文本消息，支持 @、@所有人、引用、引用并 @。

请求字段：

mention_user_list 的别名（历史兼容，新接入请只用 mention_user_list）：还接受 at_user_list；此外 at_user（单个 wxid）会被并入 @ 名单最前面。

发送模式自动推导（你不需要传 mode）：

正文内联 @：

• content 里可以用 {{mention:wxid}} 占位符，在正文任意位置插入 @。
• 插件会自动把占位符渲染成 @显示名，并同步写入消息的 @ 名单。
• 即使你不传 mention_user_list，只要正文里出现了 {{mention:wxid}}，插件也会自动提取并走 @ 链路。
• ⚠️ 如果占位符里的 wxid 解析不出备注名或昵称，整条消息会被拒绝发送（避免正文里直接出现原始 wxid）。

@所有人：

• 仅群聊可用：把 mention_user_list 设为 ["notify@all"]。
• notify@all 是微信的 @所有人协议标记，不是用户 wxid，不要展开成全部群成员。
• mention_user_list 负责触发通知，content 里的 @所有人 只负责正文展示。
• 插件不会自动往 content 里补 @所有人。要在聊天界面看到这四个字，必须你自己写进 content。
• 是否允许发送仍受微信群主/管理员权限限制，插件不绕过微信的权限校验。

示例：

curl -X POST http://192.168.0.100:19088/send_message \
  -H "Content-Type: application/json" \
  -d '{
    "receiver": "50136399923@chatroom",
    "quote_message_id": "5611615190048272387",
    "mention_user_list": ["wxid_demo_account", "wxid_3c5980ggo5se22"],
    "content": "我现在{{mention:wxid_demo_account}}，然后我还想在这里{{mention:wxid_3c5980ggo5se22}}。"
  }'

成功响应：

{
  "ok": true,
  "receiver": "50136399923@chatroom",
  "quote_message_id": "5611615190048272387",
  "mention_user_list": ["wxid_demo_account", "wxid_3c5980ggo5se22"]
}

失败响应：400 + {"ok": false, "error": "<原因>"}。常见原因：接收方为空、内容为空、wxid 无法解析、发送开关关闭。

POST /send_image

用途：发送图片。

请求字段：

成功响应：

{
  "ok": true,
  "resolved_image_path": "/var/mobile/.../photo.jpg",
  "receiver": "wxid_friend",
  "downloaded": false
}

前置条件：发送开关必须开启，否则 400 "send_image is disabled"。

POST /send_emoji

用途：发送表情（gif / png / jpg / jpeg 均可）。

大小限制读取当前微信动态配置，实际值见/debug/emoji_send_probe的limits.max_file_size/max_dimension。字节上限为两种原生配置较大值与20MiB保护上限的较小值；静态默认5MiB不能替代真机配置。转换前和读取数据后均检查，超限明确报错，不提交发送。

请求字段：

说明：

• 远程图片会自动下载到插件沙盒，缓存 1 天后自动清理。
• 不是 gif 的图片会被转换成微信表情格式。

成功响应：

{
  "ok": true,
  "receiver": "wxid_friend",
  "source": "https://example.com/demo.png",
  "source_type": "remote_url",
  "emoji_path": "/var/mobile/.../demo.gif",
  "resolved_emoji_path": "/var/mobile/.../demo.gif",
  "downloaded": true,
  "emoji_md5": "…",
  "message_type": 47,
  "message_type_name": "emoji"
}

POST /send_voice

用途：发送语音。

请求字段：

别名（这些字段名插件都认，但新接入请统一用上面的）：

说明：

• 如果 source 本身就是 .aud 格式（微信语音格式），直接发送。
• 否则插件会自动提取音频、转 PCM、编码成 SILK .aud 再发。这个过程有耗时，请把客户端超时设宽一些。
• MP3、视频链接都能走这条路。

成功响应：

{
  "ok": true,
  "receiver": "wxid_friend",
  "source": "https://example.com/audio.mp3",
  "source_type": "remote_url",
  "resolved_local_path": "/var/mobile/.../audio.mp3",
  "resolved_pcm_path": "/var/mobile/.../audio.pcm",
  "resolved_wechat_aud_path": "/var/mobile/.../audio.aud",
  "duration_ms": 3240,
  "downloaded": true,
  "message_type": 34,
  "message_type_name": "voice"
}

POST /send_video

用途：发送视频。

请求字段：

默认上限：两个都不传时，默认 10 MiB（10485760 字节）。

别名：source 也接受 video_url、video_path。

说明：远程 URL 会先做大小探测，超限直接失败，不会白下载。

成功响应：

{
  "ok": true,
  "source": "https://example.com/test.mp4",
  "source_type": "remote_url",
  "resolved_video_path": "/var/mobile/.../test.mp4",
  "resolved_thumb_path": "/var/mobile/.../thumb.jpg",
  "receiver": "wxid_friend",
  "video_duration": 12.5,
  "generated_thumb": true,
  "downloaded": true,
  "max_size_bytes": 10485760,
  "max_size_mb": 10,
  "within_size_limit": true,
  "remote_size_known": true,
  "remote_size_bytes": 8123456
}

POST /send_video_from_url

用途：发送视频（URL 专用入口）。参数与 send_video 相同，区别是成功响应里会多一个 video_url 字段，且 downloaded 的判定按 URL 来源计算。

适用场景：你的服务端只想传链接时，用这个接口语义更明确。

POST /send_livephoto

用途：发送实况照片（Live Photo）。

请求字段：

字段名 prefered_hevc 确实是这个拼法（少一个 r），不是笔误，请照写。

⚠️ 这两个可选字段在本接口（HTTP）上不做字符串转换，必须传 JSON 原生类型： - still_image_time_ms 必须传数字（传 "100" 会被当作没传） - prefered_hevc 必须传布尔值（传 "true" 会被当作 false）

这是 HTTP 接口与命令通道（长轮询/WebSocket）的一个真实行为差异——命令通道会做类型转换，HTTP 接口不会。

成功响应：

{
  "ok": true,
  "video_path": "...",
  "image_path": "...",
  "receiver": "wxid_friend"
}

失败响应：400 "send_livephoto is disabled" 或 400 + 具体原因。

POST /send_file

用途：发送文件（本地路径）。

成功响应：

{
  "ok": true,
  "resolved_file_path": "/var/mobile/.../report.pdf",
  "receiver": "wxid_friend",
  "file_name": "report.pdf",
  "file_size": 204800,
  "extension": "pdf"
}

POST /send_file_from_url

用途：发送文件（远程 URL）。

成功响应：比 send_file 多两个字段：

{
  "ok": true,
  "resolved_file_path": "...",
  "receiver": "wxid_friend",
  "file_name": "report.pdf",
  "file_size": 204800,
  "extension": "pdf",
  "source_url": "https://example.com/report.pdf",
  "downloaded": true
}

POST /send_link_card

用途：发送链接卡片。

成功响应：

{
  "ok": true,
  "receiver": "wxid_friend",
  "title": "标题",
  "url": "https://example.com",
  "thumb_url": ""
}

POST /send_music_card

用途：发送音乐卡片。注意：这个接口内部走的是转发链路（relay_* 字段会体现在响应里），不是直接构造消息。

别名表（这个接口为了兼容历史调用方，别名特别多）：

重要：url、data_url、song_album_url、app_id、app_name 这五个字段不传会用内置默认值兜底（默认指向一个示例音乐）。也就是说缺参数不会报错，会发出去一张指向默认歌曲的卡片。要发自己的音乐，这五个字段请全部显式传入。

请求示例（URL 和应用信息均为占位值，需替换）：

{
  "receiver": "filehelper",
  "title": "歌曲标题",
  "desc": "歌手 - 专辑",
  "url": "https://music.example.com/song/1",
  "data_url": "https://media.example.com/song/1.mp3",
  "song_album_url": "https://media.example.com/song/1.jpg",
  "app_id": "wx_example_music_app",
  "app_name": "音乐应用"
}

成功响应：

{
  "ok": true,
  "receiver": "wxid_friend",
  "title": "歌曲名",
  "desc": "",
  "url": "https://music.example.com/song",
  "dataurl": "...",
  "songalbumurl": "...",
  "app_id": "wx...",
  "app_name": "网易云音乐",
  "songlyric_length": 0,
  "relay_forward": true,
  "relay_chat": "filehelper",
  "relay_delete_staged": true
}

songlyric_length 为实际歌词的 UTF-16 长度；未提供歌词时为 0。

relay_* 字段说明该卡片是通过"先发到文件传输助手再转发"的链路实现的。如果你在文件传输助手里看到过残留，属正常现象，插件会清理。

POST /send_contact_card

发送已有联系人的原生名片。头像和昵称由微信联系人资料生成，接口不接收自定义头像或昵称。

{"receiver":"filehelper","contact_id":"wxid_example"}

也可传 {"receiver":"filehelper","contact_id":"wechat_alias_example"}。先查询内部 ID；微信号使用本机联系人资料及已有好友列表精确匹配 alias，不按昵称或备注模糊选择，也不会自动联网搜索陌生人。若匹配不唯一则拒绝发送。成功响应的 contact_id 统一为解析后的真实 user_name。

成功响应示例：

{"ok":true,"submitted":true,"receiver":"filehelper","contact_id":"wxid_example","message_type":42}

普通名片外层类型为 42；OpenIM / OpenIM 客服联系人沿用微信原生判断为 66 / 67。ok:true、submitted:true 表示已调用原生消息提交方法，不代表收到服务器成功回执或对方已收到。名片发送已由用户在微信 8.0.80 验证通过；特殊联系人仍按微信实际返回处理。

POST /send_location

发送单次位置消息，外层类型 48。最少传收件人及经纬度；标题和地址可由微信坐标反查补全。

{"receiver":"filehelper","latitude":23.012345,"longitude":113.123456}

指定文字时：

{"receiver":"filehelper","latitude":23.012345,"longitude":113.123456,"title":"园区南门","address":"示例路 1 号"}

title、address 都为空或省略时，插件调用微信原生反查，等待回调最多 15 秒。优先采用带方向的地理描述，再尝试地址或 POI 名称；不能保证反查得到指定商户名称。需要精确显示名称时应传 title。传入的文字只接受字符串，空白串按省略处理，null 为参数错误。

反查失败、超时、结果没有可用文字或等待期间账号/登录会话变化时，不提交位置消息；返回 HTTP 400，响应保留诊断字段。经纬度同时为 0 时微信反查入口会拒绝，可通过显式 title 跳过反查。插件原样使用传入坐标，不转换坐标系，外部 GPS 坐标须先核对与微信地图的对应关系。

成功响应示例：

{
  "ok":true,"submitted":true,"receiver":"filehelper","message_type":48,
  "latitude":23.012345,"longitude":113.123456,
  "title":"园区南门","address":"示例路 1 号","title_source":"provided"
}

title_source 为 provided（显式标题）、address（地址作为标题）、wechat_geocode（微信反查）。submitted:true 仅表示已提交原生发送，不表示服务端确认送达。此接口和名片发送受插件启用、授权及发送开关约束。

POST /send_xml

用途：直接发送原始 appmsg XML。给高级用法准备的逃生舱。

说明：

• xml 会原样写入消息，插件不做裁剪或重写。写错了就是发出去一条坏消息，插件不会帮你校验。
• 想发微信官方客户端不支持的卡片类型，这是唯一的入口。

请求示例：

curl -X POST http://192.168.0.100:19088/send_xml \
  -H "Content-Type: application/json" \
  -d '{
    "receiver": "filehelper",
    "type": 5,
    "forward": false,
    "xml": "<msg><appmsg><title>XML接口测试</title><des>原始XML发送测试</des><action>view</action><type>5</type><url>https://example.com</url></appmsg></msg>"
  }'

成功响应：透传业务结果，ok 为 true，其余字段由发送链路返回。

POST /send_signal

用途：发送"小信号"（微信的轻量提醒）。

说明：设计上只建议用于一对一联系人，不建议把群 ID 当接收方。

成功响应：

{
  "ok": true,
  "receiver": "wxid_demo_account",
  "cgi": 976,
  "event_flag": 5,
  "client_msg_id": 4976413716,
  "create_time": 1777500000
}

POST /send_pat

用途：发送"拍一拍"。

成功响应：

{
  "ok": true,
  "receiver": "wxid_demo_account",
  "room_id": "48398681165@chatroom",
  "is_group": true,
  "scene": 0,
  "selector": "..."
}

7. 消息操作

POST /forward_message

用途：转发一条已存在的消息。

表情在同一请求内检查缓存、必要时触发微信原生下载，资源就绪后才转发并等待目标消息最终发送状态；无需先打开对话或另外调用下载接口。下载与发送各最多等待30秒。下载失败不会转发；已提交但无法确认会提示结果未知，此时不要自动重发，应核对目标消息。成功JSON保持原结构。

成功响应：{"ok": true, "message_id": "...", "receiver": "..."}

前置条件：转发开关必须开启。

POST /revoke_message

用途：撤回一条消息。

成功响应：{"ok": true, "message_id": "..."}

⚠️ 微信自身对撤回有时限（2 分钟），超时会被微信拒绝并返回 400。插件不绕过这个限制。

8. 媒体下载与上传

适用插件：8.0.80。既有版本的图片、SILK 语音、视频、普通文件、表情的 HTTP 下载与上传，以及微信 CDN 上传已通过联调；视频和动画表情已验证缓存复用。三种通道共用同一媒体业务服务；本节分别给出当前通道的完整调用约定。

HTTP 成功返回 200，参数或业务失败返回 400，授权限制沿用原约定（403）。客户端总超时建议设为 200 秒。业务接口的 timeout_seconds 是插件本次等待时间，范围 1～180 秒。

支持 image 图片、voice 语音、video 视频、file 普通文件（49/6）、emoji 普通表情。微信 WXGF/WXAM 表情转换为 GIF，保留动画；原本为 GIF、PNG、JPEG、WebP 的表情保留原格式。转换失败返回错误，不输出 .bin；游戏表情不支持导出。语音只输出微信原始 SILK，不转 MP3；Opus 返回 unsupported_voice_codec。

文件初始事件可能为 49/74。微信收到上传完成信息后，会以完成文件覆盖同一本地记录，同时更新服务器消息 ID。插件在账号、会话、localID、双方、类、创建时间和外层类型均匹配，并且完成文件明确声明覆盖原服务器 ID 时，可继续使用原事件的 message_id 下载或上传；正常业务刷新会保存最终 ID 别名。当前下载白名单仍是普通文件 49/6，不因诊断识别到 74/131 或完成类型 130 就直接开放下载。

0.8.79-82 已通过 HTTP 真机验证：原事件仍缓存为 74，数据库已是完成 6，使用原事件 ID 首次下载 CSV（8,126 字节）和 ZIP（12,155,230 字节）均成功，下载前本地无附件，结果为 downloaded:true、from_cache:false。用户现已确认相关媒体业务在微信 8.0.80 验证通过；仍须满足下文的索引、原聊天记录与文件类型条件。

旧 /download_message_image（含 /debug/download_message_image 别名）和 /upload_message_image 已废弃，仅保留兼容。新接入分别使用 /download_message_media 和 /upload_message_media；图片仍传 message_id，类型自动识别，返回字段按统一媒体接口读取。长轮询 / WebSocket 的旧 upload_message_image 命令同样保留兼容，改用 upload_message_media。

上传接口受插件“消息发送”开关限制；下载和探针不受此开关限制。授权沿用当前通道约定。以下消息 ID、文件路径、资源 ID 和域名均为示意，需替换成实际值。

8.1 下载媒体

请求： POST /download_message_media，Content-Type: application/json。

{
  "message_id": "1234567890123456789"
}

只支持插件已观察到且索引仍有效的消息，不增加任意历史消息查询。

已成功保存完整定位索引的消息可在同一设备、同一账号重启后继续定位；每账号保留最近 2000 条定位记录，内存最多保留 200 个消息对象。原聊天记录须仍存在，未登记、索引被淘汰或身份不匹配时不能仅凭 ID 找回。原事件 ID 刷新到完成文件后，原 ID 和已登记的最终 ID 均可使用；重复下载可复用完整副本。用户已确认相关媒体业务在微信 8.0.80 验证通过，跨重启定位仍受上述保存条件约束。

下载成功示例（数据、路径均为示意）：

{
  "ok": true,
  "message": "已使用缓存文件",
  "message_id": "1234567890123456789",
  "media_type": "voice",
  "downloaded": true,
  "from_cache": true,
  "resolved_local_path": "/var/mobile/Containers/Data/Application/EXAMPLE/tmp/webridge_media/ACCOUNT_HASH/1234567890123456789/voice.silk",
  "resolved_file_name": "voice.silk",
  "file_size": 18576,
  "mime_type": "application/octet-stream",
  "md5": "0123456789abcdef0123456789abcdef",
  "codec": "silk",
  "voice_length_ms": 3260,
  "duration_ms": 42,
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "request_id": "media_download_001",
  "version": "8.0.80-2"
}

resolved_local_path 是手机沙盒路径，服务器无法直接 GET。需要服务器文件时调用上传接口。voice_length_ms 为语音时长，取不到为 0；duration_ms 为接口耗时。语音保持原字节，不播放、不主动设置已听状态。

缓存命中（插件副本或请求开始时微信已具备完整文件）返回 from_cache:true、message:"已使用缓存文件"；新下载返回 false、"下载完成"。图片沿用现有原生下载和解码策略，可能回退微信提供的标准清晰度，不承诺原图。

视频同时检查下载队列、声明大小和副本可读性；原生状态缺失时，必须核对完整文件 MD5 才允许导出，不能仅凭大小一致放行。表情转换后的 file_size、md5 和 mime_type 对应实际导出文件；GIF 的 MIME 为 image/gif。旧 emoji.bin 缓存会自动重新准备。

本次等待超时返回 media_timeout；后台资源准备最多继续到 180 秒。重复相同消息请求会合并正在进行的准备任务；可稍后重试同一个 message_id。

8.2 上传我们的服务器

请求： POST /upload_message_media，Content-Type: application/json。

{
  "message_id": "1234567890123456789",
  "timeout_seconds": 120
}

沿用下载接口参数；timeout_seconds 默认 60，覆盖本次等待准备和 HTTP 上传。另有可选 upload_url、request_id。HTTP 未传 request_id 时生成并返回一个真实请求 ID；当前 HTTP 请求 ID 会写入上传的 command_request_id。

默认 upload_media 就是设置里的业务服务器 base URL 加 /agent/upload_media，保留 base URL 的路径前缀。未配置业务服务器时须传入完整 HTTP/HTTPS upload_url。

请求体为 multipart/form-data，文件字段为 file。文字字段：

服务器必须返回 HTTP 2xx 和 JSON {"ok":true,"asset_id":"实际资源ID"}，其中 asset_id 为非空字符串。可以额外返回 url、local_path，分别映射为 server_url、server_local_path。仅有 HTTP 200 状态、HTML 页面、空响应或缺少 asset_id 都判为失败。视频、文件通过磁盘 multipart 文件上传，不把整个请求体装入内存。

成功返回下载元数据，另加：

{
  "ok": true,
  "message": "上传成功",
  "message_id": "1234567890123456789",
  "media_type": "voice",
  "downloaded": true,
  "from_cache": true,
  "uploaded": true,
  "asset_id": "asset_voice_example",
  "upload_http_status": 200,
  "server_url": "https://example.com/media/asset_voice_example",
  "request_id": "media_upload_001",
  "version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080"
}

from_cache 仅说明源媒体来自本地；每次调用仍向服务器发起上传。上传失败可复用缓存重试；服务器是否按 command_request_id 去重由服务器实现。旧 /upload_message_image 也复用新的磁盘 multipart helper，成功同样要求 ok:true 和非空 asset_id；旧图片接口其他字段保持原约定。

8.3 上传微信 CDN

请求： POST /upload_file_to_wechat_cdn，Content-Type: application/json。

{
  "request_id": "cdn_example_001",
  "file_path": "/var/mobile/Containers/Data/Application/EXAMPLE/tmp/webridge_media/ACCOUNT_HASH/1234567890123456789/voice.silk",
  "timeout_seconds": 120
}

也可以传 {"request_id":"cdn_example_002","file_url":"https://example.com/demo.pdf"}。

首版统一通过“给文件传输助手发送普通文件”完成上传，因此允许产生一条 filehelper 文件消息。下载得到的语音、图片等字节也可提交，但返回的都是普通文件附件票据，不能直接当作图片、语音、视频或表情专用发送票据，也不是公开下载 URL。

只有本次确切消息完成发送，且账号、localID、文件大小、MD5、服务端消息 ID、file_id、AES key 均满足校验时返回成功：

{
  "ok": true,
  "message": "微信 CDN 上传成功",
  "request_id": "cdn_example_001",
  "uploaded": true,
  "pending": false,
  "stage": "uploaded",
  "cdn_type": "file",
  "receiver": "filehelper",
  "file_name": "voice.silk",
  "file_size": 18576,
  "md5": "0123456789abcdef0123456789abcdef",
  "local_id": 123,
  "server_id": "1234567890123456790",
  "cdn": {
    "file_id": "微信实际返回值",
    "aes_key": "微信实际返回值",
    "attach_id": "有则返回"
  },
  "staging_deleted": false,
  "cleanup_status": "pending_ticket_validation",
  "version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080"
}

当前保留临时消息，staging_deleted:false。不启用按条清理，以保留后续发送所需的票据；本包不会因超时删除发送中的消息。CDN 密钥只出现在成功业务响应中，探针不返回密钥或完整 XML。

同账号相同 request_id 绑定原任务，重复参数复用等待或结果，不再次发送；本地文件还存在时会核对内容变化，参数变化返回 request_id_conflict。同 URL 重试指原任务的下载结果，不重新抓取 URL。幂等记录保存在当前微信进程内，重启后失效；结果未知时不要重启后盲目重提。

等待超时返回 ok:false,error:"media_timeout",pending:true；保留同一个 request_id 和文件参数继续调用，或用探针查询。后台最多观察 15 分钟；其后业务接口仍会按原消息重查迟到结果。最多保留 128 个 CDN 请求 ID，达到上限返回 cdn_task_limit，不会淘汰旧任务而隐式重传。

外链文件单次上限 512MB，开始前需预留相应缓存配额；本地文件受全局 1GB 配额限制。源文件、媒体缓存和上传体并存时，实际可用单文件大小会更低。空间不足明确返回错误，不扩大配额。

8.4 调试探针

查询某条消息，不触发下载、播放或发送：

请求： POST /debug/message_media_probe，Content-Type: application/json。

{
  "message_id": "1234567890123456789"
}

消息分支返回 probe_version:2，允许诊断当前下载白名单未支持的 49/74 等消息。探针不触发下载、上传、播放或发送，不回写消息缓存／定位关系，也不创建或清理媒体缓存、不更新缓存使用时间。它仍返回消息／扩展／服务类、语音格式和时长、视频下载队列信息及关键 selector 签名。

database_message 是按已登记会话和 localID 重读、基础身份核验通过的数据库对象快照，cached_message 是已缓存对象在本次诊断中的快照；无对象时为 null。顶层快照优先取数据库，否则取缓存，由 probe_source 标明。两个对象可能来自同一个原生对象，不能把两份结果视为变更前后快照。以下快照字段同时适用于顶层和两份对象：

xml.parsed 表示 XML 是否解析成功；失败时摘要可能只有此字段。xml.type、xml.totallen、xml.overwrite_newmsgid 为根 appmsg 中的十进制字符串或 null；xml.has_attachid、xml.has_cdnattachurl、xml.has_aeskey、xml.has_authkey 为布尔或 0/1，只报告是否非空。不要把不存在的值当作 0，也不要把编号转成 JSON 数字。

完成覆盖已可接受、附件尚未下载的成功响应节选（所有编号为示意）：

{
  "ok": true,
  "message": "已读取媒体状态，未触发下载或发送",
  "probe_version": 2,
  "probe_source": "database",
  "message_id": "1234567890123456789",
  "media_type": "file",
  "type_supported": 1,
  "app_msg_type": 6,
  "native_file_exists": 0,
  "native_size": 0,
  "expected_size": 8126,
  "cache_ready": 0,
  "cached_message": {"app_msg_type": 74, "m_uiMesLocalID": "4096", "m_n64MesSvrID": "1234567890123456789"},
  "database_message": {"app_msg_type": 6, "m_uiMesLocalID": "4096", "m_n64MesSvrID": "1234567890123456790", "m_overwriteNewMsgId": "1234567890123456789"},
  "lookup": {"database_status": "ok", "refresh_accepted": 1, "registered_local_id": "4096", "registered_server_id": "1234567890123456789"},
  "build_marker": "webridge_build_20261106_settings_update_8080"
}

消息探针 ok:true 只说明诊断读取成功。调用下载／上传业务后，才会执行实际资源准备并在成功定位刷新后保存别名。两份快照均无对象时返回 message_not_found，账号变化返回 account_changed；HTTP 失败为 400，授权失败沿用 403。视频原生状态缺失时 native_complete 可以为 false，而业务接口仍可在完整文件校验后成功。

查看已有 CDN 任务，不创建新任务，也不返回 AES / XML：

请求： POST /debug/message_media_probe，Content-Type: application/json。

{
  "request_id": "cdn_example_001"
}

探针 ok:true 表示读取成功；operation_ok、stage、pending、task_finished、task_error 表示上传状态。has_file_id / has_aes_key 仅表示字段是否存在。业务成功结果及票据仍从 /upload_file_to_wechat_cdn 获取。

探针的 message_id 和 request_id 二选一。查询 CDN 时，请求和成功响应里的 request_id 均为被查询的原上传任务 ID。

8.5 缓存文件规则

1. 顺序：插件完整副本 → 微信完整本地文件 → 原生下载。同账号、消息和媒体类型的并发准备合并；同时最多准备 32 项。
2. 插件副本位于 tmp/webridge_media/<账号摘要>/<消息ID>/；微信原文件不移动、不删除。写 .part，校验大小、必要 MD5 和 SILK 头后原子改名；只返回正式副本。
3. 记录文件名、大小、实际 MD5、类型和最近使用时间，不记录 AES 或 XML。命中前检查文件是否存在、可读、非空、大小一致，语音另核对 SILK 头；旧 emoji.bin 不再直接命中，会从微信资源重新导出。
4. 最近使用后保留 1 小时，所有账号共用 1GB 上限，包含本次新增副本、CDN 来源暂存和 multipart 临时文件。空间不足先淘汰最久未使用的空闲项，在用项不删，仍不足返回 cache_space_insufficient。已有其他发送目录继续使用其原有规则。
5. 启动及新任务开始时清理；上传成功也不马上删除。系统可提前回收 tmp，文件丢失后会重新准备。

8.6 后端接收服务复用

聊天媒体与朋友圈媒体可以使用同一个后端应用、同一个端口和同一套存储。 当前上传格式不同，推荐在现有业务后端提供两个接收入口，共用保存文件和生成访问地址的逻辑：

朋友圈使用本篇 朋友圈媒体下载 中的 upload 对象：url 指向上述接收地址，resource_id 由后端分配，method 默认 PUT，headers 可携带鉴权。插件不解析朋友圈上传响应正文，只读取状态码；响应不要超过 64KiB。朋友圈首次受理不等于文件上传完成，仍需等 moments_result 或查询任务，确认 status:"succeeded"、media_ready:true、delivery:"upload"、upload_completed:true。上传结果未知时先按 resource_id 核对后端，插件不会自动重传。

仅处理 multipart 的 /agent/upload_media 不能直接接收朋友圈原始正文，把朋友圈 method 改成 POST 也不会改变正文格式。后端增加原始正文入口即可，插件不需要为了共用后端而改动。两个入口可以共用资源表、文件目录和 GET /files/...；若沿用朋友圈网页示例，需支持按 resource_id 读取，视频读取需支持 Range。

upload_file_to_wechat_cdn 是手机通过微信原生链路上传微信 CDN，不需要自有上传接收服务。其 file_url 可以使用上述后端已有文件地址；返回的普通文件附件票据不能代替朋友圈发布专用上传结果。

仓库中的 demo/消息媒体上传接收端/media_upload_server.py 与 demo/朋友圈媒体上传接收端/server.py 目前仍是两个独立示例，尚未合并；正式接入推荐复用同一业务后端，按本节支持两个入口。

8.7 调用检查与常见错误

HTTP 调试可导入同目录 Apifox 定义（资料未收录），接口位于“08 媒体处理”；旧图片接口为废弃状态。

1. 用新收到事件的 body.message_id 调下载，再调一次检查 from_cache:true；核对文件名、MIME、大小和 MD5。语音应为 SILK，WXGF/WXAM 动画表情应导出 GIF。
2. 调上传我们的服务器，确认文件实际落盘、asset_id 非空；from_cache:true 只表示手机复用源文件，每次请求仍会上传。
3. 下载或上传等待超时可重试同一 message_id；微信 CDN 超时则必须保留原 request_id 和文件参数，避免重复发送。CDN 临时消息目前保留，删除后的票据消费不在已确认范围内。
4. 下载失败时同时提供业务响应和媒体探针响应；CDN 结果未知时用原上传 ID 查询，探针不含可消费票据。

常见错误：invalid_message_id、media_type_mismatch、message_not_found、not_logged_in、account_changed、unsupported_media_type、unsupported_voice_codec、media_timeout、cache_space_insufficient、media_checksum_mismatch、server_upload_failed、upload_url_required、request_id_conflict、cdn_task_limit、cdn_result_unknown。

外层 49、内层仍为 74/131 时，保留错误码 unsupported_media_type，提示为“该文件处于对方或我们，上传尚未完成(上传中)阶段，或完成消息尚未同步，请稍后使用同一 message_id 重试”。这时应等待本机或对方上传完成，且完成消息同步到本机，再用原 ID 调用；不会自动等待上传完成或绕过类型校验。其他不支持的类型仍提示“仅支持图片、语音、视频、普通文件和普通表情”。

等待超时结果示例：

{
  "ok": false,
  "error": "media_timeout",
  "error_code": "media_timeout",
  "message": "本次等待超时，原下载继续；可用同一 message_id 重试",
  "message_id": "1234567890123456789",
  "media_type": "video",
  "duration_ms": 10001,
  "request_id": "media_download_001",
  "version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080"
}

HTTP 业务失败优先读取 error_code / error，中文原因读取 message。

9. 联系人与好友

POST /friends

用途：好友列表，分页。

成功响应：

以下为响应结构节选，数组中的 ... 表示省略内容，不能直接作为 JSON 解析：

{
  "ok": true,
  "keyword": "",
  "limit": 100,
  "offset": 0,
  "total": 256,
  "has_more": true,
  "items": [ ... ]
}

支付姓名字段只反映缓存，需用 /friend_pay_name 按需查询。字段详见 列表与群成员返回字段。翻页时不断增大 offset，直到 has_more 为 false。

每个好友条目恒含 add_time（Unix 秒）与 add_time_text（固定北京时间 UTC+8，YYYY-MM-DD HH:mm:ss）；未知时两者均为 null。无需新增请求参数，分页只为当前页读取添加时间。完整字段、空值规则和示例见联系人摘要对象。

POST /friends_all

用途：一次性返回全部好友（不分页）。

成功响应：

以下为响应结构节选，数组中的 ... 表示省略内容，不能直接作为 JSON 解析：

{
  "ok": true,
  "keyword": "",
  "total": 256,
  "friend_count": 256,
  "official_account_count": 12,
  "work_account_count": 0,
  "system_account_count": 4,
  "chatroom_count": 38,
  "stranger_count": 0,
  "cached_contact_count": 310,
  "items": [ ... ]
}

支付姓名字段只反映缓存，需用 /friend_pay_name 按需查询。字段说明见 列表与群成员返回字段。

每个好友条目同样恒含 add_time 与 add_time_text，格式、时区和空值规则与 /friends 一致，只为筛选后返回的好友读取时间。HTTP 与同名命令均支持，无需新增参数。详见联系人摘要对象。

items 仅包含按当前通讯录规则筛出的普通好友；公众号、企业微信、系统号、群聊及陌生人仅参与各自分类计数。total 是返回的好友条数，cached_contact_count 是原始缓存联系人条数。 ⚠️ 好友多时响应体会很大。日常使用建议用 friends 分页接口。

POST /friend_pay_name：阻塞查询好友或群成员支付姓名末字

单次调用等待微信回调后返回最终结果，不返回 querying 中间结果，无需再次查询任务状态。微信主线程保持异步运行。

这里的“实名相关查询”指微信支付脱敏姓名的末字查询，不提供完整实名，也不能用查询结果判断对方是否已实名认证。

• id 必填，使用好友列表或 room_members 返回的个人 account_id。好友直接查询；非好友自动查找双方均在其中的普通微信群，无需传 room_id。不支持自己、群 ID、公众号、企业微信或系统号。
• refresh 为布尔值，默认 false。当前好友或共同群场景有缓存时立即返回终态（包括已缓存的失败）；true 强制刷新或失败重试，并等待本次结果。同一目标、同一场景正在查询时合并等待；关系或群上下文变化后重新查询。
• 自动查找依赖本地群列表和成员资料；未找到可用共同群或资料未就绪时返回 failed 和中文原因。存在多个共同群时选择一个已核实的普通群，不轮询所有群发起支付查询。
• 原生查询串行执行，最多 32 个待处理请求；30 秒超时包含排队时间，接口等待保护上限约 31 秒。调用方超时建议至少 40 秒。
• 仅查询转账前信息，不提交金额或付款确认。结果只保留在当前账号会话内存中，账号或联系人服务会话变化后清空。

friends、friends_all 只附带好友场景缓存，本身不发起支付查询，群内非好友不会因此加入好友列表。列表仍可能显示 not_queried 或正在处理的 querying；单人查询接口和命令只返回上表中的终态。支付姓名字段不改变昵称、备注或 display_name，不提供完整姓名。

自动选择共同群的功能已由用户在微信 8.0.80 验证通过。

请求示例：

curl --max-time 40 --request POST 'http://192.0.2.10:19088/friend_pay_name' \
  --header 'Content-Type: application/json' \
  --data-raw '{"id":"wxid_example","refresh":false}'

本次请求等待后直接返回以下终态（姓名为虚构值）：

{
  "ok": true,
  "account_id": "wxid_example",
  "pay_name_last_char": "明",
  "pay_name_status": "ok"
}

查询结果和业务失败均为 HTTP 200。失败时 ok=false、pay_name_status=failed，原因在 error；例如超时为“支付姓名查询超时，可使用 refresh 重试”。授权失败仍使用通用 HTTP 403。客户端兼容 ok 的布尔值和数字 0/1。

POST /search_contact / POST /add_friend

用途：搜索普通个人联系人，并主动发起添加或验证申请。

主动添加使用两步调用：先搜索获得 contact_ref，再用该引用提交验证消息。支持普通个人联系人；公众号、群、OpenIM 和当前账号不提供可添加的引用。friends.keyword 仍只过滤本地好友列表。

搜索参数为 {"keyword":"示例微信号"}，keyword 必须是 1–256 个字符的字符串。支持微信实际允许搜索的微信号、手机号等，不保证任意原始 wxid 可搜索。搜索成功示例（依据用户提供的 HTTP 真机回包整理，身份和头像链接已替换）：

{
  "ok": true,
  "status": "found",
  "contacts": [{
    "contact_ref": "fc_example_ref",
    "username": "example_user",
    "nick_name": "示例昵称",
    "alias": "example_alias",
    "avatar_url": "https://example.com/avatar/132",
    "avatar_hd_url": "https://example.com/avatar/0",
    "sex": 1,
    "country": "",
    "province": "",
    "city": "",
    "signature": "",
    "supported": true,
    "is_friend": true,
    "source": "wechat_id"
  }],
  "expires_in": 300,
  "native_ret": 0,
  "stage": "search",
  "request_submitted": true,
  "event_id": 42,
  "request_cgi": 106,
  "message_type": 0,
  "transport_error_type": 0,
  "transport_error_code": 0
}

contacts[] 同时返回本次搜索取得的公开资料，无需先加好友，也不会额外发起资料查询：

以上字段在每个候选中均返回，是否有值取决于微信本次回包及对方公开资料；地区是个人资料填写值，不代表实时位置。它们不改变 supported 或 contact_ref 的规则。

country、province、city、signature 为空字符串时，表示本次搜索未取得对应资料，不影响 status:found；仅凭该结果无法区分对方未设置资料，还是微信搜索回包未提供。

is_friend 来自本地普通好友判断。为 true 时无需再发好友申请，正常调用 add_friend 会返回 already_friend。supported:true 表示候选类型符合当前添加流程，不代表对方是陌生人；已有好友也可能同时返回 supported:true 和 contact_ref。

source 为 wechat_id、phone 或 qq，由微信搜索匹配类型决定。username 是微信原生返回的标识，可能是加密标识，不能一律当成稳定 wxid。多候选由调用方选择；supported:false 的候选没有 contact_ref，不能提交添加。确认未找到时返回 ok:true,status:not_found,contacts:[]；传输错误、解析错误和业务失败返回 ok:false，不能当成“用户不存在”。

添加参数：

{"contact_ref":"fc_example_ref","say_content":"你好，我是某某"}

contact_ref 必填，只能使用本账号本次登录会话的搜索结果；say_content 可省略，默认为空字符串，不接受数字或 null。输入会去除首尾空白，并按微信原生长度规则校验；过长时返回 INVALID_SAY_CONTENT，不会悄悄截断发送。不能直接传 username、scene、opcode 或票据替代引用。好友添加遵循插件发送开关。

添加成功示例：

{
  "ok": true,
  "status": "request_sent",
  "username": "example_user",
  "is_friend": false,
  "contact_ref": "fc_example_ref",
  "native_ret": 0,
  "stage": "send_verification",
  "request_submitted": true,
  "event_id": 43,
  "request_cgi": 137
}

引用在插件内存保留 300 秒，最多 50 个；这个时间是本地缓存策略，不代表微信票据寿命。重启、退出登录或账号／上下文变化后必须重新搜索。相同引用及相同规范化消息的并发调用共享操作，完成后在引用有效期内复用结果；消息不同返回 CONTACT_REF_CONFLICT。同目标的另一引用正在添加时返回 ADD_IN_PROGRESS。超时后的相同引用仍返回原结果，不会自动重发。跨引用、跨重启和超过缓存期不承诺去重，后端也应避免重复下发。

两项操作均在当前请求内等待，插件操作期限为 30 秒，调用方建议至少等待 40 秒。native_ret 未取得微信业务结果时为 null；不能把 null 当 0。搜索成功或微信添加成功为 0，部分未找到搜索结果保留微信 -4。stage 为 preparing、search、precheck、add_contact 或 send_verification。request_submitted 只表示搜索／添加请求获原生受理（预检查不单独计入），不代表服务器已成功处理；request_cgi 为当前请求／最近回包的 CGI（搜索 106、添加 137、补取联系人 182、预检查 11568）；搜索的 event_id 为提交返回的 ID，添加为最近原生回调的 ID，尚无回包时为 null。它们仅用于诊断。

常见错误码：INVALID_KEYWORD、INVALID_PARAMETERS、INVALID_SAY_CONTENT、SEND_DISABLED、ACCOUNT_UNAVAILABLE、ACCOUNT_CHANGED、CONTACT_REF_EXPIRED、CONTACT_REF_CONFLICT、ADD_IN_PROGRESS、CANDIDATE_CACHE_FULL、TOO_MANY_REQUESTS、NATIVE_API_UNAVAILABLE、REQUEST_NOT_STARTED、PRECHECK_NOT_STARTED、PRECHECK_FAILED、WECHAT_INTERACTION_REQUIRED、WECHAT_REQUEST_FAILED、SEARCH_FAILED、WECHAT_TRANSPORT_FAILED、RESPONSE_INCOMPLETE、RESPONSE_INVALID、FRIEND_OPERATION_TIMEOUT。微信返回普通 -44 时最多一次进入原生发送验证消息入口；交互限制和预检查失败不会自动继续。

探针接受 {} 或 {"contact_ref":"fc_example_ref"}。它不发送搜索／好友申请，返回 search_runtime、add_runtime（ready 及各 selector 的 compatible/encoding）、logged_in、send_enabled、cached_candidates、pending_operations、contact_ref_valid、expires_in、has_antispam_ticket、reference_status 和 last_operation。last_operation 只保留最近一次操作的状态、阶段、返回码和受理信息；不包含账号、关键词、验证消息或原始票据。出现 NATIVE_API_UNAVAILABLE 时先调用探针定位不兼容项。

已取得用户提供的 HTTP 真机搜索成功回包，确认本次已有好友场景返回头像、大图头像、性别和 is_friend:true，地区及签名为空。用户现已确认搜索与添加好友功能在微信 8.0.80 验证通过；资料字段是否有值仍以微信本次回包为准，人工处理和超时按本节状态规则处理。

HTTP 的搜索和添加结果（包括参数错误、业务失败和超时）均保留完整 JSON，通常为 HTTP 200，必须读取 ok 和 status；授权失败仍为 HTTP 403。不要用 HTTP 200 判定添加成功。

-44 和发送状态的判断：stage:add_contact 表示直接添加阶段；request_submitted:true 只表示原生请求受理，不能据此认定验证申请已经发出。新增 verification_attempted 表示是否进入过发送验证消息入口；只有最终 status:request_sent 才表示微信确认验证申请发送成功。旧包在 add_contact 返回 needs_user_action,-44 时可能尚未进入验证消息阶段。

交互条件按现有原生链路判断：spam 提示标题、正文及 ctx 同时非空才要求人工确认；仅存在空的 verifyUserSpamInfo 对象或仅有 ctx，不会拦住普通 -44 的一次验证消息转换。微信原生可处理的 XML 提示、预检查失败及其他明确限制仍停止自动继续。

脱敏 failure_detail 保留最近一次错误分类，即使随后发送验证成功也可能保留此前的 verification_required：reason 为 spam_challenge、native_error_dialog、error_xml_unreadable、precheck_failed、verification_required 或 wechat_error；native_ret 为该次错误码；并提供 has_spam_info、has_spam_title、has_spam_detail、has_context、spam_challenge、has_error_xml、xml_show_type、xml_handled、xml_unreadable。不返回原始 ctx、XML、票据或提示文本。最终结果以外层 status/native_ret 为准，不能把历史 failure_detail 当成最终失败。

friend_add_probe 的 last_operation 同时返回 verification_attempted 和 failure_detail；群场景也可在 room_candidate.last_result 查看。该判定和诊断同时用于 add_friend 与 add_room_friend，不新增接口。

成功回包按实际请求区分：CGI137 的 opcode 1（直接添加）仍要求联系人标识；opcode 2（发送验证消息）允许回包缺少用户名，插件继续执行微信原生申请记录保存和成功回调，收到 contactSendRequestOk: 后才返回 request_sent。不会仅凭 native_ret:0 合成成功。旧包在 send_verification 阶段可能将这种正常回包误报为 RESPONSE_INCOMPLETE，并把已取得的 0 丢成 null；该旧结果不能证明服务器拒绝申请，应先核对状态，避免重复发送。

取得 CGI137 回包后，新增可选脱敏 response_detail：native_ret 为本次业务返回码，request_opcode 为实际请求操作码（无法读取时为 null），has_response_username 表示回包用户名是否非空。添加结果、探针 last_operation 及群候选 last_result 均可查看。若微信返回 0 后插件本地校验或后处理失败，外层仍保留 native_ret:0，须同时检查 ok/status/error_code；0 不代表插件已完成全部处理。没有本次回包时不提供该详情；探针未发生操作时为 {}。详情不包含用户名、消息正文或票据。

POST /add_room_friend

用途：通过共同群中的成员原始 wxid 添加好友或发送验证申请。

已知共同群和成员原始 wxid 时，使用独立的 add_room_friend。搜索添加仍为 search_contact → add_friend，不把 wxid 塞进搜索流程，也不要求调用方提供手机号、微信号、scene 或票据。

请求参数：

{"room_id":"123456789@chatroom","wxid":"wxid_example_member","say_content":"你好，我们在同一个群里"}

• room_id、wxid 必填，均为 1–256 字符的字符串，不含空白。只支持普通 @chatroom 群和个人联系人，暂不支持 OpenIM、公众号、群联系人或本人。
• wxid 使用 /room_members／room_members 成员结果的 account_id（原始成员标识），也可使用已取得的原始 wxid；不能传昵称或群昵称。room_id 必须是该成员所在的共同群。
• say_content 可省略，默认为空；仅接受字符串，会去除首尾空白，沿用 add_friend 的原生长度校验，过长拒绝发送。

插件先复用当前账号状态、群联系人和群成员列表入口，确认本人和目标都在该群；再按原生群资料链路请求 CGI182，携带目标和 fromChatRoom，按用户名匹配本次响应的群成员票据。只有取得有效联系人和票据后，才将群 ID、scene 14 和完整联系人交给 add_friend 共用的原生预检／添加执行器；普通 -44 最多一次转换为发送验证消息。调用方无需点击页面，也无需传递原始票据。列表缺失或成员关系未就绪会失败，不自动同步整个群。

HTTP 结果格式示例（身份字段为示意值）：

{
  "ok":true,
  "status":"request_sent",
  "source":"room",
  "room_id":"123456789@chatroom",
  "username":"wxid_example_member",
  "is_friend":false,
  "native_ret":0,
  "stage":"send_verification",
  "contact_fetch_submitted":true,
  "has_group_member_ticket":true,
  "request_submitted":true,
  "request_cgi":137,
  "event_id":42
}

status 沿用搜索添加的 already_friend、request_sent、added、pending_sync、needs_user_action、timeout、failed；request_sent 仅表示微信确认申请已发送。已有好友不取群票据、不发添加请求。native_ret:null 表示没有可用的微信业务结果。群路径不返回 contact_ref；前置校验失败可能只有公共错误字段。

stage 增加 room_contact。contact_fetch_submitted 仅表示群资料请求获原生受理，has_group_member_ticket 仅表示本次取得的票据非空，二者都不表示好友申请成功。request_submitted 仍仅表示共享添加链路获原生受理，不包含群资料请求和独立预检查。request_cgi／event_id 为当前或最近回包诊断，CGI182 为群资料、11568 为预检查、137 为添加。发生超时、回包不完整或后处理失败时，先核对好友状态，不自动重发。

同一登录会话、同一群、同一成员、相同规范化文字，在首次请求创建起 300 秒内共享在途操作或复用最终结果（包括失败和超时）；不同文字返回 ROOM_ADD_CONFLICT。最多保留 50 个群操作记录；共享在途上限 16 个。同一目标经另一群或搜索路径正在添加时返回 ADD_IN_PROGRESS。跨群、跨重启、切换账号或超过窗口不承诺去重，后端应记录操作结果，避免重复下发。整个流程单次等待，操作期限 30 秒，调用方超时建议至少 40 秒。

群相关错误包括 INVALID_PARAMETERS、ROOM_NOT_FOUND、ROOM_MEMBERS_UNAVAILABLE、NOT_IN_ROOM、CANNOT_ADD_SELF、TARGET_NOT_IN_ROOM、UNSUPPORTED_CONTACT、ROOM_CONTACT_FETCH_FAILED、ROOM_CONTACT_NOT_FOUND、GROUP_MEMBER_TICKET_MISSING、ROOM_ADD_CONFLICT；通用运行时、发送开关、切号、超时、预检及微信限制错误沿用 add_friend。GROUP_MEMBER_TICKET_MISSING 明确表示未发起好友申请，不会退回无来源 wxid 添加。

排障继续使用只读 friend_add_probe（HTTP POST /debug/friend_add_probe），可传：

{"room_id":"123456789@chatroom","wxid":"wxid_example_member"}

新增 room_runtime（群链路签名 ready/checks）、room_preflight（本地成员校验结果或明确错误）、room_candidate（cached/status/has_contact/has_group_member_ticket/last_result）；last_result 为该群成员缓存的完整业务结果，仅在调用过添加后存在。last_operation 增加 source:search|room，仍为脱敏诊断。探针不联网取资料、不发送申请，不返回原始票据。首次使用先检查 add_runtime.ready 和 room_runtime.ready，再检查 room_preflight.ok；添加失败后用同一参数查看阶段与原始返回码。

共同群添加好友已由用户在微信 8.0.80 验证通过；受限／人工处理和重复请求仍按本节约定处理。

HTTP 同样保留完整业务 JSON，业务失败通常为 HTTP 200，须检查 ok/status；授权失败仍为 HTTP 403。

POST /debug/friend_add_probe

用途：只读检查主动添加链路。请求体 {}、{"contact_ref":"fc_example_ref"} 或 {"room_id":"123456789@chatroom","wxid":"wxid_example_member"}；搜索及群场景输出字段和排障顺序见上节。

POST /accept_friend_request

用途：同意好友申请。

⚠️ 重名陷阱：这里的 request_id 是好友申请本身的业务标识，和长轮询/WebSocket 命令信封上的 request_id（用于结果关联）完全是两回事，只是名字撞了。在长轮询/WebSocket 里下发这条命令时，你会同时看到两个 request_id 出现在不同层级，别搞混——信封上那层是给你的请求编号，args 里这层是微信的业务申请 ID。

成功响应：

{
  "ok": true,
  "request_id": "好友申请业务ID",
  "encrypt_username": "...",
  "ticket": "...",
  "scene": 0,
  "say_content": ""
}

POST /delete_friend

用途：删除好友。

成功响应：{"ok": true, "id": "..."}

好友备注、星标和黑名单

三个入口均为 POST /set_friend_remark、POST /set_friend_star、POST /set_friend_blacklist，请求使用 application/json。

仅支持已登录账号的普通微信好友，id 必须是其真实 user_name / wxid。不支持自己、群、公众号、系统号、OpenIM 或已注销好友；已拉黑的好友仍可取消黑名单。沿用鉴权和发送开关，拒绝未知字段。

remark 必须显式传入字符串，使用微信 formatter 规范化，再按微信 charLength <= 32 校验，超限拒绝；这不是通用 Unicode 字符数限制。starred / blacklisted 必须显式传入 JSON 布尔值，0/1、"false"、null、缺省均拒绝。相同目标值返回 unchanged，不再次提交原生修改。

accepted 仅代表原生 BOOL 返回成功；sync_requested 仅说明已进入原生同步调用路径，不保证入队成功。local_verified 是本地联系人回读；server_confirmed 固定 false，当前实现不等待服务器 ACK。ok=true 不保证另一台设备已同步，unknown 不宜自动重提。

响应中的 remark / starred / blacklisted 是请求目标值（备注为规范化值），不是失败后的实际值；非法或缺失字段可能使用空串／false 占位，必须结合 ok / status。联系人摘要在 getter 可读时附带 is_starred / is_blacklisted，未知则省略。原有 remark / display_name 继续可读，清空备注后显示名回退昵称。

好友设置已由用户在微信 8.0.80 验证通过；Unicode 长度限制及断网／跨设备同步仍按本节约定和微信实际状态处理。

请求与响应示例：

POST /set_friend_star
Content-Type: application/json

{"id":"wxid_example","starred":true}

{
  "ok": true,
  "id": "wxid_example",
  "starred": true,
  "accepted": true,
  "sync_requested": true,
  "already_set": false,
  "local_verified": true,
  "server_confirmed": false,
  "status": "applied_locally",
  "error": "",
  "version": "8.0.80-2"
}

业务失败也返回 HTTP 200，并保留全部状态字段；鉴权失败仍为 HTTP 403。可导入本目录 微信机器人.apifox.json（资料未收录），其中已完整收录三个好友设置接口。

列表与群成员返回字段

联系人摘要对象（items[] / members[] 的元素）

friends、friends_all、groups_all、room_members 使用相同的基础联系人字段，并按场景增加好友或群成员字段。HTTP 好友数据位于 items[]，WebSocket／长轮询命令位于成功响应的 result.items[]；群成员数据位于对应的 members[]。

空值与省略规则：

• 普通字符串的 "" 表示未设置或本地没有取得有效值；不能据此推断对方资料一定为空。
• add_time 与 add_time_text 总是成对返回：有值时分别为秒级整数和 UTC+8 文本，未知时均为 null。不以 0、空串或 1970 年日期代替未知，也不使用本地添加流程时间兜底。
• is_starred、is_blacklisted 及群成员角色字段可能整个省略。字段缺失表示未知，不能按 false 处理。

添加时间来自微信当前保存的记录，与微信资料页使用的字段一致；不承诺删除后重加时仍是终身首次添加时间。文本不随手机时区、语言或日历设置变化。两个好友查询及同名命令均无需新增请求参数。

支付姓名状态：

friends、friends_all 本身不发起支付姓名查询，需要时调用 friend_pay_name；其结果不会改变昵称、备注或 display_name。

完整好友条目示例（虚构数据，共 17 个字段）：

{
  "account_id": "wxid_example",
  "display_name": "示例备注",
  "remark": "示例备注",
  "alias": "wechat_example",
  "nick_name": "示例好友",
  "avatar_url": "",
  "sex": 0,
  "province": "",
  "city": "",
  "signature": "",
  "contact_found": true,
  "is_starred": false,
  "is_blacklisted": false,
  "add_time": 1704067200,
  "add_time_text": "2024-01-01 08:00:00",
  "pay_name_last_char": "",
  "pay_name_status": "not_queried"
}

时间未知时的字段节选：

{"add_time": null, "add_time_text": null}

friends 的返回

以下为响应结构节选，数组中的 ... 表示省略内容，不能直接作为 JSON 解析：

{
  "ok": true,
  "keyword": "",
  "limit": 100,
  "offset": 0,
  "total": 256,
  "has_more": true,
  "items": [ ... ]
}

翻页方法：不断增大 offset（offset += limit），直到 has_more 为 false。

friends_all 的返回

以下为响应结构节选，数组中的 ... 表示省略内容，不能直接作为 JSON 解析：

{
  "ok": true,
  "keyword": "",
  "total": 256,
  "friend_count": 256,
  "official_account_count": 12,
  "work_account_count": 0,
  "system_account_count": 4,
  "chatroom_count": 38,
  "stranger_count": 0,
  "cached_contact_count": 310,
  "items": [ ... ]
}

friends_all.items 只返回筛选后的普通好友，支付姓名字段只附带已有缓存。各类联系人计数用于说明本地通讯录构成，不表示这些联系人也会混入 items；好友数量可读取 friend_count，原始缓存联系人数量读取 cached_contact_count。

groups_all 的返回

以下为响应结构节选，数组中的 ... 表示省略内容，不能直接作为 JSON 解析：

{
  "ok": true,
  "keyword": "",
  "total": 38,
  "items": [ ... ]
}

groups_all 没有 has_more / limit / offset，它一次返回全部。

room_members 的返回

以下为响应结构节选，数组中的 ... 表示省略内容，不能直接作为 JSON 解析：

{
  "ok": true,
  "room_id": "50136399923@chatroom",
  "room_name": "项目群",
  "room_remark": "",
  "current_user": "wxid_self",
  "owner_user_name": "wxid_owner",
  "admin_count": 2,
  "admin_user_names": ["wxid_owner", "wxid_admin"],
  "admin_members": [ ... ],
  "self_is_owner": false,
  "self_is_admin": false,
  "member_count": 24,
  "members": [ ... ]
}

失败时的响应：{"ok": false, "error": "...", "room_id": "..."}——失败也会带上 room_id，便于定位是哪个群出错。

查询接口失败时的统一行为

friends、friends_all、groups_all、room_members 在业务失败时返回：

{ "ok": false, "error": "<原因>" }

其中 room_members 会额外带上 room_id。HTTP 状态码此时仍可能是 200——这正是 3.2 节 强调"必须同时看状态码和 ok"的原因。

10. 群聊管理

POST /groups_all

用途：一次性返回全部群聊。

成功响应：

以下为响应结构节选，数组中的 ... 表示省略内容，不能直接作为 JSON 解析：

{
  "ok": true,
  "keyword": "",
  "total": 38,
  "items": [ ... ]
}

无分页字段，一次返回全部。

POST /room_members（别名 /debug/room_members）

用途：查询某个群的成员列表。

成功响应：{"ok": true, "room_id": "...", "members": [...], "admin_members": [...]} 等，详见 列表与群成员返回字段。

两个路径的区别：用 /room_members 时返回的是精简后的对外字段；用 /debug/room_members 时响应里会额外带上 path 字段和更多内部调试信息。正式对接请用 /room_members。

POST /get_chatroom_qrcode：阻塞获取指定群二维码

curl --max-time 40 --request POST 'http://192.0.2.10:19088/get_chatroom_qrcode' \
  --header 'Content-Type: application/json' \
  --data-raw '{"room_id":"example@chatroom"}'

每次调用按微信原生协议创建独立请求，通过当前登录会话的 EventService 发起取码，在同一次调用中等待微信本次响应；不返回查询中状态，不需要任务 ID。同群并发共用正在处理的请求，完成后再次调用会重新取码。最多 32 个不同群的待处理请求，约 30 秒超时，接口等待保护上限约 31 秒；调用方超时建议至少 40 秒。

唯一参数 room_id 必须是实际群 ID 字符串，例如 example@chatroom，不能传群名。当前账号须能找到该群联系人，最终权限以微信响应为准。

status=ok 表示本次业务响应成功且取得二维码内容，不能保证扫码立即入群。restricted 对应微信非零二维码状态，业务 ok=false，error 提供中文分类说明；具体原因可能在可读文本字段或返回图片中；即使有图或 URL 也不作为普通成功处理。没有恢复具体状态枚举，不写死“1=超员、2=开启验证”。网络失败、微信 ret != 0、响应不完整和超时均返回失败信息，不返回旧缓存的码。

人数阈值由微信配置控制（静态样本默认 200，客户端判断人数达到阈值）；开启管理员进群验证也不一定禁止取码，新管理方式可以扫码申请审批。因此不按人数或验证开关在本地直接拒绝，以本次微信原码与文案为准。

普通群可能只有 URL，没有服务器图片；调用方可用 qr_code_url 自行生成二维码，无需手机下载再上传。接口不会读取微信磁盘缓存，也不返回本地文件路径。微信保存的完整分享卡片还会组合群头像、群名和有效期提示，本接口不拼装该卡片。

OpenIM 按微信原生群类型判断分流至 CGI890；该分支可能只有图片，没有 URL，也没有二维码状态，此时 qrcode_status、restricted 为 null。仍校验本次原始业务响应，不能依赖原生固定为 0 的完成通知。

常见 error_code：INVALID_ROOM_ID、ACCOUNT_UNAVAILABLE、ACCOUNT_CHANGED、ROOM_NOT_FOUND、NATIVE_API_UNAVAILABLE、TOO_MANY_REQUESTS、REQUEST_NOT_STARTED、NATIVE_REQUEST_FAILED、RESPONSE_INVALID、WECHAT_REQUEST_FAILED、RESPONSE_INCOMPLETE、QRCODE_RESTRICTED、QRCODE_TIMEOUT。REQUEST_NOT_STARTED 仅在原生事件服务返回事件 ID 为 0 时使用，不能据此推断群人数或验证限制。request_submitted=true 仅表示微信事件服务已受理，不代表服务器成功；若之后返回 QRCODE_TIMEOUT，表示尚未取得本次最终响应。

中文原因取自微信可读字段：footer_wording 和 wechat_error_message。受限时优先使用非空 footer_wording 作为 error；没有该文案时返回通用中文“微信返回二维码受限状态”，并原样保留 wechat_error_message。微信可能将具体原因直接写在返回图片里，两个文本字段均为空；本接口不做图片文字识别，也不根据 qrcode_status=1 等原始值硬编码具体原因。

用户提供的普通群真机响应已确认：请求受理并收到 wechat_ret=0，qrcode_status=1，返回 PNG，qr_code_url=null，footer_wording、wechat_error_message 均为空；人工查看图片文字为“该群已开启进群验证，只可通过邀请进群”。这只说明该次图片的含义，不是所有状态值 1 的固定映射。

has_qrcode、has_image、restricted、request_submitted 可能序列化为布尔值或数字 0/1，restricted 还可能为 null。has_image=1、has_qrcode=1 只表示有返回内容，不保证图片是可用的入群码。业务是否成功应先检查 ok 和 status。

群二维码功能已由用户在微信 8.0.80 验证通过；取码成功不保证立即入群，实际扫码仍受群设置及微信返回限制。上述受限图片记录不构成固定状态码映射，也不能据此扩大 OpenIM 支持范围。

受限响应示例（节选；群 ID 和事件 ID 为占位值，实际 image_base64 是 PNG Base64 字符串，本文省略图片内容）：

{
  "ok": false,
  "room_id": "example@chatroom",
  "status": "restricted",
  "qr_code_url": null,
  "has_qrcode": 1,
  "has_image": 1,
  "image_mime_type": "image/png",
  "qrcode_status": 1,
  "restricted": 1,
  "footer_wording": "",
  "wechat_ret": 0,
  "wechat_error_message": "",
  "message_type": 0,
  "transport_error_type": 0,
  "transport_error_code": 0,
  "request_submitted": 1,
  "request_cgi": 168,
  "event_id": 42,
  "error_code": "QRCODE_RESTRICTED",
  "error": "微信返回二维码受限状态"
}

成功示例（链接为占位值）：

{
  "ok": true,
  "room_id": "example@chatroom",
  "status": "ok",
  "qr_code_url": "https://weixin.qq.com/g/example",
  "has_qrcode": true,
  "has_image": false,
  "image_base64": null,
  "image_mime_type": null,
  "qrcode_status": 0,
  "restricted": false,
  "footer_wording": "",
  "wechat_ret": 0,
  "wechat_error_message": "",
  "message_type": 0,
  "transport_error_type": 0,
  "transport_error_code": 0,
  "request_submitted": true,
  "request_cgi": 168,
  "event_id": 42
}

查询结果、业务失败和受限结果均为 HTTP 200，须检查 ok、status；失败说明在顶层 error，授权失败仍为 HTTP 403。HTTP 等待只占用当前连接，不阻塞微信主线程或其他业务接口。

创建群聊、直接加人和发送入群邀请

入口为 POST /create_group、POST /add_group_member、POST /invite_group_member；邀请兼容 POST /group/invite_member。沿用本篇本地HTTP地址和JSON请求体设置；仅检查插件自身授权状态，不校验请求Token，也不要求调用方添加鉴权Token。

三项操作分别表示创建普通微信群、尝试直接加入群成员、发送需要对方接受的入群邀请。插件不按“40 人”硬切换，也不把添加失败自动转成发送邀请；是否可直接加入取决于微信服务端和群设置。所有结果均须查看业务状态，原生方法返回成功不等于成员已经入群。

验证范围：已有用户确认的 HTTP 真机记录，覆盖两位好友建群、直接添加已在群成员、移出后重新添加、邀请已在群成员和移出后发送邀请。邀请成功只确认发送。用户现已确认建群、添加与邀请成员功能在微信 8.0.80 验证通过。是否可直接加人仍由微信与群设置决定，审批、部分成功、超时及账号切换按本节状态处理。request_submitted 为 boolean。

使用范围与完整参数

必须已登录并开启插件写入／发送开关。待操作对象必须是当前账号的普通微信好友，传真实内部 ID；不支持昵称、完整微信号 alias、企业微信用户或群 ID 充当成员。添加和邀请只支持普通 @chatroom 群，并须能从当前群成员快照确认本人在群；无须由插件预设“只有群主能加人”，实际权限和人数限制由微信返回。

request_id 去除首尾空白后须为 1–128 个字符；成员和群 ID 也去除首尾空白，内部不能含空白。成员去重后按 ID 排序。创建时自动排除本人；至少两位其他好友是本接口首版支持范围，不是对微信服务端所有建群方式最低人数的断言。创建不接受 topic／群名，群创建后如需命名，使用已有 set_group_name，其结果独立判断。

添加／邀请先排除本机快照中已在群的成员，只向微信提交剩余普通好友；已在群者放入 already_in_room_member_ids。全部已在群时返回 already_in_room，不提交新请求；仅本机快照确认，server_confirmed:false。若任一待提交成员不是普通好友，整次请求在提交前失败，不偷偷跳过该人。

邀请保留单值别名 user_name／wxid、数组别名 user_names／wxids；可以和 member_id／member_ids 同时提供，合并、校验、去重排序。群 ID 可用 chatroom_id／group_id／to_user_name，同时传多个群字段时规范化后须一致。创建和添加不支持这些旧别名，也不允许同时传多个成员字段。未列出的参数直接拒绝，不静默忽略；null 不能代替字符串或数组。

返回字段与成功判断

下表是完整业务字段；ok／error 所在位置见本节通道说明。初始失败可能尚未解析到成员或群 ID，因此对应字段为空。message、error、error_code 和 replayed 为按情况出现的字段，其余业务字段默认存在。

逐成员 status 可能为 added、already_in_room、requires_invitation、requires_verification、approval_pending、failed、unknown。原生 native_status=0 不能独立判断加入成功，必须与总返回码共同解释：例如添加回包 wechat_ret=-2012 表示需要邀请的分支，-2028 可表示等待群主／管理员确认。wechat_ret=-2012 下 native_status=3 表示拒绝加入，逐成员为failed；状态10含义尚不能确认，保留unknown。创建成功但成员信息不完整时仍返回 created，相关成员为unknown、all_members_added:false。正常邀请回包只确认批次发送，member_results:[]；全部目标已在群而未发送时可返回逐人的 already_in_room。

错误、等待、去重与重试

服务等待真实回包约30秒，外层等待保护约31秒；客户端建议至少40秒，iOS挂起、通信排队或断线可能更久，不能把连接超时直接当业务失败。该能力不新增完成事件或单独查询接口；迟到回包会更新当前进程内记录，使用原接口／命令、原ID和相同规范化参数读取即可。

三种接入方式共用当前账号登录上下文内的操作记录。登记后相同ID、相同操作／群／去重排序成员／reason只读取记录，不再次提交；在途返回processing，结束后返回当前结果并带 replayed:true。同ID不同参数返回冲突。参数或环境校验阶段尚未登记的失败不等于已建立去重记录。新业务必须用新ID；同ID只能查询／重放原业务，不用于强制重新执行。

最多保留512项已登记操作，达到上限拒绝新操作，不按最近条目淘汰。添加操作只要仍有待添加成员结果为 unknown，即使回包字段齐全或顶层为 partial，也继续占用同群操作槽位，并等待迟到回包；已知结果与未知结果混合时逐人处理，不能据此重发整批。唯一可继续的同群操作是显式邀请：新邀请的全部目标必须属于该未完成添加记录的 invite_required_member_ids 已确认名单，并使用新的业务ID；不在名单内的邀请和其他添加仍返回OPERATION_BUSY，原添加记录继续等待。只有成员结果完整且均已明确，才解除该添加占用。邀请本身结果未知也保留同群占用，上述例外不会绕过其他未完成的邀请。建群尚未取得有效新群ID时的未知结果会占用当前账号建群槽位；已取得有效新群ID则返回 created 并解除建群占用，成员部分未知也不能重复创建原业务群。记录仅在当前微信进程和登录上下文内有效，进程重启、重新登录或服务上下文变化（含群服务重新初始化）后不保证去重；不要通过重启或换ID绕过未知结果。后端应保存业务ID及收到的结果，跨重启先核实群状态，再由业务决定下一步。

本模式封装与调用示例

参数直接放JSON请求体。新建群和添加必须提供 request_id；旧邀请接口缺省时自动生成并在结果中返回，兼容调用虽可继续使用，但无法用省略ID的重复请求去重，建议调用方主动提供并保存ID。

三个业务入口通过通用解析和鉴权后，均返回HTTP200并保留完整业务结果；ok/status 位于响应顶层，统一出口可能附带 version。HTTP200不表示已建群／已入群。非法JSON或非对象JSON会被解析层视为空字典，并返回HTTP200参数失败；本接口不另报JSON语法400。未授权仍为403，路径／方法不匹配为404，请求接收超时或过大分别为408／413。写入开关关闭的新请求为HTTP200的WRITE_DISABLED。旧邀请接口的业务失败由原来的HTTP400改为HTTP200完整结果，旧调用方应改为检查顶层 ok、status、error_code。

POST /create_group：

{
  "request_id": "req-create-001",
  "member_ids": [
    "wxid_member_a",
    "wxid_member_b"
  ]
}

POST /add_group_member：

{
  "request_id": "req-add-001",
  "room_id": "123456789@chatroom",
  "member_id": "wxid_member_a",
  "reason": ""
}

POST /invite_group_member：

{
  "request_id": "req-invite-001",
  "room_id": "123456789@chatroom",
  "member_ids": [
    "wxid_member_a"
  ]
}

建群成功示例（字段格式示例，不是真机记录）：

{
  "ok": true,
  "status": "created",
  "mode": "create",
  "request_id": "req-create-001",
  "room_id": "123456789@chatroom",
  "member_ids": [
    "wxid_member_a",
    "wxid_member_b"
  ],
  "member_count": 2,
  "submitted_member_ids": [
    "wxid_member_a",
    "wxid_member_b"
  ],
  "already_in_room_member_ids": [],
  "accepted": true,
  "request_submitted": true,
  "response_received": true,
  "server_confirmed": true,
  "request_cgi": 119,
  "event_id": 42,
  "wechat_ret": 0,
  "wechat_error_message": "",
  "message_type": 0,
  "transport_error_type": 0,
  "transport_error_code": 0,
  "created": true,
  "all_members_added": true,
  "member_results": [
    {
      "member_id": "wxid_member_a",
      "status": "added",
      "native_status": 0
    },
    {
      "member_id": "wxid_member_b",
      "status": "added",
      "native_status": 0
    }
  ],
  "invite_required_member_ids": []
}

直接添加需要改走邀请示例（字段格式示例，不是真机记录）：

{
  "ok": false,
  "status": "requires_invitation",
  "mode": "add",
  "request_id": "req-add-001",
  "room_id": "123456789@chatroom",
  "member_ids": [
    "wxid_member_a"
  ],
  "member_count": 1,
  "submitted_member_ids": [
    "wxid_member_a"
  ],
  "already_in_room_member_ids": [],
  "accepted": true,
  "request_submitted": true,
  "response_received": true,
  "server_confirmed": false,
  "request_cgi": 120,
  "event_id": 42,
  "wechat_ret": -2012,
  "wechat_error_message": "",
  "message_type": 0,
  "transport_error_type": 0,
  "transport_error_code": 0,
  "created": false,
  "all_members_added": false,
  "member_results": [
    {
      "member_id": "wxid_member_a",
      "status": "requires_invitation",
      "native_status": 0
    }
  ],
  "invite_required_member_ids": [
    "wxid_member_a"
  ],
  "error_code": "MEMBERS_NOT_ALL_ADDED",
  "error": "成员未全部确认加入，请查看 member_results；需要邀请时显式调用 invite_group_member"
}

邀请批次已发送示例（字段格式示例，不是真机记录）：

{
  "ok": true,
  "status": "invitation_sent",
  "mode": "invite",
  "request_id": "req-invite-001",
  "room_id": "123456789@chatroom",
  "member_ids": [
    "wxid_member_a"
  ],
  "member_count": 1,
  "submitted_member_ids": [
    "wxid_member_a"
  ],
  "already_in_room_member_ids": [],
  "accepted": true,
  "request_submitted": true,
  "response_received": true,
  "server_confirmed": true,
  "request_cgi": 610,
  "event_id": 42,
  "wechat_ret": 0,
  "wechat_error_message": "",
  "message_type": 0,
  "transport_error_type": 0,
  "transport_error_code": 0,
  "created": false,
  "all_members_added": false,
  "member_results": [],
  "invite_required_member_ids": []
}

已提交但超时未知示例（字段格式示例，不是真机记录）：

{
  "ok": false,
  "status": "unknown",
  "mode": "add",
  "request_id": "req-add-001",
  "room_id": "123456789@chatroom",
  "member_ids": [
    "wxid_member_a"
  ],
  "member_count": 1,
  "submitted_member_ids": [
    "wxid_member_a"
  ],
  "already_in_room_member_ids": [],
  "accepted": true,
  "request_submitted": true,
  "response_received": false,
  "server_confirmed": false,
  "request_cgi": 120,
  "event_id": 42,
  "wechat_ret": null,
  "wechat_error_message": "",
  "message_type": null,
  "transport_error_type": null,
  "transport_error_code": null,
  "created": false,
  "all_members_added": false,
  "member_results": [],
  "invite_required_member_ids": [],
  "error_code": "OPERATION_TIMEOUT",
  "error": "等待微信回包超时，可能已生效；请用相同 request_id 查询，勿换 ID 重发"
}

POST /kick_group_member（别名 /kick_group_members）

用途：踢出群成员。

member_id 与 member_ids 可同时传，自动合并去重。至少要有一个被踢对象，否则业务会失败。

成功响应：{"ok": true, "room_id": "...", "member_ids": [...], "member_count": 2}

失败响应：400，响应体带 room_id 和 member_ids 便于你定位。

POST /set_group_self_nickname（别名：POST /rename_group、POST /set_group_nickname）

用途：修改当前账号在该群里的群昵称（等同微信里「我在本群的昵称」）。修改整个群聊的名称请使用下方的 POST /set_group_name。

成功响应：{"ok": true, "room_id": "...", "new_name": "...", "clears_group_nickname": false}

清空时 new_name 回显为 ""、clears_group_nickname 为 true：

curl -X POST 'http://127.0.0.1:19088/set_group_self_nickname' \
  -H 'Content-Type: application/json' \
  -d '{"room_id":"123456@chatroom","new_name":""}'

失败响应：400 + new_name is required (pass an empty string to clear your group nickname)、room contact not found 等。

POST /set_group_name

用途：修改整个群聊的名称。此接口与 rename_group / set_group_self_nickname 语义不同。

受插件发送开关控制。调用示例（将 <手机IP> 和群 ID 换成实际值）：

curl -X POST 'http://<手机IP>:19088/set_group_name' \
  -H 'Content-Type: application/json' \
  -d '{"room_id":"123456@chatroom","new_name":"新的群聊名称"}'

成功响应示例：

{
  "ok": true,
  "room_id": "123456@chatroom",
  "new_name": "新的群聊名称",
  "accepted": true,
  "local_verified": true,
  "already_named": false,
  "local_name": "新的群聊名称"
}

accepted 只表示微信底层接受调用；local_verified 表示本机群联系人的 nick_name 已读回目标值。底层接受后，本地读回可能尚未完成，因此 ok: true 时 local_verified 也可能是 false。如果本地群名原本就等于目标值，不会重复提交，返回 ok: true、already_named: true、accepted: false、local_verified: true。以上结果都不代表其他成员端已经同步。

失败响应：HTTP 400、ok: false 和中文 error；包括群 ID 缺失或格式不对、群名为空、服务或 selector 不可用、签名不受支持、底层拒绝等。

只读探针：POST /debug/set_group_name_probe，请求体只需 {"room_id":"123456@chatroom"}。检查 group_manager_found、selector_available、signature_supported、set_group_name_ready 等字段，不执行修改。探针响应的 HTTP 状态可能是 200，仍应检查响应体里的 ok 和 set_group_name_ready。

POST /get_group_notice

用途：读取微信当前保存在本机的群公告。请求体只需 {"room_id":"123456@chatroom"}，room_id 必须是以 @chatroom 结尾的字符串。接口只读本地缓存，不发起下载，也不修改公告。

curl -X POST 'http://<手机IP>:19088/get_group_notice' \
  -H 'Content-Type: application/json' \
  -d '{"room_id":"123456@chatroom"}'

读到完整公告时的响应示例：

{
  "ok": true,
  "room_id": "123456@chatroom",
  "cached_notice_found": true,
  "summary": "微信提供的文本摘要",
  "html": "<p>公告正文</p>",
  "html_cached": true
}

summary 来自微信公告项的文本摘要，可能省略格式或内容，不能当作完整正文；html 是本地 .htm 文件的原始 UTF-8 内容，保留格式。html_cached: true 表示已成功读取该文件。正文文件未缓存或无法读取时，html 为 null、html_cached 为 false，此时仍可能有 summary。

本地未读到公告项时，接口返回 ok: true、cached_notice_found: false、summary: null、html: null、html_cached: false。这不等于群里没有公告；缓存也可能不是最新内容。参数或运行时方法不受支持时返回 HTTP 400、ok: false 和 error。

邀请入群：查询、静默接受与探针

用户已确认微信 8.0.80 的邀请查询与接受入群功能验证通过。收到普通私聊邀请链接卡片后，插件从原消息取得 URL、发送方和消息上下文，经微信原生 A8Key 鉴权调用官方邀请详情/接受协议。全程不创建网页、不点击、不执行网页脚本。已有 HTTP 查询及用户提供的接受成功回包，验证范围见本节末尾。查询时 roomInfo.roomName 可缺省，目标群 ID 可在接受成功后才取得。

业务请求统一为：

{"message_id":"123456789012345678"}

message_id 取收到卡片事件的 body.message_id，必须是正整数十进制字符串（最多 20 位且不超过 uint64，无前导零）。不接受 JSON 数字，以免大整数丢精度。不需要 invite_url、chat_id、room_id、账号凭据或 ticket。账号选择沿用既有设备/账号通道；本地复核消息属于当前登录账号。回调里的 chat_id 是来源会话，私聊的 room_id 为空，不是邀请目标群。群名等来自服务器详情；目标群 ID 在查询时可为空，接受成功后从提交回包取得。

仅处理当前账号收到的普通私聊 49/5 卡片及 support.weixin.qq.com/cgi-bin/mmsupport-bin/addchatroombyinvite 邀请。 鉴权后的地址允许微信内置的 7 个 support 域名（support/szsupport/mlsupport/hksupport.weixin.qq.com、support/sgsupport/ussupport.wechat.com），仍严格检查 HTTPS、原路径、原 ticket、端口和凭据；详情/接受请求及 Origin 使用本次鉴权域名，不跟随重定向。原消息必须仍在近期缓存（当前最多 200 条），否则返回 MESSAGE_CONTEXT_NOT_FOUND，需重新取得一条新邀请。切换账号或登录上下文时停止操作。微信被系统挂起或进程结束时不能保证后台执行；“静默”指进程有运行时间时无界面地执行协议。

HTTP 需要有效插件授权；接受接口在真正提交前复核现有 sendEnabled（当前跟随插件总开关）。查询和探针沿用 HTTP 读取接口约定，不单独受发送判断约束。命令通道三项均沿用插件启用与授权检查。

结果判定

ticket_used=true 单独不能证明当前还在群。openurl、额外交互或不支持的 A8Key action 会明确受限/失败。不会转到页面继续操作。查询阶段允许服务器暂不返回群 ID，仍可返回群名、人数和是否可接受；接受成功必须取得有效群 ID。后续成员核实按同一 ticket 的本次服务器详情判断，若返回群 ID 则必须匹配。旧本地群联系人或成员缓存不作为本次在群证据。

查询响应示例（依据已有真机查询结果，消息 ID 与群名已替换；查询时群 ID 缺省）：

{"ok":true,"status":"ready","message_id":"123456789012345678","room_id":"","room_name":"示例群","member_count":198,"can_accept":true,"in_chatroom":false,"ticket_used":false,"restriction_code":"","warning":"为维护微信平台绿色网络环境，请勿在群内传播违法违规内容。","request_submitted":false,"membership_verified":false,"wechat_ret":0,"a8key_action":6,"wechat_err_code":0,"wechat_error_type":0,"http_status":200,"stage":"info","error_code":"","error":"","elapsed_ms":1417,"version":"8.0.80-2"}

接受响应主要看 status、request_submitted、membership_verified。request_submitted=true 只表示本次或此前同票据的接受请求已开始，不能证明服务器已接收；accepted 不等于已确认在群。接受操作的 can_accept 固定为 false，避免把已处理结果再次当作可提交邀请。

接受并核实入群成功示例（依据用户提供的真机回包，消息 ID、群名与群 ID 已替换；未独立检查手机界面）：

{
  "ok": true,
  "status": "joined",
  "message_id": "123456789012345678",
  "room_id": "123456789@chatroom",
  "room_name": "示例群",
  "member_count": 198,
  "can_accept": false,
  "in_chatroom": true,
  "ticket_used": false,
  "restriction_code": "",
  "warning": "为维护微信平台绿色网络环境，请勿在群内传播违法违规内容。",
  "request_submitted": true,
  "membership_verified": true,
  "wechat_ret": 0,
  "a8key_action": 6,
  "wechat_err_code": 0,
  "wechat_error_type": 0,
  "http_status": 201,
  "stage": "verify",
  "error_code": "",
  "error": "",
  "elapsed_ms": 3876,
  "version": "8.0.80-2",
  "verification_http_status": 200,
  "verification_err_code": 0,
  "verification_error_type": 0
}

字段来源与快照语义

接受返回整合了接受前详情、接受 POST 和接受后核实三次请求：

• room_name、member_count、ticket_used、warning 保留接受前详情快照；核实阶段不刷新这些字段。因此成功回包中 ticket_used=false、member_count=198 仍可与 status=joined 同时出现，不能据此判断票据仍可用或入群后人数仍为 198。
• room_id 在接受成功时从 POST 回包取得；membership_verified 与 in_chatroom=true 表示后续同一票据的服务器详情已确认在群。verification_* 只记录这次核实请求，不覆盖接受 POST 的状态码。
• warning 来自微信详情的 data.antispamwarning，为空时取 data.securitytips，再隐藏其中的凭据和链接。当前返回没有记录具体采用了哪一个源字段。这条“为维护微信平台绿色网络环境，请勿在群内传播违法违规内容。”是微信返回的普通提醒；仅有该文案不表示违规、受限或失败，限制看 status/restriction_code。

后端判断已确认在群，使用 ok=true、status 为 joined 或 already_joined，并且 membership_verified=true。request_submitted=true 仅说明开始过提交；accepted 表示微信已确认接受但成员核实尚未成功，应查询详情确认，不能自动重提。接受操作结束时 can_accept 固定为 false，表示该操作结果不再作为可接受邀请，不能把它解释成本次接受被拒绝。

实测 wechat_ret=0 表示 A8Key 鉴权成功，a8key_action=6 是原生 URL 处理分支编号。接受回包的 http_status=201 是微信接受 POST 的成功 HTTP 状态；再结合 wechat_err_code=0/wechat_error_type=0 和有效群 ID 判断接受成功。verification_http_status=200 与核实双零业务码来自随后的详情 GET，成员是否核实仍看 membership_verified。手机本地 HTTP 接口的响应状态仍是 200；不能把 JSON 内的 http_status 当作本地接口状态。

错误码包括 INVALID_ARGUMENT、INVALID_CALL_THREAD、NOT_LOGGED_IN、ACCOUNT_CHANGED、MESSAGE_CONTEXT_NOT_FOUND、MESSAGE_CONTEXT_MISMATCH、NATIVE_UNAVAILABLE、NATIVE_EXCEPTION、A8KEY_FAILED、A8KEY_TIMEOUT、RESPONSE_INVALID、INVITATION_TIMEOUT、INVITATION_EXPIRED、INVITATION_INVALID、WECHAT_REJECTED、SEND_DISABLED、BUSY、INVITATION_LIMIT、RESULT_UNKNOWN。限制码为 INVITATION_USED、INVITATION_RESTRICTED、UNSUPPORTED_INVITATION_FLOW，接受受限时也作为错误码。

去重、超时与重试

同账号登录上下文、同票据、同操作及探针阶段的并发请求合并等待；创建操作上限 16。接受提交前登记内存记录，同一票据以后调用接受会重新查询、不重复 POST；明确拒绝可移除提交记录。提交记录当前最多 64，满时拒绝新提交，避免淘汰未知记录导致误重试。账号/会话变化或进程重启后记录不保留，不保证跨重启幂等；后端也应按账号和原消息记录已提交/未知结果，重启后先查询，不自动重发接受。

鉴权等待约 18 秒，单次 HTTP 最多 12 秒，总操作约 55 秒。调用方等待建议 75 秒。HTTP 业务结果（含失败）均返回 200 并保留完整业务 JSON；授权拦截等前置层仍沿用原错误状态，不能仅判断 HTTP 状态。不要因 30 秒内没有业务结果就自动重新提交接受操作。

只读 HTTP 探针与真机测试

统一 POST /debug/group_invitation_probe：

{"message_id":"123456789012345678","stage":"context"}

1. context：检查原消息、当前账号、原生类和 ABI，不按固定微信版本号拦截，不调用 A8Key 或业务 HTTP。
2. auth：在前述基础上调用原生鉴权并核对 fullUrl、ticket、exportkey，不请求邀请详情。
3. info（默认）：完成鉴权并 GET 详情，不 POST 接受。三阶段 request_submitted 均为 false。

诊断含 native_ready、native_signatures、wechat_version、message_context_found、message_type、app_msg_type、a8key_scene、a8key_opcode、callback_received；收到回调后可有 event_id、cgi、a8key_message、transport_error_type/code、exportkey_present、full_url_allowed、full_url_same_host/path/ticket、full_url_https、full_url_has_fragment、full_url_host（仅 hostname）、full_url_host_allowed、full_url_port（未显式设置时 null）、full_url_has_credentials、a8key_header_names；HTTP 后可有 business_http_host（应与鉴权 hostname 相同）、http_response_mime、last_response_bytes、network_error_code、http_json_object、data_object、room_info_object 及固定业务字段名称列表 invitation_fields。业务解析后还有 response_field_types（固定字段的 JSON 类型，含 missing/null）、response_string_lengths（群信息字符串长度）和 response_validation（信封、业务层、布尔字段、roomInfo 和群 ID 校验结果），不返回这些字段的原始字符串值。full_url_same_host 仅表示与原入口主域名相同；官方地区域名可使其为 false，应结合 full_url_host_allowed/full_url_allowed 判断。字段按到达阶段提供。探针不返回原始链接、ticket、exportkey、Cookie 或鉴权 header 值，也不提供任意 URL、原生方法执行能力。

可运行项目自带只读验证脚本（真实 ID 由调用方在命令行传入，不写入文件）：

python tests/group_invitation_smoke.py --base-url http://<手机IP>:19088 --message-id <刚收到的消息ID>

排障按 context → auth → info 检查；确认 status=ready 后按业务需要调用接受接口。脱敏探针 JSON 可定位原消息、ABI、A8Key 或 HTTP 问题，避免盲目重建。若 auth 成功但 info 失败，检查 http_status、双层业务码、网络错误与 header 名称。用户已确认邀请查询与接受入群在微信 8.0.80 验证通过。实现不再按固定版本号拦截，仍检查实际原生类、方法和参数类型。过期／受限邀请、网络异常、账号切换及跨重启幂等按本节状态和重试边界处理。Apifox GUI 导入未测试。

HTTP 调用示例：

POST /accept_group_invitation HTTP/1.1
Content-Type: application/json

{"message_id":"123456789012345678"}

群管理员与群免打扰

下列两项使用相同的群 ID 和业务状态约定；示例 ID 均为虚构。

需要正常鉴权和登录，拒绝未知字段。群管理与免打扰受发送写入状态约束。群 ID 必须是普通微信群真实 ...@chatroom，不接受群名或 OpenIM 群。

群管理员操作

{"room_id":"123456789@chatroom","oper_type":1,"member_ids":["wxid_member_a"]}

oper_type 必须是 JSON 整数，拒绝布尔值、字符串。成员必须是群内其他普通微信成员的真实 user_name／wxid，不接受昵称或本人；数组去重并保留顺序。当前账号必须为群主，无法从本地群资料确认权限或成员时先刷新群资料。同一群同时只处理一个权限变更，全局最多 32 项待处理。

accepted 仅为原生方法的 BOOL 返回；request_submitted 仅表示取得本次原生事件 ID，均不能单独判断成功。每次调用等待约 30 秒并一次返回结果，调用方超时建议至少 40 秒，无需业务状态轮询。超时、断线或 unknown 时先核实群状态，不要自动重新提交；转让成功后原群主不再具备群主权限。

返回保留 room_id、oper_type、去重后的 member_ids，以及以下诊断字段：

常见 error_code：OWNER_REQUIRED、ROOM_STATE_UNAVAILABLE、OPERATION_BUSY、WRITE_DISABLED、REQUEST_NOT_CONFIRMED、WECHAT_REQUEST_REJECTED、OPERATION_TIMEOUT、ACCOUNT_CHANGED。不要把 null 错误码按 0 处理。

群聊消息免打扰

{"room_id":"123456789@chatroom","silence":true}

silence:true 开启免打扰，false 恢复通知。必须显式传入 JSON 布尔值，拒绝 0/1、字符串、null 和缺省。普通群成员即可操作，只影响当前账号的消息提醒设置。

响应保留 room_id、目标值 silence、accepted、sync_requested、already_set、local_verified、server_confirmed、status；非法或缺失的 silence 可为 null。accepted 是原生 BOOL，sync_requested 只表示进入原生同步路径；server_confirmed 固定为 false，本地数据库确认不等于服务端同步 ACK。失败或未知时附 error_code／error，未知结果先核实设置，不自动重提。

HTTP 调用与结果

请求使用 Content-Type: application/json，沿用本篇鉴权。上述参数直接放在请求体，业务结果直接位于响应顶层。业务失败或未知也返回 HTTP 200，必须检查 ok／status；通用鉴权、JSON 解析等错误沿用本篇约定，响应附 version。

管理员成功响应格式示例：

{
  "ok": true,
  "room_id": "123456789@chatroom",
  "oper_type": 1,
  "member_ids": [
    "wxid_member_a"
  ],
  "status": "succeeded",
  "accepted": true,
  "request_submitted": true,
  "server_confirmed": true,
  "request_cgi": 889,
  "event_id": 42,
  "wechat_ret": 0,
  "wechat_error_message": "",
  "message_type": 0,
  "transport_error_type": 0,
  "transport_error_code": 0,
  "version": "8.0.80-2"
}

验证范围

用户已确认 HTTP 群免打扰正常，管理员添加、移除和群主转让也均有 ok=true、status=succeeded、wechat_ret=0、server_confirmed=true 的真机回包。用户现已确认相关业务在微信 8.0.80 验证通过。这些群管理接口不包含进群申请审核。

POST /quit_group

用途：退出群聊。

成功响应：{"ok": true, "id": "..."}

11. 会话管理

POST /delete_session

用途：删除指定会话（聊天列表里的那条）。

成功响应：{"ok": true, "id": "1234567890@chatroom"}

注意：删除会话不会删除聊天记录，也不会删除好友关系。

12. 红包与转账

POST /receive_red_packet

用途：领取红包。

响应：透传领取结果（含领取状态、金额等字段）。失败时 400，但响应体里仍然带业务结果，便于你判断是"已经被领完"还是"参数不对"。

POST /red_packet_detail

用途：查询红包详情（不领取）。

响应：透传详情结果。

POST /receive_transfer

用途：确认收款。参数 transfer_id、message_id 均为 string，至少一项非空，推荐两个都传且对应同一笔转账。

响应：返回精简业务结果，成功 HTTP 200，业务失败 HTTP 400；进入收款业务后，失败也保留下表字段。鉴权、插件／发送开关等前置拒绝沿用通用错误格式，不保证收款业务字段齐全。

收到正常确认收款回包的示例：

{
  "ok": true,
  "version": "8.0.80-2",
  "transfer_id": "transfer_example",
  "message_id": "message_example",
  "status": "callback_ok",
  "accepted": true,
  "confirmed": true,
  "callback_received": true,
  "ret_code": 0,
  "error": ""
}

接口等待原生回包约 5 秒。status="confirm_invoked" 表示已发起确认、等待已超时，返回 ok=true, accepted=true, confirmed=false, callback_received=false, ret_code=null，不能认定资金已到账。callback_received 仅是辅助信号；匹配实际确认收款回包且成功时为 callback_ok，或独立查询取得原生状态 2001 后为 confirmed，才会得到 ok=true, confirmed=true。

收到回包却缺少合法返回码时，业务失败 HTTP 400 示例：

{
  "ok": false,
  "version": "8.0.80-2",
  "transfer_id": "transfer_example",
  "message_id": "message_example",
  "status": "callback_unknown",
  "accepted": true,
  "confirmed": false,
  "callback_received": true,
  "ret_code": null,
  "error": "转账回调缺少状态码，收款结果未知，请勿自动重试"
}

callback_unknown 或等待超时不要直接重试；使用下方 get_transfer_status 查询，原生状态 2001 才确认已收取。接收与退还同笔互斥，未知结果先查终态。

业务响应不包含整份 content／content_xml、native_url、callback、pay_info_probe 或 runtime_probe。排错时用 POST /debug/transfer_probe 在请求体传 transfer_id／message_id 查询；无参数 GET /debug/transfer_probe 读取最近快照。完整诊断快照也保留相关上下文，它们不作为收款成功依据。

转账：退还与查询状态

接口：POST /refund_transfer 退还待收取转账；POST /get_transfer_status 只查询服务器资金状态。退还要求插件和发送开关开启；查询不受发送开关限制；HTTP 监听仍可用且已通过鉴权时可查询，业务服务不另外用插件开关拦截这项只读操作。

请求体示例（两个接口通用）：

{
  "transfer_id": "transfer_example",
  "message_id": "message_example"
}

HTTP 成功返回 200，业务失败返回 400，响应体直接保留完整业务结果。鉴权等通道错误按本文第 3 节处理。下面依次是退还已提交仍等待、查询待收取、已确认退还和缓存失效示例：

{
  "ok": true,
  "transfer_id": "transfer_example",
  "message_id": "message_example",
  "accepted": true,
  "confirmed": false,
  "status": "refund_pending",
  "native_status": null,
  "ret_code": null,
  "error_code": "",
  "error": ""
}

{
  "ok": true,
  "transfer_id": "transfer_example",
  "message_id": "message_example",
  "accepted": false,
  "confirmed": false,
  "status": "waiting_receive",
  "native_status": 2000,
  "ret_code": 0,
  "error_code": "",
  "error": "",
  "can_refund": true,
  "status_description": "等待收款",
  "native_status_name": "waiting_receive"
}

{
  "ok": true,
  "transfer_id": "transfer_example",
  "message_id": "message_example",
  "accepted": true,
  "confirmed": true,
  "status": "refunded",
  "native_status": 2002,
  "ret_code": 0,
  "error_code": "",
  "error": ""
}

{
  "ok": false,
  "transfer_id": "",
  "message_id": "",
  "accepted": false,
  "confirmed": false,
  "status": "failed",
  "native_status": null,
  "ret_code": null,
  "error_code": "CACHE_NOT_FOUND",
  "error": "转账上下文已失效，请使用本次运行收到的转账消息"
}

本轮状态（2026-11-05）：用户此前已确认普通微信群内指定给自己的个人转账可领取；在 0.8.79-79 交付后，用户回传同笔转账查询 waiting_receive / native_status=2000 / can_refund=true，以及退还后 refunded / native_status=2002 / accepted=true / confirmed=true / ret_code=0，群内个人转账的查询和退还正常路径已实测通过。接口参数及结果结构不变，群 ID 从原消息读取，无需调用方补传。标准 Ubuntu 构建通过，新包为 0.8.79-79；旧包 0.8.79-78 的查询／退还仍保留群限制。此次回包未单独覆盖 WebSocket／长轮询外层收发、结果事件、重复操作、断网与账号切换，也未重新回传接收结果。

范围与前置条件：本轮源码支持当前登录账号作为收款人的普通微信个人转账（app_msg_type=2000），包括普通微信群内他人指定给当前账号的个人转账；不包括群收款／AA、企业互通群、任一方为 @openim 的交易、已收取后的退款或部分金额退还。群内转账须能读取原消息的个人付款人、接收人及群 ID，并确认本地群联系人属于普通微信群；群资料缺失或类型无法确认时仍拒绝。查询与退还都依赖本次运行收到的原转账消息，并要求缓存包含付款人、交易编号和已明确读取的非负整数有效期（允许 0，不等同于字段缺失）；本版不提供按历史交易号恢复上下文的入口。上下文按当前账号保存在内存中，最多 120 笔；重启、账号会话变化或淘汰后可能返回 CACHE_NOT_FOUND，持久化 ID 不能恢复该缓存。

请求参数：两个接口使用同一组参数，无其他业务输入；不能补传付款人、金额、交易号或有效期绕过原消息核验。

可以省略未提供的字段；不得传数字、null、数组或对象。去除首尾空白后两个字段都为空时失败；同时提供时必须指向同一笔，否则 ID_MISMATCH。

结果字段：下表说明业务结果，外层封装按本节本模式的示例读取。进入业务服务后固定返回这些基础字段；通道鉴权、插件禁用等更早的拒绝可采用本模式通用错误外壳，不能假设总有业务字段。

查询结果还可能返回 can_refund（boolean）、status_description（string）和 native_status_name（string，微信回包原生名称，可能为空）；微信错误回包可能带 wx_error_type（integer 或 null；回包未提供时为 null）。can_refund=true 仅表示服务器状态待收取、普通交易、双方匹配且无同笔未决收款／退还占用；不包含发送开关，也不保证后续风控允许退还。

成功判定与等待：只有 status="refunded" 且 native_status=2002 才代表已退还。ok=true、accepted=true、HTTP／命令传输成功或收到事件，均不能单独作为退还成功判据。两个新操作在当前请求／命令中短等待约 5 秒；排队、主线程调度和网络时间另计，客户端建议至少等待 15 秒。预检／查询超时且未提交时返回 QUERY_TIMEOUT, accepted=false；已提交但仍无终态时返回 refund_pending, accepted=true。提交后的确认查询可能返回 WECHAT_ERROR, accepted=true，仍须继续查询，不能认定退还确定失败。

重试与互斥：同一笔转账的接收与退还互斥，未决操作会返回 TRANSFER_BUSY；结果未知时保留占用，查询到终态后可回收占用。退还请求被微信明确拒绝才解除该退款提交的占用。重复调用不是按 request_id 持久幂等：ID 用于定位同笔转账，通道 request_id 只关联命令结果。网络超时、refund_pending、refund_unknown 或 accepted=true 的失败，都应先调用状态查询，不要改 ID、重启或自动重提退还／收款。未决保护不保证跨进程或跨账号会话延续。

业务错误码：失败保留结构化结果，不要只记录错误文字。

验证范围：普通个人转账的正常查询、接收与退还已有用户确认的真机记录：查询取得待收取 2000，退还后确认 2002，接收取得 callback_ok 且 confirmed=true。用户现已确认转账相关功能在微信 8.0.80 验证通过；重复操作、网络异常与账号切换仍按本节状态和重试规则处理。

退款完成／失败／未知时还可能收到 transfer_refund_result 事件；事件不可替代主动查询。

13. 账号资料与个人二维码

POST /clear_gender_region

用途：清除当前账号的性别与地区。

请求字段：无。

成功响应：

{
  "ok": true,
  "fields_cleared": ["sex", "country", "province", "city"],
  "restart_recommended": true
}

restart_recommended: true 表示建议重启微信让改动在界面上生效。

POST /profile_nickname（别名 /profile/nickname）

用途：修改当前账号昵称。

成功响应：{"ok": true, "nickname": "...", "restart_recommended": false}

前置条件：发送开关必须开启，否则 400 "profile_nickname is disabled"。

POST /profile/update、/profile/gender、/profile/region、/profile/signature

用途：设置或清空性别、地区、个性签名。上述写接口已通过用户真机 HTTP 全量测试，长轮询与 WebSocket 共用相同实现。

参数规则：

• 未提供的资料字段保持原值；性别、地区、签名单独入口只接受各自字段。未知字段与 null 在提交前拒绝。
• region_code 与 region 二选一。推荐先用下一节的 /profile/region_codes 查询完整代码。
• 地区是整组替换：传 region_code:"CN" 会设置国家并清空省市；传 region 时省市缺失也会清空。省不能脱离国家，市不能脱离省。自定义字符串按微信服务器实际处理结果展示。
• 签名使用微信 CAppUtil.calStringLen: 计数，上限 30。ASCII UTF-16 单元权重 1，其他单元权重 2，总权重除 2 向上取整；例如 30 个中文或 60 个 ASCII 可通过。超限直接拒绝，不截断。
• 拍一拍独立提交，不能放进 /profile/update。写操作要求发送开关开启。

提交响应示例：

{
  "ok": true,
  "accepted": true,
  "status": "submitted",
  "local_verified": true,
  "server_confirmed": false,
  "requested": {"signature": "今天也要开心"},
  "before": {"sex": 1, "country": "CN", "province": "Guangdong", "city": "Shenzhen", "signature": "", "current_user": "wxid_self"},
  "current": {"sex": 1, "country": "CN", "province": "Guangdong", "city": "Shenzhen", "signature": "今天也要开心", "current_user": "wxid_self"},
  "changed_fields": ["signature"],
  "error": "",
  "readback_error": "",
  "message": "资料已提交微信同步队列；本地读回不代表服务器确认"
}

accepted 表示微信受理，local_verified 表示本地读回，均不代表服务器确认；最终资料以微信展示为准。当前值已一致时返回 status:"unchanged"、accepted:false，不重复提交。失败为 HTTP 400；submitted_with_error 可能已入队，应检查 accepted、current 和错误信息再处理。

批量清空性别、地区和签名：

curl --request POST 'http://172.20.10.5:19088/profile/update' \
  --header 'Content-Type: application/json' \
  --data-raw '{"sex":0,"region_code":"","signature":""}'

POST /profile/region_codes：查询国家、省、市地区代码

用途：只读查询微信原生地区库，取得可直接用于 region_code 的完整代码。不要求发送开关，仍需插件授权。请求体仅接受可选字符串 parent_code；URL 查询参数不参与解析。

响应示例（仅展示一项）：

{
  "ok": true,
  "parent_code": "CN_Guangdong",
  "count": 1,
  "items": [
    {"code": "CN_Guangdong_Shenzhen", "name": "深圳", "parent_code": "CN_Guangdong", "type": 2}
  ],
  "selector_probe": {}
}

count 是本次列表实际数量。items[].code 是完整代码，name 是随微信语言变化的展示名；type 是原生层级标记，取不到为 null。始终用返回的 code 查询下一级或设置地区，不要根据中文名称拼代码。叶节点或不存在的父代码可能返回空列表；空列表不代表查询失败。

以下 curl 可分别导入 Postman / Apifox：

curl --request POST 'http://172.20.10.5:19088/profile/region_codes' \
  --header 'Content-Type: application/json' \
  --data-raw '{}'

curl --request POST 'http://172.20.10.5:19088/profile/region_codes' \
  --header 'Content-Type: application/json' \
  --data-raw '{"parent_code":"CN"}'

curl --request POST 'http://172.20.10.5:19088/profile/region_codes' \
  --header 'Content-Type: application/json' \
  --data-raw '{"parent_code":"CN_Guangdong"}'

POST /profile/pat_suffix：设置或清空拍一拍后缀

请求仅接受 {"pat_suffix":"的小脑袋"}；传 {"pat_suffix":""} 清空。发送开关需开启。

微信原生规则先处理空白/换行，再按 charLengthWithEmoOneCharPolicy:YES andIsFullWidth:NO 计数并检查禁止字符。限制来自动态配置，不能简单用字符串长度替代；本次真机上限 10、禁止字符为 <>/，以 /debug/profile_pat_suffix_probe 返回的 capabilities.max_length、capabilities.forbidden_characters 为准。

立即返回的关键字段：

{
  "ok": true,
  "accepted": true,
  "status": "pending",
  "server_confirmed": false,
  "local_verified": false,
  "operation_id": "示例操作UUID",
  "event_id": 123,
  "requested": "的小脑袋",
  "normalized": "的小脑袋",
  "length": 4,
  "max_length": 10,
  "error": ""
}

随后调用 GET /debug/profile_pat_suffix_probe，检查 last_operation：

只保存最近一次操作，重启微信后记录消失；上一项仍 pending 时拒绝第二项提交。用响应的 operation_id / event_id 与 last_operation 对照，避免把别的操作结果当作本次结果。该数字 event_id 是微信 oplog ID，与消息事件的去重键不同。

资料只读探针

预校验只返回 validation.valid、normalized、error 和 writes_performed:false，不会提交。探针的 ok:true 仅表示查询完成，还须检查 ready 或 validation.valid。头像探针显示 avatar.write_enabled:false、status:"deferred"，本轮未增加头像写接口。

POST /get_self_qrcode：获取自己的二维码

需要正常鉴权和登录，不受发送状态约束。请求体必须为 {}；自动使用当前登录账号，不接受 appId、wxid、style、refresh 或其他字段。本次请求二维码 URL，必要时生成 PNG；不读取旧磁盘图片，也不撤销旧二维码。同账号并发查询合并，等待约 30 秒，调用方超时建议至少 40 秒。

受限或失败时保留原始状态、提示及可用图片，不把受限结果按成功处理。失败时结合 error_code／error，不能只检查图片是否存在。

业务结果位于响应顶层；业务失败或未知也返回 HTTP 200，须结合 ok、status 和 error_code 判断。授权失败为 HTTP 403。个人二维码尚无本轮成功真机记录。

14. 朋友圈

你调用手机HTTP；不是调用后端的/agent/*。示例192.0.2.10:19088为文档占位地址，必须换成你自己的插件地址；媒体上传域名和Token也必须替换。所有示例数据均为虚构。

最短读取流程：

1. GET /health 确认端口、授权及功能状态，GET /account_status 确认微信登录。
2. POST /moments/list {}；保存首次返回的operation_id，此时pending只是微信正在查询。
3. 每1～2秒POST /moments/operation {"operation_id":"原编号"}，直至得到终态；也可提前启动/events监听完成事件。
4. 最终从items[]取动态；点开一条用/moments/detail，继续历史用next_cursor，看媒体用该动态的media[].mid。

curl --request POST 'http://192.0.2.10:19088/moments/list' --header 'Content-Type: application/json' --data-raw '{}'

curl --request POST 'http://192.0.2.10:19088/moments/operation' --header 'Content-Type: application/json' --data-raw '{"operation_id":"11111111-1111-4111-8111-111111111111"}'

返回结果怎么判断

accepted只表示微信查询／任务受理。互动和单帖权限先查详情，所以accepted=true可能只是详情查询已发出。write_accepted才表示提交了微信写操作；它不用于表达上传文件。server_confirmed只描述微信结果，不描述上传目标；媒体即使上传成功仍为false。

request_id用于关联；HTTP中可选，最长128个UTF-16单位，长轮询／WS从命令外层写入。它不是跨重启的幂等保证。操作记录最多48项，完成记录在后续请求进入时可能淘汰，通常最多保留10分钟；重启即丢失，不是永久任务数据库。账号切换后不能查询旧账号操作，旧账号事件也不会包成新账号事件。

一般查询／资源准备120秒超时且未提交微信写入时失败；已提交写入却未确认时可能unknown，晚回包仍可用更高revision更新原操作。相同范围处理中或unknown锁未释放时会拒绝新任务。网络断开也不能证明微信写入或后端上传没有发生。

首次HTTP受理示例：

{
  "ok": true,
  "status": "pending",
  "accepted": true,
  "write_accepted": false,
  "server_confirmed": false,
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "error": "",
  "action": "list"
}

完成查询示例：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "list",
  "accepted": true,
  "write_accepted": false,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "items": [],
  "next_cursor": "12345678901234567890",
  "has_more": null,
  "snapshot_complete": true,
  "snapshot_source": "network",
  "missing_ids": [],
  "raw_count": 1,
  "truncated": false
}

也可以接收HTTP事件。先记录自己的offset并拉取；每次读取后按返回的next_offset继续，按event_id去重。需要关联body.operation_id与原任务。事件可能早于查询结果到达，后端应能保存并合并。

curl --request POST 'http://192.0.2.10:19088/events' --header 'Content-Type: application/json' --data-raw '{"offset":0,"limit":50,"timeout_seconds":20}'

/events中的完成事件形态（省略通用时间字段）：

{
  "ok": true,
  "events": [
    {
      "update_id": 1775000000123,
      "event_name": "moments_result",
      "event_id": "msg:moments:11111111-1111-4111-8111-111111111111:1",
      "account_id": "wxid_self",
      "body": {
        "ok": true,
        "status": "succeeded",
        "operation_id": "11111111-1111-4111-8111-111111111111",
        "request_id": "demo-request-001",
        "action": "list",
        "accepted": true,
        "write_accepted": false,
        "server_confirmed": true,
        "revision": 1,
        "error": "",
        "items": [],
        "next_cursor": "12345678901234567890",
        "has_more": null,
        "snapshot_complete": true,
        "snapshot_source": "network",
        "missing_ids": [],
        "raw_count": 1,
        "truncated": false
      }
    }
  ],
  "next_offset": 1775000000124
}

朋友圈数据怎么继续使用

提交的动态ID、评论ID和cursor必须是非零UInt64十进制字符串，不接受JSON数字或溢出。输出sns_id和游标为字符串；评论ID沿用微信原生类型，可能为数字或字符串，后端需要无损解析大整数再转字符串。不要让64位ID经过JavaScript Number；网页demo已有无损保护。media_id保持mid原值，不要求它是十进制数。所有时间戳字段按字段名区分秒（create_time）与毫秒（*_ms）。

动态对象字段包括sns_id、wxid、create_time、content、type、is_mine、liked、like_count、comment_count、private、visibility_type、media、likes、comments。type和visibility_type保留微信原始值，不要把它们直接当发布接口的type/visibility枚举。普通图片动态type通常1，普通视频通常15。

媒体包含mid、type、subType、totalSize、videoDuration、width、height、preview_urls及原生可用的dataUrl/hdUrl/uhdUrl/lowBandUrl/attachUrl/attachThumbUrl。某字段不存在表示原生未提供。CDN地址不保证电脑直接可用；HTTP200也可能是占位图。列表不自动下载整页资源。

评论包含comment_id、comment64_id、wxid、nickname、content、create_time、is_mine及可用的reply_comment_id/reply_comment64_id/reply_wxid；likes沿用类似摘要结构。每条动态媒体最多32项、赞与评论各200项，media_truncated/interactions_truncated为true表示已截断；接口没有继续分页获取全部评论的入口。

历史和快照的正确判断

direction默认head。显式head不能带cursor；传cursor且省略direction时按tail；tail必须带上一页next_cursor，不能传0，不能自行减1，也不接受自定义page_size。页大小由微信控制。

has_more=false才表示原始历史网络空页已确认到头；has_more=null表示暂不确定，有next_cursor可以继续。items不足40条、筛选后空页都不等于到头。has_more不明确但next_cursor=null时，停止本轮继续翻页，不要编造游标；可以保留结果后稍后重新从最新页核实。

snapshot_complete表示本页是否补齐，不是全量历史完成。snapshot_source=network/network_merged_cache区分网络完整对象与网络／缓存合并。missing_ids列出无法补齐的动态，可查detail。unchanged=true也要检查完整性。单页最多200条，truncated表示原始页超出保护上限。

好友时间线是微信当前账号按权限筛选后的信息流，不保证是所有好友相册并集或无限历史。用户相册的 visible_period 使用明确原生字段或三天/半年提示；提示为空仍为 unknown。空页、缓存计数或 ret_tips 均不足以证明被屏蔽；可用 check_visibility 获取首屏诊断。后端自行保存、去重、比较历史；插件不自动定时刷新。

远程后端：手机主动上传媒体

推荐远程接入使用这一流程：后端先分配resource_id和上传地址 → 下发media/download并附upload → 手机调用微信下载、解密或复用缓存 → 手机主动HTTP上传 → 接收moments_result → 后端按resource_id取自己保存的文件。全程无需后端访问手机HTTP，也不会把文件Base64塞进长轮询／WS。

upload字段：

插件自动设置Content-Type=image/jpeg或video/mp4、Content-Length。不能覆盖这两个头、Host、Transfer-Encoding、Connection、Cookie、Proxy-Authorization。使用签名上传时，后端需按对应文件类型签名；resource_id不会自动变成HTTP头，后端自行在上传路径或自己的签名头中关联。

后端接收完整文件并成功存储后才返回2xx；推荐201或204。插件不解析上传响应正文，因此响应正文控制在64KiB内；文件访问URL由你的后端通过resource_id自行生成。返回2xx且上传字节完整后才upload_completed=true；30x不跟随，4xx/5xx失败，不进行插件层自动重传。

准备阶段最多120秒；开始上传后另有180秒总上限（请求等待上限90秒），一次上传模式操作最多约300秒。上传过程按需读文件，不整体加载视频。上传中断、超时或成功状态但缺完整传输确认时upload_outcome_unknown=true：后端可能已经存储，先按resource_id核实，再决定是否重传；接收端应对同一resource_id幂等保存。重传由后端显式发起，插件不提供断点续传。

上传URL与鉴权头只用于当前任务，不进入结果、事件或完成后的操作记录。切号、微信退出或进程重启可能中止任务；这不是跨进程持久后台上传。上传模式成功后没有手机media_url，也没有后端文件的expires_at_ms；保留期限由你的后端决定。微信原生缓存可复用；插件生成的JPEG在上传终态清理，不删除微信视频缓存。

已有零依赖示例位于demo/朋友圈媒体上传接收端/server.py：PUT /uploads/{小写UUID}接收文件，要求Authorization: Bearer <MOMENTS_UPLOAD_TOKEN>；GET /files/{同UUID}读取临时文件，支持Range。后端用UUID同时作为resource_id和路径即可。示例保留10分钟、最多16个资源、重启清空；GET链接含不可猜测UUID，知道链接即可读取，生产环境应按自己的账号鉴权和保留策略实现。

网页demo/朋友圈网页工作台可展开“手机主动上传媒体”，填写已部署接收端地址和Token；随后每次点击媒体下载会生成独立UUID并上传，网页从接收端读取。手机不能访问电脑的127.0.0.1，需要使用手机可达的接收端地址。网页仍用HTTP测试业务；长轮询／WS业务后端直接使用本节命令参数即可。

发布、权限与排错边界

发布visibility=public（公开）、private（仅自己）、include（仅指定用户）、exclude（不给指定用户看）。include/exclude须带非空wxids，最多200项；public/private不能带非空名单。新发布和修改已有本人动态均支持这四种范围；不临时修改微信UI全局发帖设置。

这些MiB是插件保护上限，不是微信通用服务器限额。视频时长、正文配置以当前账号探针为准，不能固定写成30秒或2000字。媒体下载成功也不保证所有电脑浏览器支持该视频编码。

好友权限friend查询为本地hide_from/dont_see；recent查询为本人period。修改recent支持three_days/one_month/half_year/all；查看别人的可见期限使用user。post查询是联网详情，返回item、visible_users、excluded_users；visibility_type是原生字段，修改参数仍使用字符串visibility。只允许修改本人动态。

权限写入的server_confirmed=true而local_verified=false表示服务器已成功、本地读回异常，local_update_error给出原因，不应因此再写一次。dont_see完整服务器确认缺失会保留unknown。不要用“本地开关已变化”代替服务器确认。

视频发布前下载支持无文件后缀URL，结合文件头／响应文件名处理，并异步等待AVFoundation元数据。video_diagnostics.stage为download/metadata/thumbnail/ready；保留file_bytes、extension、duration_seconds、video_track_count、playable、thumb_ready等已取得信息。下载及可选thumb_download含http_status、received_bytes、expected_bytes（-1未知）、elapsed_ms、phase及底层error_domain/error_code；系统提供时还有DNS／连接／响应／传输metrics。准备失败不发布。下载／元数据／封面问题可先使用probe检查，不能把probe成功当发布成功。

评论错误保留raw_ret、server_error及comment_diagnostics；引用不存在、本人评论或无权限对象会明确拒绝。点赞、评论、删除和修改已有单帖都先联网详情；一个帖子的处理中任务可能阻止同帖新请求，按原operation_id等结果。

验证范围：读取、发布互动、单帖权限及本地媒体预览已有 HTTP 真机验收记录。用户现已确认朋友圈相关功能（含主动上传）在微信 8.0.80 验证通过。朋友圈实现标识为 moments_20261016_upload_v1，与插件构建标记分开读取。

接口完整用法

下列每项包含请求字段、可直接使用的场景示例、结果含义与下一步。重复字段含义以本章前面的表格为准；所有示例响应均为虚构，省略部分可选字段。

好友最新时间线与历史：/moments/list

每次请求一页当前账号能看到的好友时间线。默认最新页；提供cursor且省略direction时按历史页处理。

最新页

curl --request POST 'http://192.0.2.10:19088/moments/list' --header 'Content-Type: application/json' --data-raw '{}'

历史下一页

curl --request POST 'http://192.0.2.10:19088/moments/list' --header 'Content-Type: application/json' --data-raw '{"direction":"tail","cursor":"12345678901234567890"}'

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "list",
  "accepted": true,
  "write_accepted": false,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "items": [
    {
      "sns_id": "12345678901234567890",
      "wxid": "wxid_friend",
      "create_time": 1775000000,
      "content": "示例动态",
      "type": 1,
      "is_mine": false,
      "liked": false,
      "like_count": 0,
      "comment_count": 1,
      "private": false,
      "visibility_type": 1,
      "media": [
        {
          "mid": "example-media-id",
          "type": 2,
          "width": 1080,
          "height": 1440,
          "preview_urls": []
        }
      ],
      "likes": [],
      "comments": [
        {
          "comment_id": 67,
          "comment64_id": "670000000000000001",
          "wxid": "wxid_friend",
          "content": "示例评论",
          "is_mine": false
        }
      ],
      "media_truncated": false,
      "interactions_truncated": false
    }
  ],
  "next_cursor": "12345678901234567890",
  "has_more": null,
  "snapshot_complete": true,
  "snapshot_source": "network",
  "missing_ids": [],
  "raw_count": 1,
  "truncated": false
}

下一步： 取items[].sns_id可查详情或互动；取next_cursor请求下一页；取media[].mid准备媒体。

指定用户相册与可见期限：/moments/user

传 wxid 获取本人或好友相册。visible_period 优先读取原生期限字段；字段不足时仅从明确的三天/半年提示补充，空提示仍为 unknown。visibility_status 是本次响应的可见性判断，不能据此确认被屏蔽、拉黑或删除。

可见性检查（HTTP 请求体或命令 args）

{"wxid":"wxid_xxx","check_visibility":true}

普通请求继续使用微信的 MD5 增量策略。诊断仍复用同一个相册入口；刷新接口在 scope=user、direction=head 时也支持 check_visibility。按原 operation_id 等待终态，items=[] 本身不能证明空相册或被屏蔽。

用户最新页

curl --request POST 'http://192.0.2.10:19088/moments/user' --header 'Content-Type: application/json' --data-raw '{"wxid":"wxid_xxx"}'

用户历史页

curl --request POST 'http://192.0.2.10:19088/moments/user' --header 'Content-Type: application/json' --data-raw '{"wxid":"wxid_xxx","cursor":"12345678901234567890"}'

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "user",
  "accepted": true,
  "write_accepted": false,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "items": [
    {
      "sns_id": "12345678901234567890",
      "wxid": "wxid_friend",
      "create_time": 1775000000,
      "content": "示例动态",
      "type": 1,
      "is_mine": false,
      "liked": false,
      "like_count": 0,
      "comment_count": 1,
      "private": false,
      "visibility_type": 1,
      "media": [
        {
          "mid": "example-media-id",
          "type": 2,
          "width": 1080,
          "height": 1440,
          "preview_urls": []
        }
      ],
      "likes": [],
      "comments": [
        {
          "comment_id": 67,
          "comment64_id": "670000000000000001",
          "wxid": "wxid_friend",
          "content": "示例评论",
          "is_mine": false
        }
      ],
      "media_truncated": false,
      "interactions_truncated": false
    }
  ],
  "next_cursor": "12345678901234567890",
  "has_more": null,
  "snapshot_complete": true,
  "snapshot_source": "network",
  "missing_ids": [],
  "raw_count": 1,
  "truncated": false,
  "visible_period": "all",
  "visible_period_source": "sns_user_info",
  "visibility_status": "visible",
  "check_visibility": false,
  "request_md5_empty": true,
  "top_raw_count": 0,
  "same_md5_count": 0,
  "raw_ret": 0,
  "privacy_flags_raw": 4096,
  "privacy_recent_raw": 4294967295,
  "ret_tips": "",
  "limited_id": "0",
  "continue_id": "0"
}

可见性诊断字段

只有原生返回码为 0 或 207、head 请求实际 MD5 为空、普通和置顶条数及同 MD5 计数均明确为零、continue_id 明确为 "0" 时，才报告 empty_or_restricted。同 MD5 未变化、仅有缓存计数、字段缺失或首屏未完成时不能据空数组下结论。

操作状态保持兼容：非零 raw_ret 仍返回 status=failed、ok=false、server_confirmed=false，同时保留取得的诊断字段；visibility_status 独立描述响应证据。没有原生响应的网络失败中，visibility_status 保持 unknown，不输出确定的 blocked 标志。受理结果及失败回调可能只有未知值，必须等待原 operation_id 的终态或对应 moments_result。

下一步： 继续历史时保留同一个wxid并使用本页next_cursor；历史页visible_period=unknown不能覆盖此前已确认的期限。

联网获取动态详情：/moments/detail

根据列表、发布结果或已知sns_id联网查询，返回item。媒体、评论及权限信息仍受当前账号服务器可见范围限制。

动态详情

curl --request POST 'http://192.0.2.10:19088/moments/detail' --header 'Content-Type: application/json' --data-raw '{"sns_id":"12345678901234567890"}'

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "detail",
  "accepted": true,
  "write_accepted": false,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "item": {
    "sns_id": "12345678901234567890",
    "wxid": "wxid_friend",
    "create_time": 1775000000,
    "content": "示例动态",
    "type": 1,
    "is_mine": false,
    "liked": false,
    "like_count": 0,
    "comment_count": 1,
    "private": false,
    "visibility_type": 1,
    "media": [
      {
        "mid": "example-media-id",
        "type": 2,
        "width": 1080,
        "height": 1440,
        "preview_urls": []
      }
    ],
    "likes": [],
    "comments": [
      {
        "comment_id": 67,
        "comment64_id": "670000000000000001",
        "wxid": "wxid_friend",
        "content": "示例评论",
        "is_mine": false
      }
    ],
    "media_truncated": false,
    "interactions_truncated": false
  }
}

下一步： 点赞、评论使用item.sns_id；回复取本帖comments中的comment_id或comment64_id；媒体下载取本帖media中的mid。

服务端触发刷新并接收结果：/moments/refresh

scope省略时为timeline；scope=user时必须传wxid。刷新获取本次页面快照并产生moments_result，不启动定时任务，也不自动计算全局增删差异。支持与list/user相同的历史参数。