# wechatbot-webhook

**Repository Path**: dragonlhp/wechatbot-webhook

## Basic Information

- **Project Name**: wechatbot-webhook
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2024-01-10
- **Last Updated**: 2025-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
<img src="https://cdn.jsdelivr.net/gh/danni-cool/danni-cool@cdn/image/wechatbot-webhook.png" width="500" height="251"/>

![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/danni-cool/wechatbot-webhook/release.yml) ![npm dowloads](https://img.shields.io/npm/dm/wechatbot-webhook?label=npm/downloads)
 ![Docker Pulls](https://img.shields.io/docker/pulls/dannicool/docker-wechatbot-webhook) ![GitHub release (with filter)](https://img.shields.io/github/v/release/danni-cool/wechatbot-webhook)
<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 镜像](https://hub.docker.com/repository/docker/dannicool/docker-wechatbot-webhook/general)| [📦 NPM包](https://www.npmjs.com/package/wechatbot-webhook)｜[🔍 FAQ](https://github.com/danni-cool/wechatbot-webhook/issues/72)
</div>

开箱即用的 Wechaty 应用层项目，实现了一个支持消息收发的微信 webhook 机器人，当 http 调用和二次开发亦可，二次开发请fork

## ✨ Features

- **推送消息** (发送文字 / 图片 / 文件)
  - 💬 支持消息单条 / 多条 / 群发
  - 🌃 消息 url 解析成文件发送
  - 📁 支持读文件发送

- **接收消息**（文字 / 图片 / 语音 / 视频 / 文件 / 好友申请 / 公众号推文链接）
  - 🚗 单 API 收发消息（依赖收消息API，被动回复无需公网IP）
  - 🪧 登入掉线异常事件通知

- **其他功能**
  - 🤖 支持 非掉线自动登录
  - ✈️ 支持 带鉴权 api 接口获取登陆二维码
  - 支持 [n8n](https://n8n.io/) 低码平台丝滑接入（webhook 节点）
  - 🚢 支持 docker 部署，兼容 `arm64` 和 `amd64`
  - ✍️ 支持 日志文件导出

## 🚀 一分钟 Demo

### 1. 运行

```bash
npx wechatbot-webhook
```

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

### 2. 扫码登录

![](https://cdn.jsdelivr.net/gh/danni-cool/danni-cool@cdn/image/Jietu20231224-170732.gif)

### 3. 使用 http 请求给指定用户发消息

新开个终端试试以下 curl，to字段值换成你要发送的昵称

```bash
curl --location 'http://localhost:3001/webhook/msg/v2' \
--header 'Content-Type: application/json' \
--data '{ "to": "测试昵称", data: { "content": "Hello World!" }}'
```

## ⛰️ 部署 Deploy（推荐）

### Docker 部署

#### 1. 启动容器

```bash
# 启动容器并映射日志目录，日志按天维度生成，e.g: app.2024-01-01.log
docker run -d --name wxBotWebhook -p 3001:3001 \
-v ~/wxBot_logs:/app/log \
dannicool/docker-wechatbot-webhook
```

#### 2. 登录

```bash
docker logs -f wxBotWebhook
```

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

<https://localhost:3001/login?token=YOUR_PERSONAL_TOKEN>

#### Docker 可选 env 参数

> Tips：需要增加参数使用 -e，多行用 \ 隔开，例如 -e  RECVD_MSG_API="<https://example.com/your/url>" \

| 功能 | 环境变量 | 案例 | 备注 |
|--|--|--|--|
|  收消息 |   RECVD_MSG_API  |   RECVD_MSG_API=<https://example.com/your/url>   |  如果想自己处理收到消息的逻辑，比如根据消息联动，填上你的处理逻辑 url，该行可以省略 |
| 禁用自动登录 | DISABLE_AUTO_LOGIN | DISABLE_AUTO_LOGIN=true |  非微信踢下线账号，可以依靠session免登, 如果想每次都扫码登陆，则增加该条配置 |
| 自定义登录 API token | LOGIN_API_TOKEN | LOGIN_API_TOKEN=abcdefg123 | 你也可以自定义一个自己的登录令牌，不配置的话，默认会生成一个 |

## 🛠️ API

### 1. 推消息 API

> v2版本接口增加了群发功能，v1 版本接口请移步 [legacy-api](./docs/legacy-api)

- Url：<http://localhost:3001/webhook/msg/v2>
- 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）

##### 发单条消息

```bash
curl --location 'http://localhost:3001/webhook/msg/v2' \
--header 'Content-Type: application/json' \
--data '{
    "to": "testUser",
    "data": { "content": "你好👋" }
}'
```

##### 发给群消息

```bash
curl --location 'http://localhost:3001/webhook/msg/v2' \
--header 'Content-Type: application/json' \
--data '{
    "to": "testGroup",
    "isRoom": true,
    "data": { "type": "fileUrl" , "content": "https://download.samplelib.com/jpeg/sample-clouds-400x300.jpg" },
}'
```

##### 同一对象多条消息(群消息同理)

```bash
curl --location 'http://localhost:3001/webhook/msg/v2' \
--header 'Content-Type: application/json' \
--data '{
    "to": "testUser",
    "data": [
        {
            "type": "text",
            "content": "你好👋"
        },
        {
            "type": "fileUrl",
            "content": "https://samplelib.com/lib/preview/mp3/sample-3s.mp3"
        }
    ]
}'
```

##### 群发消息

``` bash
curl --location 'http://localhost:3001/webhook/msg/v2' \
--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 提示

> 确保消息单次发送一致性，某一条参数校验失败会终止所有消息发送任务

```json
{
    "success": true,
    "message": "",
    "task": {
        "successCount": 0,
        "totalCount": 0,
        "failedCount": 0,
        "reject": [],
        "sentFailed": [],
        "notFound": []
    }
}
```

#### 读文件发送

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

- Url：<http://localhost:3001/webhook/msg>
- Methods: `POST`
- ContentType: `multipart/form-data`
- FormData: 格式见下面表格

##### `payload` 结构

| 参数    | 说明                                                                             | 数据类型 | 默认值 | 可否为空 | 可选值  |
| ------- | -------------------------------------------------------------------------------- | -------- | ------ | -------- | ------- |
| to      | 消息接收方，传入`String` 默认是发给昵称（群名同理）, 传入 Json String 结构支持发给备注过的人，比如："{alias: '备注名'}"，群名不支持备注名称                                       | `String` | -      | N        | -       |
| isRoom  | **是否发的群消息**，formData纯文本只能使用 `String` 类型，`1`代表是，`0`代表否， | `String` | `0`    | Y        | `1` `0` |
| content | **文件**，本地文件一次只能发一个，多个文件手动调用多次                           | `Binary` | -      | N        | -       |

##### Curl

```bash
curl --location --request POST 'http://localhost:3001/webhook/msg' \
--form 'to=testGroup' \
--form content=@"$HOME/demo.jpg" \
--form 'isRoom=1'
```

#### 返回值 `response` 结构

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

### 2. 收消息 API

> 收消息API现在支持通过返回值实现**快捷回复**，无需再发起 post 请求，一个 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> refer: [wechaty类型支持列表](https://wechaty.js.org/docs/api/message#messagetype--messagetype) | `String`          | `text` `file` `urlLink` `friendship` | -                                                |
| content       | 传输的内容, 文本或传输的文件共用这个字段，结构映射请看示例                                                                                                                                                                                                                | `String` `Binary` |                         | [示例](docs/recvdApi.example.md#formdatacontent) |
| source        | 消息的相关发送方数据, JSON String                                                                                                                                                                                                                                         | `String`          |                         | [示例](docs/recvdApi.example.md#formdatasource)  |
| isMentioned   | 该消息是@我的消息[#38](https://github.com/danni-cool/wechatbot-webhook/issues/38)                                                                                                                                                                                  | `String`          | `1` `0`                 | -                                                |
| isSystemEvent | 是否是来自系统消息事件（上线，掉线、异常事件、快捷回复后的通知）                                                                                                                                                                                                                        | `String`          | `1` `0`                 | -                                                |

**服务端处理 formData 一般需要对应的处理程序，假设你已经完成这一步，你将得到以下 request**

```json
  {
    "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",
    "isSystemEvent": "0"
  }
```

**收消息 api curl示例(直接导入postman调试）**

```curl
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"' \
--form 'isSystemEvent="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 | - |

如果回复单条消息

```json
 {
    "success": true,
    "data": {
      "type": "text",
      "message": "hello world！"
    }
  }
```

组合回复多条消息

```json
 {
    "success": true,
    "data": [
      {
        "type": "text",
        "message": "hello world！"
      },
      {
        "type": "fileUrl",
        "message": "https://samplelib.com/lib/preview/mp3/sample-3s.mp3"
      }
    ]
  }
```

### 3. 其他API

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

#### `/login?token=YOUR_PERSONAL_TOKEN`

- **描述**：获取登录二维码接口。
- **methods**: `GET`
- **query**: token

**status**: `200`
登录成功，返回 json 包含当前用户

```json
{"success":true,"message":"Contact<TestUser>is already login"}
```

**status**: `302`
登录态掉了，跳转最新的登录二维码 

#### `/healthz?token=YOUR_PERSONAL_TOKEN`

- **描述**：健康检测接口。
- **methods**: `GET`
- **query**: token
- **status**: `200`

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


## 🌟 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=danni-cool/wechatbot-webhook&type=Date)](https://star-history.com/#danni-cool/wechatbot-webhook&Date)

## ⏫ 更新日志

更新内容参见 [CHANGELOG](https://github.com/danni-cool/docker-wechat-roomBot/blob/main/CHANGELOG.md)