飞书自定义机器人

自定义机器人绑定到一个群聊，适合告警和业务播报。本文依据飞书开放平台资料整理，核验日期为 2026-09-14；未使用真实企业账号执行发送验证。

能力边界

问题	结论
能发到哪里	只能发送到创建它的当前群聊，同一个自定义机器人不能添加到其他群
是否需要租户管理员审核	官方说明添加后即可使用，不需要租户管理员审核；群和租户策略仍可能限制谁能添加
能否读取群消息或用户资料	不能。自定义机器人没有数据访问权限，也不能作为双向对话入口
能否主动选择其他用户或群	不能；需要动态接收目标时使用企业自建应用
是否支持卡片与富文本	支持文本、富文本、群名片和消息卡片等类型，具体结构以官方文档为准
能否用于外部群	官方自定义机器人文档只承诺“当前群聊”能力；外部群是否出现入口受群类型和租户策略影响，不能默认可用

若需求包含接收群成员消息、访问用户身份或在外部群提供机器人服务，应使用带机器人能力的应用，并单独评估应用对外共享范围。

准备条件

1. 已加入目标群，确认该群确实是最终接收通知的群，而不是临时测试群。
2. 当前账号能打开群设置中的群机器人，并能看到添加机器人入口。
3. 租户没有通过安全策略禁用自定义机器人，群管理设置也没有禁止当前成员添加。
4. 已决定使用签名、关键词或 IP 白名单中的至少一种安全限制；生产环境优先签名并叠加稳定出口 IP。
5. 发送端能够通过 HTTPS 访问 open.feishu.cn，服务器时间已同步。
6. 有服务端密钥存储位置，不把 Webhook 或签名 Secret 放到浏览器代码中。

如何判断自己有没有权限

在飞书客户端打开目标群，进入群设置 → 群机器人：

• 能看到“添加机器人”并能选择“自定义机器人”：当前账号具备完成创建的实际权限。
• 能看到机器人列表但没有添加入口：检查自己是否为群主或群管理员，并请租户管理员核对群机器人安全策略。
• 完全看不到“群机器人”：先确认群类型和客户端版本，再让群主或管理员在同一群中检查。
• 创建入口存在但提交被策略拦截：这是租户或群策略限制，不是 Webhook 调用代码问题。

飞书官方没有给出一张适用于所有租户策略的固定角色矩阵，因此应以目标群中的实际入口和管理员策略为最终判断依据。

配置步骤

1. 从群聊添加机器人

1. 在飞书客户端进入目标群，点击右上角更多按钮并打开设置。
2. 进入群机器人 → 添加机器人 → 自定义机器人。
3. 填写头像、名称和描述。名称应能区分环境和用途，例如“生产告警”，不要使用具体密钥信息。
4. 点击添加后复制完整 Webhook URL。该地址只属于当前群，不能拿到其他群复用。

2. 配置安全设置

在机器人详情中配置一种或多种安全方式：

• 自定义关键词：文本中至少包含一个已配置关键词。它适合额外防误发，但不能保护已经泄露的消息内容。
• IP 白名单：只允许稳定的公网出口 IP。填写 NAT、网关或云服务实际出口，不是容器内网 IP。
• 签名校验：请求携带当前时间戳和按官方算法生成的签名。服务器时钟偏差会导致校验失败。

测试阶段也不建议完全关闭安全设置。若需要逐项排查，可先启用关键词完成最小请求，再切换到签名并保留固定测试向量。

3. 保存并验证

1. 将 Webhook 和可选的签名 Secret 写入服务端 Secret 管理。
2. 先发送只包含安全关键词的纯文本消息。
3. 检查 HTTP 状态和响应 JSON 中的 code，成功值为 0。
4. 在目标群确认机器人名称、消息内容和时间均正确。

Web 页面能否完成配置

飞书开发者后台用于创建和发布应用机器人，不能替代群内的自定义机器人添加流程。自定义机器人必须从目标群的客户端设置中创建和管理；官方文档页面只是操作说明，不是配置控制台。

外部群与跨群场景

自定义机器人只能服务创建它的当前群。对于外部群，先在目标群中检查是否存在“自定义机器人”入口；没有入口时不能通过开发者后台或 Webhook API 绕过群类型和租户策略。

需要跨群、外部共享、读取消息或识别用户时，应改用企业自建应用机器人，并在开发者后台配置机器人能力、可用范围和对外共享能力。自定义机器人 Webhook 不能升级成应用机器人凭据。

凭据说明

字段	必需	说明
WEBHOOK_URL	是	创建机器人后生成的完整地址，视为密钥
SIGNING_SECRET	启用签名时	用于按平台规则生成时间戳签名
KEYWORD	启用关键词时	消息正文必须包含配置的关键词

最小请求

JavaScript 示例需要 Node.js 20 或更新版本；Python 示例需要安装 requests。

未启用签名时，可先验证最小文本消息：

curl

curl -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{"msg_type":"text","content":{"text":"通知渠道连通性测试"}}'

JavaScript

const response = await fetch(process.env.WEBHOOK_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    msg_type: 'text',
    content: { text: '通知渠道连通性测试' },
  }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
if (result.code !== 0) throw new Error(JSON.stringify(result));
console.log(result);

Python

import os
import requests

response = requests.post(
    os.environ["WEBHOOK_URL"],
    json={"msg_type": "text", "content": {"text": "通知渠道连通性测试"}},
    timeout=15,
)
response.raise_for_status()
result = response.json()
if result.get("code") != 0:
    raise RuntimeError(result)
print(result)

启用签名后，需要按官方文档生成 timestamp 和 sign 并加入请求体，不能直接复用其他平台的 HMAC 格式。

验证结果

HTTP 成功不等于消息已到达。确认响应中的 code 为 0，并在创建机器人的群聊中看到测试文本。错误码 9499 通常表示请求体格式不正确；11232 表示触发限流。随后再逐项验证富文本或卡片。

消息类型与限制

官方文档当前明确以下限制：

• 单租户、单机器人最多 100 次/分钟、5 次/秒。
• 请求体不能超过 20 KB。
• 整点和半点可能遇到更高系统压力，官方建议避开集中发送；返回 11232 时应降低频率并退避。
• 自定义机器人只在当前群内可用，没有读取群消息或用户数据的权限。

告警风暴时应先在业务侧聚合重复事件，不能依靠循环重试突破限流。卡片或富文本失败时回退到纯文本，确认是内容结构问题还是权限与凭据问题。

安全建议

• Webhook 和签名密钥只保存在服务器端。
• 签名、关键词和 IP 白名单可以叠加；它们不替代 Webhook 本身的保密。
• 日志中只记录脱敏后的机器人标识和平台请求 ID。
• 泄露后在群设置中删除或重新创建机器人，并替换发送端密钥。
• 对 11232 和临时服务错误做有限退避；参数和安全校验错误不自动重试。

常见问题

提示关键词不匹配：测试文本需要包含机器人安全设置中的关键词。

签名校验失败：检查服务器时间、时间戳单位、待签名字符串和 Base64 编码步骤。

请求成功但群里没有消息：确认机器人仍在目标群中，且请求发送到当前有效的 Webhook。

找不到 Web 管理地址：自定义机器人没有独立 Web 控制台，必须在目标群客户端内创建。开发者后台管理的是应用机器人。

外部群没有添加入口：不能从开发者后台绕过。评估具备对外共享能力的应用机器人，或改用该群允许的通知方式。

返回 11232：已触发机器人限流。聚合重复消息，按延迟退避，不要立即并发重试。

官方资料

• 飞书开放平台：在群组中添加自定义机器人
• 飞书开放平台：机器人能力对比