> ## 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.

# 飞书端口

> 通过飞书或 Lark 自建应用发送文本、文件、图片和自定义 JSON 消息，支持 ArcScript 模板。

飞书端口通过企业自建应用的机器人发送消息，可用于业务通知和文件交付。端口属于 **MFT** 类型，同时支持飞书和 Lark。

## 核心功能

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

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

开始前，需要有飞书企业账号，并具备创建企业自建应用的权限。已有可用应用时，可直接使用其凭据。

1. 登录[飞书开发者后台](https://open.feishu.cn/app)，单击**创建企业自建应用**，填写应用名称、说明和图标。
2. 打开应用的**凭证与基础信息**页面，复制 **App ID** 和 **App Secret**，分别填入端口连接的同名字段。凭据获取位置可参考[飞书官方配置说明](https://www.feishu.cn/content/817244137021)。
3. 在**添加应用能力**中添加并启用**机器人**。
4. 在**权限管理**中开通**以应用的身份发消息**（`im:message:send_as_bot`）权限。如需发送文件或图片，也按[上传文件](https://open.feishu.cn/document/server-docs/im-v1/file/create)和[上传图片](https://open.feishu.cn/document/server-docs/im-v1/image/create)接口文档开通所需权限。
5. 在**版本管理与发布**中创建版本，设置应用可用范围并提交发布，按企业要求完成管理员审核。机器人能力、发送权限和发布操作可参考[飞书官网的机器人配置步骤](https://www.feishu.cn/content/article/7602952057348902079)。

给成员发送消息时，成员需要在机器人的可用范围内；给群组发送消息时，应先将机器人加入目标群组，并确保其具有发言权限。具体要求可参考[飞书官方发送消息说明](https://www.feishu.cn/content/mtb6n3ah)。

使用 Lark 时，在 [Lark 开发者后台](https://open.larksuite.com/app)创建应用，并将端口连接的**域名**设为 `Lark`。完整流程可参阅开放平台的[自建应用开发流程](https://open.feishu.cn/document/home/introduction-to-custom-app-development/self-built-application-development-process)。

## 端口配置

### 连接

在**设置**选项卡中选择或创建连接。以下设置保存在连接中。

| 设置             | 说明                                                                                 |
| -------------- | ---------------------------------------------------------------------------------- |
| **App ID**     | 自建应用的 App ID。必填。                                                                   |
| **App Secret** | 同一应用的密钥。必填，端口不会从输入消息或消息头读取此值。                                                      |
| **域名（Domain）** | 选择应用注册的平台：飞书（`FeiShu`）或 `Lark`。默认为飞书，分别使用 `open.feishu.cn` 和 `open.larksuite.com`。 |

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

### 设置选项卡

| 设置                                         | 说明                                                                                                                |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **接收人类型（Recipient Type）**                  | 选择 Open ID（`OpenID`）、User ID（`UserID`）、Union ID（`UnionID`）、邮箱（`Email`）或群 ID（`ChatID`）。默认为 Open ID，原始 JSON 模式下也生效。 |
| **接收人（Recipient）**                         | 与所选类型对应的单个 ID 或邮箱地址。不接受多个接收人的列表，原始 JSON 模式不使用此设置。                                                                 |
| **允许消息头覆盖（Allow Message Header Override）** | 默认关闭。启用后，`FeiShu-Recipient` 和 `FeiShu-RecipientType` 消息头可分别覆盖接收人和类型。连接、App ID、App Secret 和域名始终来自所选连接。             |
| **发送模式（Send Mode）**                        | 选择文本（`Text`）、模板（`Template`）、文件（`File`）或原始 JSON（`RawJSON`）。默认为文本。                                                  |
| **消息模板（Message Template）**                 | 模板模式下必填，用于生成发送的文本内容，支持 ArcScript 和宏。                                                                              |
| **发送附带消息（Send Accompanying Message）**      | 文件模式下使用，默认关闭。启用后，在文件或图片发送成功后再发送一条文本消息。                                                                            |
| **附带消息模板（Accompanying Message Template）**  | 启用附带消息后必填，用于生成附带文本，支持 ArcScript 和宏。                                                                               |

### 高级选项卡

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

## 使用方式

### 发送文本

1. 选择连接并测试连接。
2. 设置接收人类型和接收人，例如选择**邮箱**并填写成员的飞书邮箱。
3. 将发送模式设为**文本**，传入 UTF-8 文本消息。
4. 启用自动化中的**发送**，自动处理到达端口的消息。

文本模式直接发送输入内容，不进行模板渲染。内容不能为空；端口按 UTF-8 字节数检查文本长度，上限为 `150 KiB`，完整请求还需符合飞书接口的大小要求。

### 使用 ArcScript 模板

将发送模式设为**模板**，在**消息模板**中填写文字、ArcScript 表达式或脚本。模板可以访问当前消息内容和消息头，也支持宏。例如：

```xml theme={null}
<arc:set attr="notice.filename" value="[_message.header:filename]" />
文件处理完成： [notice.filename]
```

此示例读取当前消息的文件名并生成通知文本。每条输入消息都会触发模板渲染，端口将渲染结果作为文本消息发送；结果不能为空，并受相同的文本长度限制。附带消息模板也可以使用 ArcScript。语法和用法可参阅[ArcScript 入门](../scripting/introduction-to-arcscript)。

模板模式输出普通文本。如需富文本或消息卡片，可使用原始 JSON 模式提供相应消息类型的请求。

### 发送文件或图片

将发送模式设为**文件**，输入消息必须带有文件名且内容不能为空。端口根据文件扩展名识别图片，例如 `.jpg`、`.png`、`.gif`，上传后发送图片消息；其他文件上传后发送文件消息。端口检查的上传大小上限为：文件 `30 MiB`，图片 `10 MiB`；格式等要求以对应上传接口为准。

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

### 发送原始 JSON

将发送模式设为**原始 JSON**，输入必须是完整的消息请求 JSON 对象。以下示例发送群消息，需将**接收人类型**设为**群 ID**，并替换为实际群 ID：

```json theme={null}
{
  "receive_id": "oc_example_chat_id",
  "msg_type": "text",
  "content": "{\"text\":\"订单处理完成。\"}"
}
```

请求必须包含 `receive_id`、`msg_type` 和 `content`。其中 `content` 为序列化后的消息内容 JSON 字符串，具体结构可参阅[飞书官方发送消息接口](https://open.feishu.cn/document/server-docs/im-v1/message/create)。

此模式直接发送输入 JSON，不渲染模板，也不使用端口的**接收人**或 `FeiShu-Recipient` 消息头。**接收人类型**仍然生效；启用消息头覆盖后，也可通过 `FeiShu-RecipientType` 指定类型。端口将其作为查询参数 `receive_id_type` 发送。

输入不得包含 `receive_id_type`、`tenant_access_token`、`app_id` 或 `app_secret` 字段，身份验证由端口使用所选连接提供。

## 处理结果

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