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

# 釘釘端口

> 透過釘釘群組自訂機器人的 Webhook 傳送文字、Markdown 和自訂 JSON 訊息，支援 ArcScript 範本與 @提醒。

釘釘端口透過自訂機器人向釘釘群組傳送訊息，可用於業務通知。端口屬於 **MFT** 類型，Webhook 位址和機器人安全設定直接儲存在端口中，無需建立共用連線。

## 核心功能

* 支援直接傳送文字、使用 ArcScript 範本產生文字或 Markdown，以及傳送原始 JSON 請求。
* 支援機器人加簽和自訂關鍵字驗證。
* 支援透過手機號碼、使用者 ID 提醒群組成員，或 @所有人。

## 新增機器人並取得 Webhook 位址

開始前，需要能夠管理目標釘釘群組中的機器人。以下以 PC 版釘釘為例：

1. 開啟目標群組，進入右上角的**群組設定 → 智慧群組助手 → 新增機器人**。
2. 在機器人清單中選擇**自訂**，按一下**新增**，填寫機器人名稱和頭像。
3. 配置機器人的安全設定，至少選擇一種。使用**自訂關鍵字**時，例如設定為 `業務通知`，並將同樣的值填入端口的**自訂關鍵字**。
4. 如啟用**加簽**，複製機器人的加簽密鑰，填入端口的**加簽密鑰**；未啟用加簽時留空。
5. 依提示完成新增，複製產生的完整 Webhook URL，填入端口的**Webhook 位址**。

新增操作和位址取得位置可參考[阿里雲官方 Webhook 取得指南](https://help.aliyun.com/zh/ahas/support/how-to-obtain-the-webhook-url-of-a-custom-chatbot)，安全選項可參考[釘釘官方自訂機器人安全設定](https://open.dingtalk.com/document/robots/customize-robot-security-settings)。如果啟用 IP 白名單，應允許執行端口的伺服器或代理存取公網時使用的出口 IP。

Webhook 位址通常如下，需替換為機器人實際產生的位址：

```text theme={null}
https://oapi.dingtalk.com/robot/send?access_token=YOUR_ACCESS_TOKEN
```

## 端口配置

### 設定索引標籤

| 設定                          | 說明                                                                                                                               |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Webhook 位址（Webhook URL）** | 自訂機器人的完整 HTTPS 位址，必須包含非空的 `access_token` 查詢參數。必填。                                                                                |
| **加簽密鑰（Secret）**            | 機器人啟用加簽時填寫。端口自動產生時間戳記和簽章，無需手動加入 Webhook 位址。未啟用時留空。                                                                               |
| **自訂關鍵字（Keyword）**          | 機器人使用關鍵字驗證時填寫。文字和範本模式下，若內容及 Markdown 標題未包含關鍵字，會將關鍵字自動加到內容前方。原始 JSON 模式要求輸入自行包含關鍵字。未啟用時留空。                                        |
| **傳送測試訊息**                  | 向目標群組傳送一條真實的測試訊息，用於檢查 Webhook 和安全設定，群組成員可見。                                                                                      |
| **傳送模式（Send Mode）**         | 選擇文字（`Text`）、範本（`Template`）或原始 JSON（`RawJSON`）。預設為文字。                                                                            |
| **訊息格式（Message Format）**    | 範本模式下使用，選擇 `Text` 或 `Markdown`。預設為 `Text`。                                                                                       |
| **訊息標題（Message Title）**     | Markdown 範本模式下必填，用於會話清單和通知中的標題。                                                                                                  |
| **訊息範本（Message Template）**  | 範本模式下必填，用於產生傳送內容，支援 ArcScript 和宏。                                                                                                |
| **@手機號碼**                   | 需要提醒的群組成員手機號碼，多個值用分號分隔。若需在正文中內嵌顯示 @，正文也需包含對應的 `@手機號碼` 文字。                                                                        |
| **@使用者 ID**                 | 需要提醒的釘釘使用者 ID，多個值用分號分隔。                                                                                                          |
| **@所有人**                    | 啟用後提醒群組內所有成員。預設關閉。                                                                                                               |
| **允許訊息頭覆蓋**                 | 預設關閉。啟用後，`DingTalk-AtMobiles`、`DingTalk-AtUserIds` 和 `DingTalk-AtAll` 訊息頭可分別覆蓋 @手機號碼、@使用者 ID 和 @所有人。訊息頭不能覆蓋 Webhook 位址、加簽密鑰或關鍵字。 |

### 進階索引標籤

| 設定              | 說明                              |
| --------------- | ------------------------------- |
| **逾時（Timeout）** | 每次釘釘 API 請求的逾時時間，單位為秒，預設為 `60`。 |

## 使用方式

### 傳送文字

1. 填寫 Webhook 位址及對應的安全設定，按一下**傳送測試訊息**檢查配置。
2. 將傳送模式設為**文字**，依需要配置 @提醒。
3. 將 UTF-8 文字訊息傳入端口，啟用自動化中的**傳送**以自動處理。

文字模式直接傳送輸入內容，不進行範本渲染。內容不能為空；端口按 UTF-8 位元組數檢查長度，文字和 Markdown 內容上限均為 `20000` 位元組，自動新增的關鍵字也計入長度。

### 使用 ArcScript 範本

將傳送模式設為**範本**，選擇訊息格式並填寫**訊息範本**。範本支援 ArcScript，可以讀取目前訊息內容和訊息頭，也支援宏。例如，選擇 `Markdown`，將**訊息標題**設為 `檔案處理完成`，範本可填寫：

```xml theme={null}
<arc:set attr="notice.filename" value="[_message.header:filename]" />
## 檔案處理完成
檔案名稱： [notice.filename]
```

每條輸入訊息都會觸發範本渲染，端口將渲染結果按所選格式傳送。結果不能為空，並受相同的內容長度限制。此範例讀取目前訊息的檔案名稱，ArcScript 語法和用法可參閱[ArcScript 入門](../scripting/introduction-to-arcscript)。

### 傳送原始 JSON

將傳送模式設為**原始 JSON**，輸入必須是包含 `msgtype` 的完整機器人請求 JSON 物件。例如，機器人配置了關鍵字 `業務通知` 時，可以使用：

```json theme={null}
{
  "msgtype": "text",
  "text": {
    "content": "業務通知：訂單處理完成。"
  },
  "at": {
    "isAtAll": false
  }
}
```

此模式直接傳送輸入 JSON，不渲染範本，並忽略端口的訊息格式、標題和 @提醒設定及對應訊息頭。若需 @成員或所有人，應在輸入中設定 `at` 物件。

端口仍使用配置的 Webhook 位址和加簽密鑰。若配置了自訂關鍵字，輸入訊息本文必須自行包含該關鍵字，否則會在傳送前報錯。`link`、`actionCard` 和 `feedCard` 等訊息類型也可透過此模式傳送，具體結構可參考[釘釘官方自訂機器人接入文件](https://open.dingtalk.com/document/robots/custom-robot-access)。

## 處理結果

傳送成功後，輸入訊息標記為成功。配置、範本渲染或傳送失敗時，輸入訊息標記為錯誤，可在交易日誌中查看原因，並使用端口的重試設定重新處理。安全驗證失敗時，應檢查關鍵字、加簽密鑰和 IP 白名單。