> ## 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` 欄位，身分驗證由端口使用所選連線提供。

## 處理結果

傳送成功後，輸入訊息標記為成功。配置、範本渲染、上傳或傳送失敗時，輸入訊息標記為錯誤，可在交易日誌中查看原因，並使用端口的重試設定重新處理。