Wechatbot Webhook

<div align="center"> <img src="./docs/Jietu20240506-220141%402x.jpg" width="500"/>

<a href="https://discord.gg/qBF9VsBdc8"><img src="https://img.shields.io/discord/1165844612473172088?logo=Discord&link=https%3A%2F%2Fdiscord.gg%qBF9VsBdc8" /></a>

🚢 Docker 镜像 | 📦 NPM包｜🔍 FAQ

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

</div>

✨ 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

• Url：http://localhost:3001/webhook/msg/v2?token=[YOUR_PERSONAL_TOKEN]
• Methods: POST
• ContentType: application/json
• Body: 格式见下面表格

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": []
    }
}

读文件发送

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

• Url：http://localhost:3001/webhook/msg?token=[YOUR_PERSONAL_TOKEN]
• Methods: POST
• ContentType: multipart/form-data
• FormData: 格式见下面表格

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 | <div>功能类型</div><ul><li>✅ 文字(text)</li><li>✅ 链接卡片(urlLink)</li><li>✅ 图片(file)</li><li>✅ 视频(file)</li><li>✅ 附件(file)</li> <li>✅ 语音(file)</li><li>✅ 添加好友邀请(friendship)</li></ul><di