> ## 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 白名单。