Caution
当前版本基于web协议，其支持的功能有限，也不完美，除了bug修补和稳定性功能外，不再接收新的 feature request，后续精力会放到 windows 分支上，感兴趣的可以点个 watch 👀
| 功能 | web协议 | windows协议 |
|---|---|---|
| 目前可用性 | ✅ | ❌ |
| 代码分支 | main | windows |
| Docker Tag | latest | windows |
| <发送消息> | ✅ 单条 / 多条 / 群发 | ✅ 单条 / 多条 / 群发 |
| 发文字 | ✅ | ✅ |
| 发图片 | ✅ 本地图片 / url图片解析 | ✅ 本地图片 / url图片解析 |
| 发视频（mp4) | ✅ 本地视频 / url视频解析 | |
| 发文件 | ✅ 本地文件 / url文件解析 | ✅ 本地文件 / url文件解析 |
| <接收消息> | ||
| 接收文字 | ✅ | ✅ |
| 接收语音 | ✅ | |
| 接收图片 | ✅ | |
| 接收视频 | ✅ | |
| 接收文件 | ✅ | |
| 接收公众号推文链接 | ✅ | |
| 接收系统通知 | ✅ 上线通知 / 掉线通知 / 异常通知 | |
| 头像获取 | ✅ | |
| 快捷回复 | ✅ | ✅ |
| <群管理> | ||
| <好友管理> | ||
| 接收好友申请 | ✅ | |
| 通过好友申请 | ✅ | |
| 获取联系人列表 | ||
| <其他功能> | ||
| 非掉线自动登录 | ✅ | |
| API 鉴权 | ✅ | ✅ |
| n8n 无缝接入 | ✅ | |
| 支持docker部署 | ✅ arm64 / amd64 | ✅ amd64 |
| 日志文件导出 | ✅ | ✅ |
以上提到的功能 ✅ 为已实现，受限于微信协议限制，不同协议支持功能也是不同的，并不是所有功能都可以对接，例如：
- 企业微信消息的收发 #142
- 发送语音消息 / 分享音乐 / 公众号等在 features 中未提到的功能
npx wechatbot-webhook除非掉线，默认记住上次登录，换帐号请运行以下命令
npx wechatbot-webhook -r
从命令行中复制推消息api，例如 http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]
新开个终端试试以下 curl，to、token 字段值换成你要值
curl --location 'http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]' \
--header 'Content-Type: application/json' \
--data '{ "to": "测试昵称", data: { "content": "Hello World!" }}'Important
包管理器迁移已至 pnpm，安装依赖请使用它，以支持一些不定时的临时包修补（patches）和加速依赖安装
docker pull dannicool/docker-wechatbot-webhook
# 启动容器并映射日志目录，日志按天维度生成，e.g: app.2024-01-01.log
docker run -d --name wxBotWebhook -p 3001:3001 \
-v ~/wxBot_logs:/app/log \
dannicool/docker-wechatbot-webhookwget -O docker-compose.yml https://cdn.jsdelivr.net/gh/danni-cool/wechatbot-webhook@main/docker-compose.yml && docker-compose down && docker-compose -p wx_bot_webhook updocker logs -f wxBotWebhook找到二维码登录地址，图下 url 部分，浏览器访问，扫码登录wx
https://localhost:3001/login?token=[YOUR_PERSONAL_TOKEN]
Tips：需要增加参数使用 -e，多行用 \ 隔开，例如 -e RECVD_MSG_API="https://example.com/your/url" \
| 功能 | 变量 | 备注 |
|---|---|---|
| 日志级别 | LOG_LEVEL=info | 日志级别，默认 info，只影响当前日志输出，详细输出考虑使用 debug。无论该值如何变化，日志文件总是记录debug级别的日志 |
| 收消息 API | RECVD_MSG_API=https://example.com/your/url | 如果想自己处理收到消息的逻辑，比如根据消息联动，填上你的处理逻辑 url |
| 收消息 API 接受自己发的消息 | ACCEPT_RECVD_MSG_MYSELF=false | RECVD_MSG_API 是否接收来自自己发的消息（设置为true，即接收, 默认false） |
| 自定义登录 API token | LOGIN_API_TOKEN=abcdefg123 | 你也可以自定义一个自己的登录令牌，不配置的话，默认会生成一个 |
| 禁用自动登录 | DISABLE_AUTO_LOGIN=true | 非微信踢下线账号，可以依靠当前登录的session免登, 如果想每次都扫码登陆，则增加该条配置 |
v2版本接口增加了群发功能，v1 版本接口请移步 legacy-api
- Url：http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]
- Methods:
POST - ContentType:
application/json - Body: 格式见下面表格
发文字或文件外链, 外链会解析成图片或者文件
| 参数 | 说明 | 数据类型 | 默认值 | 可否为空 | 可选参数 |
|---|---|---|---|---|---|
| to | 消息接收方，传入String 默认是发给昵称（群名同理）, 传入Object 结构支持发给备注过的人，比如：{alias: '备注名'}，群名不支持备注名 |
String Object |
- | N | - |
| isRoom | 是否发给群消息，这个参数决定了找人的时候找的是群还是人，因为昵称其实和群名相同在技术处理上 | Boolean |
false |
Y | true false |
| data | 消息体结构,见下方 payload.data |
Object Array |
false |
N | true false |
| 参数 | 说明 | 数据类型 | 默认值 | 可否为空 | 可选参数 |
|---|---|---|---|---|---|
| type | 消息类型, 字段留空解析为纯文本 | String text |
- | Y | text fileUrl |
| content | 消息内容，如果希望发多个Url并解析，type 指定为 fileUrl 同时，content 里填 url 以英文逗号分隔 | String |
- | N | - |
curl --location 'http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]' \
--header 'Content-Type: application/json' \
--data '{
"to": "testUser",
"data": { "content": "你好👋" }
}'有些情况下，直接发送 url 文件名可能不是我们想要的，给 url 拼接 query 参数
$alias可用于指定发送给目标的文件名（注意：别名不做文件转换）
curl --location 'http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]' \
--header 'Content-Type: application/json' \
--data '{
"to": "testUser",
"data": {
"type": "fileUrl" ,
"content": "https://download.samplelib.com/jpeg/sample-clouds-400x300.jpg?$alias=cloud.jpg"
}
}'curl --location 'http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]' \
--header 'Content-Type: application/json' \
--data '{
"to": "testGroup",
"isRoom": true,
"data": { "type": "fileUrl" , "content": "https://download.samplelib.com/jpeg/sample-clouds-400x300.jpg" },
}'curl --location 'http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]' \
--header 'Content-Type: application/json' \
--data '{
"to": "testUser",
"data": [
{
"type": "text",
"content": "你好👋"
},
{
"type": "fileUrl",
"content": "https://samplelib.com/lib/preview/mp3/sample-3s.mp3"
}
]
}'curl --location 'http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]' \
--header 'Content-Type: application/json' \
--data '[
{
"to": "testUser1",
"data": {
"content": "你好👋"
}
},
{
"to": "testUser2",
"data": [
{
"content": "你好👋"
},
{
"content": "近况如何？"
}
]
}
]'success: 消息发送成功与否，群发消息即使部份发送成功也会返回truemessage: 出错时提示的消息- 消息发送成功: Message sent successfully
- 参数校验不通过: Some params is not valid, sending task is suspend...
- 消息都发送失败: All Messages [number] sent failed...
- 部份发送成功: Part of the message sent successfully...
task: 发送任务详细信息task.successCount: 发送成功条数task.totalCount: 总消息条数task.failedCount: 发送失败条数task.reject: 因为参数校验不通过的参数和 error 提示task.sentFailed: 因为发送失败和 error 提示task.notFound: 因为未找到用户或者群和 error 提示
确保消息单次发送一致性，某一条参数校验失败会终止所有消息发送任务
{
"success": true,
"message": "",
"task": {
"successCount": 0,
"totalCount": 0,
"failedCount": 0,
"reject": [],
"sentFailed": [],
"notFound": []
}
}读文件暂时只支持单条发送
- Url：http://localhost:3001/webhook/msg?token=[YOUR_PERSONAL_TOKEN]
- Methods:
POST - ContentType:
multipart/form-data - FormData: 格式见下面表格
| 参数 | 说明 | 数据类型 | 默认值 | 可否为空 | 可选值 |
|---|---|---|---|---|---|
| to | 消息接收方，传入String 默认是发给昵称（群名同理）, 传入 Json String 结构支持发给备注过的人，比如：--form 'to="{alias: "小号"}"'，群名不支持备注名称 |
String |
- | N | - |
| isRoom | 是否发的群消息，formData纯文本只能使用 String 类型，1代表是，0代表否， |
String |
0 |
Y | 1 0 |
| content | 文件，本地文件一次只能发一个，多个文件手动调用多次 | Binary |
- | N | - |
curl --location --request POST 'http://localhost:3001/webhook/msg?token=[YOUR_PERSONAL_TOKEN]' \
--form 'to=testGroup' \
--form content=@"$HOME/demo.jpg" \
--form 'isRoom=1'{
"success": true,
"message": "Message sent successfully"
}- Methods:
POST - ContentType:
multipart/form-data - Form格式如下
| formData | 说明 | 数据类型 | 可选值 | 示例 |
|---|---|---|---|---|
| type | 功能类型
其他类型
系统类型
|
String |
text file urlLink friendship unknown system_event_login system_event_logout system_event_error system_event_push_notify |
- |
| content | 传输的内容, 文本或传输的文件共用这个字段，结构映射请看示例 | String Binary |
示例 | |
| source | 消息的相关发送方数据, JSON String | String |
示例 | |
| isMentioned | 该消息是@我的消息 #38 | String |
1 0 |
- |
| isMsgFromSelf | 是否是来自自己的消息 #159 | String |
1 0 |
- |
服务端处理 formData 一般需要对应的处理程序，假设你已经完成这一步，你将得到以下 request
{
"type": "text",
"content": "你好",
"source": "{\"room\":\"\",\"to\":{\"_events\":{},\"_eventsCount\":0,\"id\":\"@f387910fa45\",\"payload\":{\"alias\":\"\",\"avatar\":\"/cgi-bin/mmwebwx-bin/webwxgeticon?seq=1302335654&username=@f38bfd1e0567910fa45&skey=@crypaafc30\",\"friend\":false,\"gender\":1,\"id\":\"@f38bfd1e10fa45\",\"name\":\"ch.\",\"phone\":[],\"star\":false,\"type\":1}},\"from\":{\"_events\":{},\"_eventsCount\":0,\"id\":\"@6b5111dcc269b6901fbb58\",\"payload\":{\"address\":\"\",\"alias\":\"\",\"avatar\":\"/cgi-bin/mmwebwx-bin/webwxgeticon?seq=123234564&username=@6b5dbb58&skey=@crypt_ec356afc30\",\"city\":\"Mars\",\"friend\":false,\"gender\":1,\"id\":\"@6b5dbd3facb58\",\"name\":\"Daniel\",\"phone\":[],\"province\":\"Earth\",\"signature\":\"\",\"star\":false,\"weixin\":\"\",\"type\":1}}}",
"isMentioned": "0",
"isMsgFromSelf": "0",
"isSystemEvent": "0" // 考虑废弃，请使用type类型判断系统消息
}收消息 api curl示例(直接导入postman调试）
curl --location 'https://your.recvdapi.com' \
--form 'type="file"' \
--form 'content=@"/Users/Downloads/13482835.jpeg"' \
--form 'source="{\\\"room\\\":\\\"\\\",\\\"to\\\":{\\\"_events\\\":{},\\\"_eventsCount\\\":0,\\\"id\\\":\\\"@f387910fa45\\\",\\\"payload\\\":{\\\"alias\\\":\\\"\\\",\\\"avatar\\\":\\\"/cgi-bin/mmwebwx-bin/webwxgeticon?seq=1302335654&username=@f38bfd1e0567910fa45&skey=@crypaafc30\\\",\\\"friend\\\":false,\\\"gender\\\":1,\\\"id\\\":\\\"@f38bfd1e10fa45\\\",\\\"name\\\":\\\"ch.\\\",\\\"phone\\\":[],\\\"star\\\":false,\\\"type\\\":1}},\\\"from\\\":{\\\"_events\\\":{},\\\"_eventsCount\\\":0,\\\"id\\\":\\\"@6b5111dcc269b6901fbb58\\\",\\\"payload\\\":{\\\"address\\\":\\\"\\\",\\\"alias\\\":\\\"\\\",\\\"avatar\\\":\\\"/cgi-bin/mmwebwx-bin/webwxgeticon?seq=123234564&username=@6b5dbb58&skey=@crypt_ec356afc30\\\",\\\"city\\\":\\\"Mars\\\",\\\"friend\\\":false,\\\"gender\\\":1,\\\"id\\\":\\\"@6b5dbd3facb58\\\",\\\"name\\\":\\\"Daniel\\\",\\\"phone\\\":[],\\\"province\\\":\\\"Earth\\\",\\\"signature\\\":\\\"\\\",\\\"star\\\":false,\\\"weixin\\\":\\\"\\\",\\\"type\\\":1}}}"' \
--form 'isMentioned="0"'
如果期望用
RECVD_MSG_API收消息后立即回复(快捷回复)，请按以下结构返回返回值，无返回值则不会回复消息
- ContentType:
json
| 参数 | 说明 | 数据类型 | 默认值 | 可否为空 | 可选参数 |
|---|---|---|---|---|---|
| success | 该条请求成功与否，返回 false 或者无该字段，不会处理回复，有一些特殊消息也通过这个字段控制，比如加好友邀请，返回 true 则会通过好友请求 |
Boolean |
- | Y | true false |
| data | 如果需要回复消息的话，需要定义data字段 | Object Object Array |
- | Y |
| 参数 | 说明 | 数据类型 | 默认值 | 可否为空 | 可选参数 |
|---|---|---|---|---|---|
| type | 消息类型，该字段不填默认当文本类型传输 | String |
text |
Y | text fileUrl |
| content | 消息内容，如果希望发多个Url并解析，type 指定为 fileUrl 同时，content 里填 url 以英文逗号分隔 | String |
- | N | - |
如果回复单条消息
{
"success": true,
"data": {
"type": "text",
"content": "hello world！"
}
}组合回复多条消息
{
"success": true,
"data": [
{
"type": "text",
"content": "hello world！"
},
{
"type": "fileUrl",
"content": "https://samplelib.com/lib/preview/mp3/sample-3s.mp3"
}
]
}除了在 docker 启动时配置token，在默认缺省 token 的情况，会默认生成一个写入
.env文件中
- 地址：
/login - methods:
GET - query: token
- status:
200 - example: http://localhost:3001/login?token=[YOUR_PERSONAL_TOKEN]
返回 json 包含当前用户
{"success":true,"message":"Contact<TestUser>is already login"}展示微信登录扫码页面
可以主动轮询该接口，检查服务是否正常运行
- 地址：
/healthz - methods:
GET - query: token
- status:
200 - example: http://localhost:3001/healthz?token=[YOUR_PERSONAL_TOKEN]
微信已登录, 返回纯文本 healthy，否则返回 unHealthy
从 2.8.0 版本开始，可以通过本接口访问到头像等静态资源，具体见 recvd_api 数据结构示例的 avatar 字段
注意所有上报 recvd_api 的静态资源地址不会默认带上 token, 需要自己拼接，否则会返回 401 错误, 请确保自己微信已登录，需要通过登录态去获取资源
-
地址：
/resouces -
methods:
GET -
query:
- token: 登录token
- media: encode过的相对路径，比如
/avatar/1234567890.jpgencode为avatar%2F1234567890.jpg
-
status:
200404401
成功获取资源, 返回静态资源文件
获取资源失败
{"success":false, "message":"Unauthorized: Access is denied due to invalid credentials."}{
"success": false, "message": "you must login first"
}Thanks to all our contributors!
更新内容参见 CHANGELOG
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "github-actions[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent