# 企业微信消息发送工具

**Repository Path**: web/work-weixin-pusher

## Basic Information

- **Project Name**: 企业微信消息发送工具
- **Description**: 企业微信消息发送工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-25
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业微信消息发送工具

## 项目概述

本项目是一个基于PHP5.6开发的企业微信消息发送工具，严格按照企业微信文档规范实现，支持多种消息类型的发送，包括文本、markdown、markdown_v2、图片和图文消息。同时，针对超长内容，提供了自动分片发送功能，确保消息能够完整传递。

## 功能特性

- ✅ **文本消息** (text) - 支持超长内容自动分片，支持@指定成员
- ✅ **Markdown消息** (markdown) - 支持超长内容自动分片
- ✅ **Markdown V2消息** (markdown_v2) - 支持超长内容自动分片
- ✅ **图片消息** (image) - 支持本地图片和网络图片
- ✅ **图文消息** (news) - 支持标题、描述、图片和跳转链接
- ✅ **自动分片** - 当消息内容超过企业微信限制时，自动拆分成多个消息发送
- ✅ **分片标记** - 每个分片消息都包含分片编号信息，便于接收方识别
- ✅ **完整性保证** - 确保长消息的完整传递，避免内容截断
- ✅ **配置灵活** - 支持通过配置文件设置默认Webhook地址
- ✅ **API接口** - 提供HTTP API接口，方便其他系统调用
- ✅ **@人员功能** - 支持通过userid或手机号@指定成员

## 安装环境

- PHP 5.6+
- cURL 扩展（用于发送HTTP请求）
- file_get_contents 函数支持（用于读取图片）

## 演示地址

https://tool.bitefu.net/qywx/

## Webhook地址获取方法

### 方式一：通过企业微信管理后台获取

1. 登录企业微信管理后台：https://work.weixin.qq.com/
2. 进入「应用管理」页面
3. 选择需要接收消息的应用（如果没有，先创建一个应用）
4. 在应用详情页面，找到「接收消息」模块
5. 点击「设置API接收」或「设置企业号」为企业微信
6. 在Webhook配置中，会话授权中找到Webhook地址
7. 复制完整的Webhook地址（格式如：`https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxx`）

### 方式二：通过群机器人获取

1. 打开企业微信PC客户端或手机端
2. 进入需要接收消息的群聊
3. 点击群设置（右上角齿轮图标）
4. 选择「群机器人」选项
5. 点击「添加机器人」
6. 创建一个新的群机器人
7. 复制机器人详情中的Webhook地址

### 方式三：通过自建应用获取

1. 登录企业微信管理后台
2. 进入「应用管理」→「自建应用」
3. 创建或选择一个应用
4. 在应用详情中获取AgentId
5. 获取应用的Secret（需要在「我的企业」页面获取）
6. 通过API调用获取access_token后，再调用发送消息接口

### Webhook地址格式

企业微信Webhook地址格式如下：

```
https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

**注意**：
- 请妥善保管Webhook地址，不要泄露给他人
- 每个Webhook地址只对应一个机器人或应用
- Webhook地址可以在应用设置中重新生成

## 快速开始

### 1. 配置Webhook地址和Key

在 `QyWechatPusher.php` 文件中，修改默认的Webhook地址和key：

```php
private $config = array(
    "webhook_url" => "https://qyapi.weixin.qq.com/cgi-bin/webhook/send",
    "key" => "" // 替换为实际的Webhook key
);
```

或者在创建实例时传入配置：

```php
$config = array(
    "webhook_url" => "https://qyapi.weixin.qq.com/cgi-bin/webhook/send",
    "key" => "your-webhook-key"
);
$pusher = new QyWechatPusher($config);
```

### 2. 发送消息示例

#### 发送文本消息

```php
require_once 'QyWechatPusher.php';

$pusher = new QyWechatPusher();
$result = $pusher->sendMessage("服务器监控：CPU使用率正常", "text");
print_r($result);
```

#### 发送文本消息并@指定成员（使用userid）

```php
require_once 'QyWechatPusher.php';

$pusher = new QyWechatPusher();
$content = "服务器监控：CPU使用率正常，请相关人员注意";
$mentionedList = array("user001", "user002");
$result = $pusher->sendMessage($content, "text", null, $mentionedList, true);
print_r($result);
```

#### 发送文本消息并@指定成员（使用手机号）

```php
require_once 'QyWechatPusher.php';

$pusher = new QyWechatPusher();
$content = "系统告警：内存使用率超过80%，请相关人员及时处理";
$mentionedMobileList = array("138****0001", "138****0002");
$result = $pusher->sendMessage($content, "text", $mentionedMobileList, null, true);
print_r($result);
```

#### 发送长文本消息（启用分片）

```php
require_once 'QyWechatPusher.php';

$pusher = new QyWechatPusher();
// 生成超过2048字节的长文本
$longText = str_repeat("这是一段测试文本，用于测试长消息的自动分片功能。", 50);
$result = $pusher->sendMessage($longText, "text", null, null, true);
print_r($result);
```

#### 使用自定义Webhook和key

```php
require_once 'QyWechatPusher.php';

// 创建实例时传入自定义配置
$config = array(
    "webhook_url" => "https://qyapi.weixin.qq.com/cgi-bin/webhook/send",
    "key" => "your-webhook-key"
);
$pusher = new QyWechatPusher($config);

$content = "测试自定义Webhook和key";
$result = $pusher->sendMessage($content, "text");
print_r($result);
```

#### 发送文本消息并@所有人

```php
require_once 'QyWechatPusher.php';

$pusher = new QyWechatPusher();
$content = "重要通知：今晚进行系统维护，请所有人员提前做好准备";
$result = $pusher->sendMessage($content, "text");
print_r($result);
```

#### 发送Markdown消息

```php
require_once 'QyWechatPusher.php';

$pusher = new QyWechatPusher();
$content = "**📊 系统状态**\n\n- CPU使用率：65%\n- 内存使用率：72%\n- 磁盘使用率：45%";
$result = $pusher->sendMessage($content, "markdown");
print_r($result);
```

#### 发送图片消息

```php
require_once 'QyWechatPusher.php';

$pusher = new QyWechatPusher();
// 支持本地图片路径或网络图片URL
$result = $pusher->sendMessage("https://example.com/image.png", "image");
print_r($result);
```

#### 发送图文消息

```php
require_once 'QyWechatPusher.php';

$pusher = new QyWechatPusher();
// 创建图文消息
$article = $pusher->createNewsArticle(
    "系统更新通知",
    "系统将于今晚进行更新维护",
    "https://example.com/detail",
    "https://example.com/image.png"
);
$result = $pusher->sendMessage($article, "news");
print_r($result);
```

## API接口使用

本项目提供了HTTP API接口，方便其他系统通过HTTP请求发送消息。

### 接口地址

```
http://your-domain/api.php
```

### 请求方法

POST

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| content | mixed | 是 | 消息内容（根据不同的消息类型，格式不同） |
| msg_type | string | 是 | 消息类型 (text/markdown/markdown_v2/image/news) |
| webhook_url | string | 否 | Webhook地址（使用默认配置时可不填） |
| key | string | 否 | Webhook key（使用默认配置时可不填） |
| enable_chunking | bool | 否 | 是否启用分片发送 (默认true) |
| mentioned_list | array | 否 | 需要@的成员userid列表，示例: ["user001", "user002"] |
| mentioned_mobile_list | array | 否 | 需要@的成员手机号列表，示例: ["138****0001", "138****0002"] |

### 请求示例

#### 文本消息

```json
{
  "content": "服务器监控：CPU使用率正常",
  "msg_type": "text"
}
```

#### @指定成员（使用userid）

```json
{
  "content": "服务器监控：CPU使用率正常，请相关人员注意",
  "msg_type": "text",
  "mentioned_list": ["user001", "user002"]
}
```

#### @指定成员（使用手机号）

```json
{
  "content": "系统告警：内存使用率超过80%，请相关人员及时处理",
  "msg_type": "text",
  "mentioned_mobile_list": ["138****0001", "138****0002"]
}
```

#### @所有人

```json
{
  "content": "重要通知：今晚进行系统维护，请所有人员提前做好准备",
  "msg_type": "text"
}
```

#### Markdown消息

```json
{
  "content": "**📊 系统状态**\n\n- CPU使用率：65%\n- 内存使用率：72%",
  "msg_type": "markdown"
}
```

#### 图片消息

```json
{
  "content": "https://example.com/image.png",
  "msg_type": "image"
}
```

#### 图文消息

```json
{
  "content": {
    "title": "系统更新通知",
    "description": "系统将于今晚进行更新维护",
    "url": "https://example.com/detail",
    "picurl": "https://example.com/image.png"
  },
  "msg_type": "news"
}
```

### 响应示例

#### 成功响应

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "success": true,
    "message": "消息发送成功",
    "data": {
      "errcode": 0,
      "errmsg": "ok"
    }
  }
}
```

#### 失败响应

```json
{
  "code": 400,
  "message": "缺少必要参数"
}
```

## @人员功能说明

企业微信文本消息支持@功能，可以通过以下方式指定需要@的成员：

### mentioned_list - 成员userid列表

- 参数类型：数组
- 说明：需要@的成员userid列表
- 获取方式：在企业微信管理后台的「通讯录」中可以查看成员的UserID
- 示例：`["user001", "user002"]`

### mentioned_mobile_list - 成员手机号列表

- 参数类型：数组
- 说明：需要@的成员手机号列表
- 获取方式：成员在企业微信绑定的手机号
- 示例：`["138****0001", "138****0002"]`

### @所有人

- 设置 `mentioned_list` 或 `mentioned_mobile_list` 为 `["@all"]` 即可@所有人
- 不指定@人员时，默认@所有人

### 注意事项

- 仅文本消息(text)支持@功能
- 图片、Markdown、图文等消息类型不支持@功能
- 分片发送时，仅第一片消息会@成员，后续分片不会重复@

## 测试脚本

本项目提供了 `demo.php` 测试脚本，用于测试各种消息类型的发送功能：

```bash
php demo.php
```

### 测试用例列表

1. `testTextMessage` - 发送文本消息
2. `testMarkdownMessage` - 发送Markdown消息
3. `testLongTextMessage` - 发送长文本消息（自动分片）
4. `testLongMarkdownMessage` - 发送长Markdown消息（自动分片）
5. `testImageMessage` - 发送图片消息
6. `testNewsMessage` - 发送图文消息
7. `testCustomWebhook` - 使用自定义Webhook发送消息
8. `testCustomKey` - 使用自定义key发送消息
9. `testTextMessageWithMentionedList` - @指定成员（userid）
10. `testTextMessageWithMentionedMobileList` - @指定成员（手机号）
11. `testTextMessageWithMentionAll` - @所有人
12. `testLongTextMessageWithMention` - 长文本消息并@指定成员

## 消息限制

- **文本消息**: 最长2048字节
- **Markdown消息**: 最长4096字节
- **Markdown V2消息**: 最长4096字节
- **图片消息**: 支持JPG、PNG格式，最大10MB
- **图文消息**: 最多8条图文
- **发送频率**: 每分钟不超过20条

## 错误处理

### 常见错误码

- **40014**: Webhook地址无效
- **40015**: 消息内容格式错误
- **40016**: 消息长度超过限制
- **40017**: 接口调用频率限制
- **40018**: 接口频率限制
- **40019**: 机器人不存在
- **40020**: 机器人已禁用

### 错误处理建议

1. 检查Webhook地址是否正确
2. 验证消息格式是否符合要求
3. 控制消息发送频率
4. 检查企业微信应用配置

## 最佳实践

### 消息内容优化

1. **简洁明了**: 控制消息长度，突出重点
2. **格式规范**: 使用Markdown增强可读性
3. **定期发送**: 避免频繁发送相同内容
4. **分类发送**: 按重要性分级发送

### @人员使用建议

1. **精准@**: 只@相关人员，避免打扰无关人员
2. **手机号优先**: 如果不确定userid，可以使用手机号
3. **@all慎用**: 仅在重要通知时使用@所有人

### Webhook管理

1. **统一管理**: 集中管理Webhook地址
2. **权限控制**: 限制Webhook使用权限
3. **监控告警**: 监控Webhook调用状态
4. **备份机制**: 准备备用Webhook地址

## 安全性

- **Webhook保密**: 不要泄露Webhook地址
- **内容验证**: 验证发送的消息内容
- **权限控制**: 限制消息发送权限
- **日志审计**: 记录所有发送记录

## 参考文档

- [企业微信开发文档](https://developer.work.weixin.qq.com/document/path/99110)
- [Webhook发送消息API](https://developer.work.weixin.qq.com/document/path/90236)

## 版本历史

- **1.0.0** (2026-04-25): 初始版本，支持文本、markdown、markdown_v2、图片、图文消息发送，以及超长内容自动分片功能。
- **1.1.0** (2026-04-25): 新增@指定成员功能，支持通过userid或手机号@成员。

## 许可证

本项目采用MIT许可证，详见LICENSE文件。