飞书企业自建应用消息

企业自建应用适合面向指定用户或群聊发送消息，需要管理员控制应用权限与可用范围。本文依据飞书开放平台资料整理，核验日期为 2026-09-14；未执行真实租户发送验证。

能力边界

问题	结论
能发给谁	可按 open_id、union_id、user_id、邮箱或 chat_id 指定用户和群聊
给用户发送的前提	用户在机器人可用范围内，且没有被租户侧禁用
给群发送的前提	应用已启用机器人能力，机器人在群中并拥有发言权限
自定义机器人能否调用	不能，发送消息 API 只支持开发者后台创建的应用机器人
能否发送到外部群	需要应用具备对外共享能力并满足外部群规则，不能默认所有自建应用都可发送
是否支持接收消息	本页只讲主动发送；接收和回复使用对话机器人

应用 API 不是“任意群广播”。可用范围、机器人入群状态、群发言权限和租户沟通策略都会影响最终投递。

准备条件

1. 能登录飞书开发者后台，并在目标企业下创建或维护企业自建应用。
2. 有应用版本发布权限；需要审批的消息权限能由租户管理员完成审批。
3. 已准备一个测试用户和测试群，可用范围只需先覆盖这些测试对象。
4. 明确接收标识类型，例如 open_id、user_id 或 chat_id，并知道它们不能跨应用或跨租户随意复用。
5. 发送群消息时，应用机器人已经加入目标群并有发言权限。
6. 服务端能安全保存 App Secret、缓存 tenant_access_token，并能访问 open.feishu.cn。

如何判断自己有没有应用管理权限

登录开发者后台并选择目标企业：

• 能创建企业自建应用：具备创建权限。
• 能进入应用并修改权限、机器人能力、可用范围和版本：具备主要开发配置权限。
• 能创建版本但发布或申请权限时需要审批：需要租户管理员完成审批，这是正常的权限分工。
• 只能查看应用或无法选择目标企业：当前账号不是该应用的管理员或开发成员，应由应用负责人邀请。

能够管理某个群不等于能够管理企业自建应用；群主权限和应用开发权限是两套权限。

配置步骤

1. 创建应用并启用机器人能力

1. 打开飞书开发者后台，选择目标企业并创建企业自建应用。
2. 在应用详情的凭证与基础信息中记录 App ID；按页面安全流程取得 App Secret。
3. 在添加应用能力中启用机器人。没有机器人能力时，消息接口会返回相关业务错误。
4. 设置机器人名称、头像和说明，避免测试与生产应用使用相同展示名称。

2. 申请消息权限

在权限管理中申请最小发送权限。官方发送接口当前允许使用 im:message、im:message:send_as_bot 或历史权限 im:message:send 中符合调用身份的一项；实际名称和审批要求以控制台为准。

如果使用 user_id，还需要相应用户 ID 字段权限。只使用 open_id 时不要额外申请通讯录敏感权限。

3. 配置可用范围并发布

1. 首次联调只把测试用户加入可用范围。
2. 创建应用版本，检查机器人能力、权限和可用范围都包含在待发布版本中。
3. 提交发布；需要管理员审批时等待审批完成。
4. 权限或可用范围变更后重新发布版本。只在控制台保存不一定会对用户生效。

4. 准备接收目标

• 给用户发送时，官方推荐优先使用该应用下的 open_id。
• 使用 user_id、union_id 或邮箱时，查询参数 receive_id_type 必须一致。
• 给群发送时使用 chat_id，并先把应用机器人加入群、确认没有被禁言。
• 不要把显示名或群名称当成稳定 ID。

5. 获取并缓存租户令牌

使用 App ID 与 App Secret 调用内部应用 Token 接口。检查 HTTP 状态和响应 code，按 expire 或官方返回的有效期缓存。缓存键至少包含应用和租户，不同应用不能共用令牌。

只在明确的令牌失效错误下刷新并重试一次；权限不足、目标无效和机器人不在群中不能靠刷新解决。

6. 发送最小消息

调用发送消息接口，查询参数和 receive_id 类型保持一致。文本内容需要先序列化为 JSON 字符串。先向一个测试用户发送，再测试群聊和卡片。

凭据说明

字段	必需	说明
APP_ID	是	企业自建应用标识
APP_SECRET	是	获取租户访问令牌的敏感凭据
TENANT_ACCESS_TOKEN	是	有有效期，发送端应缓存并提前刷新
RECEIVE_ID	是	接收用户或群聊标识，必须与查询参数类型一致

APP_SECRET 是长期密钥，TENANT_ACCESS_TOKEN 是短期服务端令牌。二者都不能返回给浏览器。不同应用下同一用户的 open_id 可能不同；跨应用关联用户时必须理解 union_id 和 user_id 的授权边界。

最小请求

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

先获取访问令牌，再发送文本消息：

curl

curl -X POST 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' \
  -H 'Content-Type: application/json' \
  -d '{"app_id":"APP_ID","app_secret":"APP_SECRET"}'

curl -X POST 'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id' \
  -H 'Authorization: Bearer TENANT_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"receive_id":"OPEN_ID","msg_type":"text","content":"{\"text\":\"通知渠道连通性测试\"}"}'

JavaScript

const tokenResponse = await fetch(
  'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      app_id: process.env.APP_ID,
      app_secret: process.env.APP_SECRET,
    }),
  },
);
const tokenResult = await tokenResponse.json();
if (!tokenResponse.ok || tokenResult.code !== 0) throw new Error(JSON.stringify(tokenResult));

const response = await fetch(
  'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${tokenResult.tenant_access_token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      receive_id: process.env.OPEN_ID,
      msg_type: 'text',
      content: JSON.stringify({ text: '通知渠道连通性测试' }),
    }),
  },
);
const result = await response.json();
if (!response.ok || result.code !== 0) throw new Error(JSON.stringify(result));
console.log(result);

Python

import os
import requests

token_response = requests.post(
    "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
    json={"app_id": os.environ["APP_ID"], "app_secret": os.environ["APP_SECRET"]},
    timeout=15,
)
token_response.raise_for_status()
token_result = token_response.json()
if token_result.get("code") != 0:
    raise RuntimeError(token_result)

response = requests.post(
    "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id",
    headers={"Authorization": f"Bearer {token_result['tenant_access_token']}"},
    json={
        "receive_id": os.environ["OPEN_ID"],
        "msg_type": "text",
        "content": '{"text":"通知渠道连通性测试"}',
    },
    timeout=15,
)
response.raise_for_status()
result = response.json()
if result.get("code") != 0:
    raise RuntimeError(result)
print(result)

验证结果

检查 HTTP 状态、飞书业务码 code=0 和返回的 message_id，并由目标用户确认收到消息。若使用 chat_id，还需确认应用机器人已经在群中并有发言权限。

建议保存响应头中的平台请求标识和响应消息 ID，用于平台侧排查。日志只记录脱敏 ID，不记录 Token 和消息正文。

消息类型、幂等与限制

• 官方发送接口支持文本、富文本、卡片、图片、视频、音频、文件等类型；图片和文件需要先使用对应素材接口上传。
• 向同一用户发送限频为 5 QPS；向同一群组发送为群内机器人共享 5 QPS。接口本身另有平台级频率限制。
• 文本消息请求体最大 150 KB，卡片和富文本最大 30 KB。
• 可选 uuid 最长 50 字符；同一 uuid 在 1 小时内至多成功发送一条，适合发送重试幂等。
• 批量通知应在业务侧分流和限速，不能通过多个 Token 绕过用户或群级限制。

常见业务错误

业务码	含义与处理
230002	机器人不在目标群，将应用机器人加入群后重试
230006	未启用机器人能力，启用并重新发布应用
230013	用户不在可用范围、被禁用或已离职，核对范围并发布
230018	群设置禁止当前操作，例如机器人没有发言权限
230020	触发频率限制，按平台规则退避并聚合消息
230027	缺少必要权限，核对 Scope、审批、调用身份和版本

业务码和处理规则可能更新，排查时以发送消息官方页面当前错误码表为准。

安全建议

• App Secret 不能发送到前端；访问令牌只在服务器端缓存。
• 只申请发送消息需要的权限，并限制应用可用范围。
• 不在日志中记录完整 Token、Secret 或消息中的敏感业务数据。
• 使用 uuid 或业务幂等键保护超时重试，避免重复通知。
• 大范围发布前先审查接收者、数据分类和跨租户边界。

常见问题

权限不足：检查权限是否已申请、版本是否已发布、管理员是否已授权。

接收人无效：确认 receive_id_type 与 RECEIVE_ID 的实际类型一致。

访问令牌失效：按返回的有效期缓存和刷新，不要永久保存单次令牌。

用户在企业中但返回 230013：检查应用版本的可用范围、租户管理后台的禁用成员，以及用户是否离职；修改后重新发布。

群消息返回 230002 或 230018：确认应用机器人在该群中，并且群设置允许机器人发言。

相同通知发送了两次：为一次业务投递生成稳定 uuid，在超时重试时复用；新内容必须使用新值。

官方资料

• 飞书开放平台：发送消息
• 飞书开放平台：获取 tenant_access_token
• 飞书开放平台：配置应用可用范围
• 飞书开放平台：如何启用机器人能力