微信公众号 / 服务号

微信公众号 / 服务号。HTTP 回调接收 + 客服消息 / 被动回复发送；开启 passiveMode 后未认证公众号也能在 5 秒内被动回复。

适配器类型："wechat"　源码：src/adapter/wechat/ 协议：微信公众平台（公众号/服务号），HTTP 回调接收 + 客服消息/被动回复发送。

说明

特点

• HTTP 回调接收消息，支持文本、图片、语音
• 两种发送模式：被动回复（无需认证，5秒内）+ 客服消息（需认证，48小时内）
• 图片/语音自动上传素材后发送

原理

• 接收：微信服务器 POST 事件到回调 URL，适配器校验签名后解析 XML
• 发送（被动回复）：在 HTTP 响应中直接返回 XML，5 秒内有效
• 发送（客服消息）：POST https://api.weixin.qq.com/cgi-bin/message/custom/send

前提

• 微信公众平台注册公众号/服务号
• 回调地址公网可达（http 走 80 端口 / https 走 443 端口）
• 客服消息接口需要微信认证（未认证公众号用 passiveMode）

安装

适配器安装

van adapter install wechat

依赖库

无额外依赖（纯 HTTP）。

配置

{
  "botId": "WeChat-Official",
  "type": "wechat",
  "appId": "wx你的AppID",
  "appSecret": "你的AppSecret",
  "token": "你的服务器配置Token",
  "port": 8090,
  "path": "/wechat/callback",
  "passiveMode": true
}

配置项	必填	说明
appId	✅	公众号 AppID
appSecret	✅	AppSecret（用于换取 access_token）
token	✅	公众平台后台填的 Token（用于签名校验）
port	✅	回调监听端口
path	可选	回调路径，默认 "/"
passiveMode	推荐	被动回复模式，默认 true；未认证公众号必须开启

接收事件

微信事件	框架事件	说明
文本/图片/语音消息	private_message	userId=用户 openid
关注/取关等	notice	raw.notice_type 标识

API 调用

被动回复（passiveMode，推荐）

消息进来 5 秒内调 send_msg，会以 XML 被动回复直接返回（无需认证）：

await bot.callApi("send_private_msg", {
  user_id: "用户openid",
  message: "回复内容"
})

客服消息（需认证公众号）

用户 48 小时内有互动时可主动推送：

await bot.callApi("send_msg", {
  user_id: "用户openid",
  message: "主动推送"
})

显式被动回复

await bot.callApi("passive_reply", {
  user_id: "用户openid",
  content: "要返回的文本"
})

图片/语音会自动上传素材后发送；多段消息按顺序发送。

常见问题

• 收不到消息：回调地址公网不可达、Token 不一致、未在公众平台提交服务器配置。
• Invalid signature：URL 端口配错（http 只能 80 / https 只能 443）。
• errcode:48001：未认证公众号调用客服接口，开 passiveMode:true 走被动回复。
• 40164：服务器 IP 不在白名单，但 passiveMode 不受影响。

相关项目

• 微信公众平台开发文档：https://developers.weixin.qq.com/doc/offiaccount/