Skip to content
/ wechatbot-webhook Public
forked from danni-cool/wechatbot-webhook

轻量、可部署的微信机器人webhook服务，使用http接口收发微信消息, 用它作为个人通知、AIGC 应用或者 coze、n8n等自动化工作流的消息节点

License

MIT license
0 stars 284 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

mrhuang5678/wechatbot-webhook

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

499 Commits
.github
.github
 
 
.husky
.husky
 
 
.vscode
.vscode
 
 
docs
docs
 
 
packages/cli
packages/cli
 
 
patches
patches
 
 
scripts
scripts
 
 
src
src
 
 
typings
typings
 
 
.dockerignore
.dockerignore
 
 
.editorconfig
.editorconfig
 
 
.env.example
.env.example
 
 
.eslintignore
.eslintignore
 
 
.eslintrc.js
.eslintrc.js
 
 
.gitignore
.gitignore
 
 
.npmrc
.npmrc
 
 
.prettierrc.js
.prettierrc.js
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
commitlint.config.js
commitlint.config.js
 
 
docker-compose.yml
docker-compose.yml
 
 
dockerfile
dockerfile
 
 
main.js
main.js
 
 
package.json
package.json
 
 
pnpm-lock.yaml
pnpm-lock.yaml
 
 
pnpm-workspace.yaml
pnpm-workspace.yaml
 
 
tsconfig.json
tsconfig.json
 
 

Repository files navigation

GitHub Workflow Status (with event) npm dowloads Docker Pulls GitHub release (with filter)

🚢 Docker 镜像 | 📦 NPM包｜🔍 FAQ

一个小小的微信机器人webhook，帮你抹平了很多自己开发的障碍，基于 http 请求，与hooks微信不同，因为基于web api，所以优势在于可以部署到arm架构等设备上

✨ Features

Caution

项目目前基于web微信，其本身就有被限制风险，另外大概两天一掉线，除了正常功能修补，不接新的 feature request。 windows 协议正在WIP，近期应该会和大家见面！

功能 web协议 windows协议
目前可用性 ✅ ❌
代码分支 main windows
Docker Tag latest windows
<发送消息> ✅ 单条 / 多条 / 群发 ✅ 单条 / 多条 / 群发
发文字 ✅ ✅
发图片 ✅ 本地图片 / url图片解析 ✅ 本地图片 / url图片解析
发视频（mp4) ✅ 本地视频 / url视频解析
发文件 ✅ 本地文件 / url文件解析 ✅ 本地文件 / url文件解析
<接收消息>
接收文字 ✅ ✅
接收语音 ✅
接收图片 ✅
接收视频 ✅
接收文件 ✅
接收公众号推文链接 ✅
接收系统通知 ✅ 上线通知 / 掉线通知 / 异常通知
头像获取 ✅
快捷回复 ✅ ✅
<群管理>
<好友管理>
接收好友申请 ✅
通过好友申请 ✅
获取联系人列表
<其他功能>
非掉线自动登录 ✅
API 鉴权 ✅ ✅
n8n 无缝接入 ✅
支持docker部署 ✅ arm64 / amd64 ✅ amd64
日志文件导出 ✅ ✅

⚠️ 特别说明：

以上提到的功能 ✅ 为已实现，受限于微信协议限制，不同协议支持功能也是不同的，并不是所有功能都可以对接，例如：

  • 企业微信消息的收发 #142
  • 发送语音消息 / 分享音乐 / 公众号等在 features 中未提到的功能

🚀 一分钟 Demo

1. 运行 & 扫码

npx wechatbot-webhook

除非掉线，默认记住上次登录，换帐号请运行以下命令 npx wechatbot-webhook -r

如遇安装报错，请确保自己的node版本 >= 18.14.1 #227

2. 复制推消息 api

从命令行中复制推消息api，例如 http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]

3. 使用以下结构发消息

新开个终端试试以下 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）和加速依赖安装

⛰️ 部署 Deploy（推荐）

1.使用 docker 部署

拉取最新镜像
docker pull dannicool/docker-wechatbot-webhook
docker 部署
# 启动容器并映射日志目录，日志按天维度生成，e.g: app.2024-01-01.log
docker run -d --name wxBotWebhook -p 3001:3001 \
-v ~/wxBot_logs:/app/log \
dannicool/docker-wechatbot-webhook
使用 compose 部署 (可选)
wget -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 up

2.登录

docker logs -f wxBotWebhook

找到二维码登录地址，图下 url 部分，浏览器访问，扫码登录wx

https://localhost:3001/login?token=[YOUR_PERSONAL_TOKEN]

可选 env 参数

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免登, 如果想每次都扫码登陆，则增加该条配置

🛠️ API

1. 推消息 API

v2版本接口增加了群发功能，v1 版本接口请移步 legacy-api

payload 结构

发文字或文件外链, 外链会解析成图片或者文件

参数 说明 数据类型 默认值 可否为空 可选参数
to 消息接收方，传入String 默认是发给昵称（群名同理）, 传入Object 结构支持发给备注过的人，比如：{alias: '备注名'}，群名不支持备注名 String Object - N -
isRoom 是否发给群消息，这个参数决定了找人的时候找的是群还是人，因为昵称其实和群名相同在技术处理上 Boolean false Y true false
data 消息体结构,见下方 payload.data Object Array false N true false

payload.data 结构

参数 说明 数据类型 默认值 可否为空 可选参数
type 消息类型, 字段留空解析为纯文本 String text - Y text fileUrl
content 消息内容，如果希望发多个Url并解析，type 指定为 fileUrl 同时，content 里填 url 以英文逗号分隔 String - N -

Example（curl）

发单条消息
curl --location 'http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]' \
--header 'Content-Type: application/json' \
--data '{
    "to": "testUser",
    "data": { "content": "你好👋" }
}'
发文件 url 同时支持修改成目标文件名

有些情况下，直接发送 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": "近况如何？"
          }
        ]
    }
]'

返回值 response 结构

  • success: 消息发送成功与否，群发消息即使部份发送成功也会返回 true
  • message: 出错时提示的消息
    • 消息发送成功: 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": []
    }
}

读文件发送

读文件暂时只支持单条发送

payload 结构
参数 说明 数据类型 默认值 可否为空 可选值
to 消息接收方，传入String 默认是发给昵称（群名同理）, 传入 Json String 结构支持发给备注过的人，比如：--form 'to="{alias: "小号"}"'，群名不支持备注名称 String - N -
isRoom 是否发的群消息，formData纯文本只能使用 String 类型，1代表是，0代表否， String 0 Y 1 0
content 文件，本地文件一次只能发一个，多个文件手动调用多次 Binary - N -
Curl
curl --location --request POST 'http://localhost:3001/webhook/msg?token=[YOUR_PERSONAL_TOKEN]' \
--form 'to=testGroup' \
--form content=@"$HOME/demo.jpg" \
--form 'isRoom=1'

返回值 response 结构

{
  "success": true,
  "message": "Message sent successfully"
}

2. 收消息 API

payload 结构

  • Methods: POST
  • ContentType: multipart/form-data
  • Form格式如下
formData 说明 数据类型 可选值 示例
type
功能类型
  • ✅ 文字(text)
  • ✅ 链接卡片(urlLink)
  • ✅ 图片(file)
  • ✅ 视频(file)
  • ✅ 附件(file)
  • ✅ 语音(file)
  • ✅ 添加好友邀请(friendship)
其他类型
  • 未实现的消息类型(unknown)
系统类型
  • ✅ 登录(system_event_login)
  • ✅ 登出(system_event_logout)
  • ✅ 异常报错(system_event_error)
  • ✅ 快捷回复后消息推送状态通知(system_event_push_notify)
 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"'

返回值 response 结构（可选）

如果期望用 RECVD_MSG_API 收消息后立即回复(快捷回复)，请按以下结构返回返回值，无返回值则不会回复消息

  • ContentType: json
参数 说明 数据类型 默认值 可否为空 可选参数
success 该条请求成功与否，返回 false 或者无该字段，不会处理回复，有一些特殊消息也通过这个字段控制，比如加好友邀请，返回 true 则会通过好友请求 Boolean - Y true false
data 如果需要回复消息的话，需要定义data字段 Object Object Array - Y

response.data 结构

参数 说明 数据类型 默认值 可否为空 可选参数
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"
      }
    ]
  }

3. 其他API

token 配置说明

除了在 docker 启动时配置token，在默认缺省 token 的情况，会默认生成一个写入 .env 文件中

3.1 获取登录二维码接口

登录成功

返回 json 包含当前用户

{"success":true,"message":"Contact<TestUser>is already login"}
登录失败

展示微信登录扫码页面

3.2 健康检测接口

可以主动轮询该接口，检查服务是否正常运行

微信已登录, 返回纯文本 healthy，否则返回 unHealthy

3.3 获取静态资源接口

从 2.8.0 版本开始，可以通过本接口访问到头像等静态资源，具体见 recvd_api 数据结构示例的 avatar 字段

注意所有上报 recvd_api 的静态资源地址不会默认带上 token, 需要自己拼接，否则会返回 401 错误, 请确保自己微信已登录，需要通过登录态去获取资源

status: 200

成功获取资源, 返回静态资源文件

status: 404

获取资源失败

status: 401 未携带登录token
{"success":false, "message":"Unauthorized: Access is denied due to invalid credentials."}
status: 401 微信登录态已过期
{
   "success": false, "message": "you must login first"
}

🌟 Star History

Star History Chart

Contributors

Thanks to all our contributors!

⏫ 更新日志

更新内容参见 CHANGELOG

About

轻量、可部署的微信机器人webhook服务，使用http接口收发微信消息, 用它作为个人通知、AIGC 应用或者 coze、n8n等自动化工作流的消息节点

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 98.8%
  • Shell 1.2%