> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 企业微信端口

> 通过企业微信自建应用发送文本、Markdown、文件和自定义 JSON 消息。

WeCom 端口通过企业微信自建应用向成员、部门或标签发送消息，可用于业务通知和文件交付。

## 核心功能

* 支持直接发送文本、使用模板生成文本或 Markdown、发送文件，以及发送原始 JSON 请求。
* 多个端口可以共用同一个企业微信连接，并分别配置接收人和发送模式。
* 自动获取和缓存访问令牌；令牌失效时刷新并重试一次。

## 创建自建应用并获取凭据

开始前，需要有企业微信企业账号，并具备管理后台的应用管理权限。已有自建应用时，可直接使用其凭据。

1. 使用管理员账号登录[企业微信管理后台](https://work.weixin.qq.com/wework_admin/loginpage_wx)。
2. 进入**应用管理 → 自建 → 创建应用**，填写应用名称、Logo 和说明，并设置可见范围。
3. 打开创建好的应用详情页，复制 **AgentId**，填入端口连接的**应用 ID**。
4. 在同一应用详情页找到 **Secret**，单击**查看**，按提示在企业微信客户端完成管理员确认并获取密钥，填入连接的**应用密钥**。
5. 进入**我的企业 → 企业信息**，复制**企业 ID**，填入连接的**企业 ID**。

以上操作可参考[腾讯官方指南中的应用创建和凭据查询步骤](https://identity.tencent.com/docs/guides/SyncConfig/wecom/)。企业 ID、应用 ID 和应用密钥应来自同一企业及所选自建应用。

在应用详情页的**开发者接口 → 企业可信 IP**中，按后台要求配置运行端口的服务器访问公网时使用的出口 IP；通过代理访问时填写代理的出口 IP。相关后台操作可参阅[腾讯官方配置指南](https://identity.tencent.com/docs/guides/IDPconfig/workspace/wecom/)。

自建应用的可见范围应包含消息接收成员。消息发送权限和参数要求可参阅企业微信官方[发送应用消息](https://developer.work.weixin.qq.com/document/path/90236)文档。

## 端口配置

### 连接

在**设置**选项卡中选择或创建企业微信连接。以下凭据保存在连接中。

| 设置                  | 说明                         |
| ------------------- | -------------------------- |
| **企业 ID（Corp ID）**  | 企业微信的企业 ID。必填。             |
| **应用 ID（Agent ID）** | 用于发送消息的自建应用 ID，必须为非负整数。必填。 |
| **应用密钥（Secret）**    | 自建应用的密钥。必填。                |

单击**测试连接**可检查凭据是否能够获取访问令牌。测试不会发送消息，也不验证接收人是否能收到消息。

### 设置选项卡

| 设置                                         | 说明                                                                                           |
| ------------------------------------------ | -------------------------------------------------------------------------------------------- |
| **接收人类型（Recipient Type）**                  | 选择成员（`User`）、部门（`Department`）或标签（`Tag`）。默认为成员，每条消息使用一种接收人类型。                                 |
| **接收人（Recipient）**                         | 对应类型的 ID，多个 ID 用分号分隔，例如 `user001;user002`。原始 JSON 模式不使用此设置。                                  |
| **允许消息头覆盖（Allow Message Header Override）** | 默认关闭。启用后，可通过 `WeCom-Recipient` 和 `WeCom-RecipientType` 消息头覆盖接收人及其类型。连接凭据和 Agent ID 始终来自所选连接。 |
| **发送模式（Send Mode）**                        | 选择文本（`Text`）、模板（`Template`）、文件（`File`）或原始 JSON（`RawJSON`）。默认为文本。                             |
| **消息格式（Message Format）**                   | 模板模式下使用，选择 `Text` 或 `Markdown`。默认为 `Text`。                                                   |
| **消息模板（Message Template）**                 | 模板模式下必填，用于生成消息内容，支持 ArcScript 和宏。                                                            |
| **发送附带消息（Send Accompanying Message）**      | 文件模式下使用，默认关闭。启用后，在文件发送成功后再发送一条文本或 Markdown 消息。                                               |
| **附带消息格式（Accompanying Message Format）**    | 启用附带消息后显示，选择 `Text` 或 `Markdown`。默认为 `Text`。                                                 |
| **附带消息模板（Accompanying Message Template）**  | 启用附带消息后必填，支持 ArcScript 和宏。                                                                   |

### 高级选项卡

| 设置              | 说明                                |
| --------------- | --------------------------------- |
| **超时（Timeout）** | 每次企业微信 API 请求的超时时间，单位为秒，默认为 `60`。 |

## 使用方式

### 发送文本

1. 选择企业微信连接并测试连接。
2. 将接收人类型设为 `User`，填写成员 ID，例如 `user001`。
3. 将发送模式设为 `Text`，将 UTF-8 文本消息传入端口。
4. 启用自动化中的**发送**，自动处理到达端口的消息。

文本模式将输入内容直接作为文本发送，不进行模板渲染。内容不能为空，端口按 UTF-8 字节数检查长度，文本最多为 `2048` 字节。

### 使用模板

将发送模式设为 `Template`，选择消息格式并填写模板。例如，选择 `Markdown` 后可使用：

```text theme={null}
## 文件处理完成
文件名：%Filename%
```

每条输入消息都会触发模板渲染。模板模式发送渲染后的内容，渲染结果不能为空；文本最多为 `2048` 字节，Markdown 最多为 `4096` 字节。

### 发送文件

将发送模式设为 `File`，输入消息必须带有文件名。端口先上传文件，再使用返回的媒体 ID 发送文件消息；文件大小必须在 `5` 字节至 `20 MiB` 之间。

如需附带说明，启用**发送附带消息**并填写模板。文件和说明分别发送；如果文件已发送而说明失败，重试该输入消息会再次发送文件。

### 发送原始 JSON

将发送模式设为**原始 JSON**，输入消息应为企业微信消息请求的 JSON 对象，例如：

```json theme={null}
{
  "touser": "user001|user002",
  "msgtype": "text",
  "text": {
    "content": "订单处理完成。"
  }
}
```

请求必须包含 `msgtype`，以及 `touser`、`toparty`、`totag` 中至少一个接收人字段。此模式按原始 JSON 发送，忽略端口的接收人、头覆盖和消息格式设置。

端口会自动补充所选连接的 `agentid` 并提供身份验证。输入不得包含 `access_token`；如果填写了 `agentid`，必须与连接中的值一致。其他消息字段应符合企业微信对应消息类型的要求。

## 处理结果

发送成功后，输入消息标记为成功。配置、上传或发送失败时，输入消息标记为错误，可在交易日志中查看原因，并使用端口的重试设置重新处理。