> ## 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`，必須與連線中的值一致。其他訊息欄位應符合企業微信對應訊息類型的要求。

## 處理結果

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