标题
微信api接口转发消息调用教程（微信api接口转发消息调用教程视频）
本文约2400字，预计需要9分钟
知更Ai（zhigengai.com）微信api接口转发消息调用教程，适合需要把微信收到的消息同步到业务程序、指定好友或群聊的开发者和运营团队。知更Ai提供两条相关链路：一条是通过 WebSocket 接收实时消息，另一条是通过 HTTP API 转发已经收到的消息。
实际使用时，可以按照下面的流程理解：
微信收到消息 → WebSocket 推送消息 → 程序获取
msgsvrid→ 调用转发 API → 转发到指定好友或群聊
如果只是转发一条已经获取到消息编号的历史消息，可以直接调用 HTTP 接口；如果需要实时处理，就先建立 WebSocket 连接，再调用转发接口。
微信API接口转发消息，需要准备什么
开始调用前，需要确认以下条件：
- 知更Ai已经添加并登录目标微信账号；
- 机器人处于在线状态；
- 调用程序和知更Ai运行在同一台电脑上；
- 已在系统设置中获取 WebSocket Token；
- 使用的账号具备对应 API 功能权限；
- 已经明确消息来源、转发对象和筛选条件。
知更Ai的 WebSocket 服务只监听本机地址 127.0.0.1，端口为 5010，完整地址是：
HTTP 消息接口使用本机 5011 端口。转发任意消息的地址是：
这里的两个接口用途不同：
| 接口 | 用途 |
|---|---|
WebSocket /api/ws/relay |
接收实时微信消息 |
HTTP /api/forward/any |
根据消息编号转发消息 |
HTTP /api/msg/text |
新建并发送一条文本消息 |
微信消息转发的核心参数
转发任意消息时，需要提交三个参数：
| 参数 | 是否必填 | 说明 |
|---|---|---|
bot_id |
是 | 执行转发的机器人微信号标识 |
msgsvrid |
是 | 要转发的服务器消息 ID，需要从消息推送数据中获取 |
receiver |
是 | 接收对象，可以是好友 wxid 或群聊 ID |
其中，msgsvrid是整个流程的关键。程序不能只根据消息文字内容调用转发接口，还需要从实时消息数据中取得对应的服务器消息 ID。
一个基础请求示例如下：
{"bot_id": "wxid_xxx",
"msgsvrid": "4294312797723933242",
"receiver": "group_xxx"
}
对应的请求方式是：
POST http://127.0.0.1:5011/api/forward/anyContent-Type: application/json
微信API使用指南：直接调用转发接口
如果已经有了 bot_id、msgsvrid 和 receiver，可以直接向 HTTP API 发起请求。
Python 调用示例
import requests url = "http://127.0.0.1:5011/api/forward/any" payload = { "bot_id": "wxid_xxx", "msgsvrid": "4294312797723933242", "receiver": "group_xxx" } response = requests.post(url, json=payload, timeout=15) print(response.status_code) print(response.json())
JavaScript 调用示例
const response = await fetch( "http://127.0.0.1:5011/api/forward/any", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ bot_id: "wxid_xxx", msgsvrid: "4294312797723933242", receiver: "group_xxx" }) } ); const result = await response.json(); console.log(result);
调用成功时，HTTP 状态一般为 200，并且返回数据中的 code 为 0：
{ "code": 0, "message": "ok", "data": { "status": "sent" } }
如果调用失败，通常会返回 HTTP 400，业务状态码为 -1：
{ "code": -1, "message": "转发任意消息失败: <底层错误信息>", "data": null }
判断是否真正调用成功时，应同时查看 HTTP 状态和返回内容中的 code，不能只看请求是否发出。
微信聊天API接口调用：先接收实时消息
如果希望在收到某类消息后再转发，需要先连接 WebSocket。
WebSocket 服务的基础信息如下：
- 地址：
ws://127.0.0.1:5010/api/ws/relay - 端口：
5010 - 路径：
/api/ws/relay - 消息方向：服务端推送到客户端
- Token：在系统设置页面查看或刷新
- 可用前提：需要具备对应的 VIP 功能权限
连接建立后，第一帧必须发送鉴权 JSON：
{ "type": "auth", "key": "wk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
其中：
type必须是auth；key填写系统设置中的ws_token；- JSON 需要以文本帧发送；
- 鉴权成功后，服务端不会额外发送确认消息，客户端可以直接等待后续推送。
如果鉴权失败，服务端会发送类似下面的内容，然后关闭连接：
{ "type": "auth_failed", "reason": "invalid token" }
微信发送消息接口的完整联动示例
下面的示例展示“接收实时消息，再转发指定消息”的基本结构。示例只对包含特定关键词的消息执行后续处理，实际使用时还应增加来源校验、接收对象白名单和人工确认条件。
import asyncio
import json
import requests
import websockets
WS_URL = "ws://127.0.0.1:5010/api/ws/relay"
WS_TOKEN = "wk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
FORWARD_URL = "http://127.0.0.1:5011/api/forward/any"
TARGET_RECEIVER = "group_xxx"
async def main():
async with websockets.connect(WS_URL) as ws:
await ws.send(json.dumps({
"type": "auth",
"key": WS_TOKEN
}))
async for raw in ws:
message = json.loads(raw)
if message.get("type") == "auth_failed":
print("鉴权失败：", message.get("reason"))
break
if message.get("event") != "on_message":
continue
robot_wxid = message.get("robot_wxid")
data = message.get("data") or {}
for item in data.get("msglist", []):
content = item.get("content", "")
msgsvrid = item.get("msgsvrid")
if not msgsvrid:
continue
# 示例条件：只处理包含“资料”的文本消息
if "资料" not in content:
continue
payload = {
"bot_id": robot_wxid,
"msgsvrid": msgsvrid,
"receiver": TARGET_RECEIVER
}
result = requests.post(
FORWARD_URL,
json=payload,
timeout=15
)
print("转发结果：", result.json())
asyncio.run(main())
这个示例中的 msglist 是消息列表，robot_wxid用于区分消息来自哪个机器人，msgsvrid用于定位要转发的消息。
多账号场景下，应始终使用推送数据里的 robot_wxid 作为机器人标识，不要用昵称等可能发生变化的字段判断消息归属。
分享转发API接口的步骤与注意事项
如果要实现“指定好友消息同步到群聊”，可以按照以下步骤配置：
- 在机器人管理中添加并登录微信账号。
- 确认机器人在线。
- 在系统设置中查看 WebSocket Token。
- 程序连接
ws://127.0.0.1:5010/api/ws/relay。 - 连接后立即发送
auth鉴权帧。 - 监听
event字段为on_message的推送数据。 - 从
data.msglist中提取消息内容和msgsvrid。 - 根据来源、关键词或消息类型进行筛选。
- 调用
/api/forward/any。 - 检查返回的
code是否为0，并记录执行结果。
在消息转发模块中，也可以直接通过页面配置完成类似任务。配置时需要选择：
- 主讲人，也就是消息来源；
- 同步对象，也就是消息接收方；
- 需要转发的内容类型；
- 高级过滤关键词；
- 关键词替换规则；
- 消息跟发规则。
需要注意，主讲人只能选择好友或群内成员，不能直接选择群本身；同步对象可以选择好友或群聊，但不能选择群成员作为独立接收对象。
不同消息类型的转发边界
知更Ai的消息转发功能支持文本、图片、文件、视频、GIF、语音、位置、小程序和视频号等内容类型。
“转发任意消息”接口通过 msgsvrid定位历史消息，但当前文档明确说明该接口无法转发语音。若业务场景包含语音，需要单独确认当前版本支持的处理方式，不要直接按照文本、图片的方式调用。
如果只是发送新文本，而不是转发已经收到的历史消息，可以调用：
POST http://127.0.0.1:5011/api/msg/text请求数据如下：
{"bot_id": "wxid_xxx",
"receiver": "group_xxx",
"content": "这是一条新的文本消息"
}
这两个接口的区别是：
/api/forward/any：转发已经存在的消息，需要msgsvrid；/api/msg/text：创建并发送一条新的文本消息，需要content。
常见调用问题
连接成功但收不到消息
先检查以下项目：
- WebSocket 地址是否使用了
5010端口； - 路径是否为
/api/ws/relay； - 第一帧是否确实发送了鉴权 JSON；
- Token是否来自系统设置中的最新值；
- 机器人是否处于在线状态；
- 当前账号是否具备对应功能权限。
WebSocket 服务只监听 127.0.0.1。如果程序运行在另一台电脑上，不能直接使用这个本机地址，需要根据官方提供的其他接口方式进行集成。
转发接口返回失败
重点检查：
bot_id是否填写了机器人微信号标识；msgsvrid是否来自当前消息推送；receiver是否为正确的好友 wxid 或群聊 ID；- 机器人是否已经退出或离线；
- 当前消息类型是否属于接口支持范围；
- HTTP 请求体是否为合法 JSON。
为什么只收到部分消息
WebSocket 推送数据中的 event可能不止一种。客户端应先判断 event == "on_message"，再读取data和msglist。对于其他事件类型，应按照实际字段进行分流处理，不要直接当作普通微信消息解析。
合规与数据安全提醒
消息转发涉及联系人、群聊内容和业务资料，建议只处理已经获得授权的消息和接收对象。程序中应避免把 Token 写入公开代码仓库，也不要把本机接口暴露给不必要的网络设备。
知更Ai的相关接口以本机服务为主，便于在本地化环境中处理数据。使用自动化功能时，应保持安全、绿色、稳定、合规的使用方式，设置清晰的转发条件和合理的处理节奏，先进行小范围验证，再逐步扩大应用范围。
以平台官方规则为准，使用自动化功能前请了解并遵守相关平台政策与法律法规。
常见问题
问：微信API接口转发消息调用教程适合什么场景？
答：适合把指定微信消息同步到好友或群聊，也适合将实时消息接入自己的脚本、桌面程序或业务系统。实时场景需要 WebSocket 接收消息，再调用 HTTP 转发接口。
问：微信API接口需要什么参数？
答：转发任意消息需要 bot_id、msgsvrid 和 receiver 三个参数，其中 msgsvrid需要从消息推送数据中获取。
问：微信消息发送API和消息转发接口有什么区别？
答：消息发送 API 用于新建并发送文本等内容；消息转发接口用于根据已有消息的服务器消息 ID，转发已经收到的消息。
问：微信发送消息接口调用失败怎么办？
答：先检查机器人是否在线、参数是否完整、接收对象标识是否正确，再查看 HTTP 状态和返回内容中的 code。code == 0表示业务调用成功。
问：微信接口开发教程中为什么要使用 WebSocket？
答：WebSocket适合接收实时消息推送，可以在收到指定内容后，再由程序调用转发 API。只转发已知消息时，则可以直接调用 HTTP 接口。
