飞书开放平台避坑指南：获取User ID、群ID的三种方法及常见权限错误排查

飞书开发者实战手册：精准获取用户与群组ID的三大路径与高频错误解析

刚接触飞书开放平台的开发者们，是否经常被各种ID类型绕晕？User ID、Open ID、Union ID究竟该用哪个？群组消息发送失败时，那个神秘的错误码"11203"又意味着什么？这些问题看似基础，却直接影响着通知推送、成员管理等核心功能的实现效率。本文将用真实项目经验，拆解飞书ID体系的核心逻辑，并分享三种高效获取ID的实战方法，同时针对"99992402"、"11203"等典型错误提供即查即用的解决方案。

1. 飞书ID体系深度解析：User ID、Open ID与Union ID的适用场景

飞书的身份识别体系采用三层结构设计，每种ID都有其特定的使用场景和获取方式。理解这些差异是避免后续开发踩坑的关键。

核心ID类型对比表：

提示：当需要实现跨应用的用户数据打通时（如CRM系统与OA系统的数据关联），优先使用Union ID而非Open ID。

获取这些ID的典型方式包括：

• 管理后台导出：适用于批量获取组织成员信息
• API接口查询：适合动态获取实时数据
• 事件回调解析：用于即时响应用户操作

我曾在一个项目中使用Open ID作为用户标识，结果当该用户访问另一个关联应用时，系统无法识别其身份。后来改用Union ID才解决这个问题——这也是为什么理解ID差异如此重要。

2. 三种核心方法获取用户与群组ID的实操指南

2.1 管理后台可视化获取：适合初期调试与小型团队

对于成员数量较少（建议50人以内）的团队，通过飞书管理后台获取ID是最直观的方式：

1. 登录飞书管理后台（https://www.feishu.cn/admin/）
2. 进入「组织架构」-「成员与部门」模块
3. 点击目标用户右侧的「查看详情」按钮
4. 在详情页的URL中即可看到类似user_id=5d3a8e9的参数值

优点：

• 无需编程基础
• 可直接验证ID准确性
• 适合快速测试场景

局限：

• 无法批量导出大规模成员数据
• 需要管理员权限
• 不适用于自动化流程

2.2 API接口调用：推荐用于生产环境的稳定方案

飞书提供了完善的API体系获取用户和群组信息。以下是获取用户列表的典型代码示例：

import requests def get_user_list(app_id, app_secret): # 1. 获取access_token token_url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" token_data = { "app_id": app_id, "app_secret": app_secret } token_resp = requests.post(token_url, json=token_data).json() access_token = token_resp['tenant_access_token'] # 2. 获取用户列表 user_url = "https://open.feishu.cn/open-apis/contact/v3/users" headers = { "Authorization": f"Bearer {access_token}", "Content-Type": "application/json" } user_resp = requests.get(user_url, headers=headers).json() return user_resp['data']['users']

关键参数说明：

• app_id和app_secret：在飞书开放平台创建应用时获得
• tenant_access_token：访问大多数API必需的凭证，有效期2小时
• 分页处理：当用户量较大时，需处理page_token参数实现分页查询

2.3 机器人事件回调：实时获取最新ID的动态方式

当用户与机器人交互时（如@机器人、点击卡片按钮），飞书服务器会向配置的回调地址推送事件消息，其中包含相关用户的ID信息。典型的事件回调数据结构如下：

{ "event": { "sender": { "sender_id": { "open_id": "ou_123456", "user_id": "5d3a8e9", "union_id": "on_abcd" } }, "message": { "chat_id": "oc_123456" // 群聊ID } } }

配置回调服务的核心步骤：

1. 在应用管理后台启用「事件订阅」
2. 配置请求验证（Encrypt Key）
3. 实现服务器端点处理飞书的验证请求
4. 部署服务并验证连通性

注意：回调地址必须支持HTTPS协议，且端口为443。开发测试阶段可使用ngrok等工具实现本地服务的外网暴露。

3. 高频权限错误排查手册：从"11203"到"99992402"的解决方案

3.1 "11203"错误：批量消息权限缺失的完整修复流程

当看到send message error, code = 11203, msg = send user_ids permission denied错误时，表明应用缺少批量发送消息的权限。解决步骤：

1. 登录飞书开放平台（https://open.feishu.cn/app）
2. 进入目标应用的「权限管理」页面
3. 在「权限配置」中添加「批量发送消息」权限
4. 提交申请并等待管理员审批（通常需要1-2工作日）
5. 审批通过后，在「版本管理与发布」中创建新版本并发布

常见误区：

• 仅添加权限但未发布新版本
• 使用User ID发送但未申请「以应用身份发送消息」权限
• 未等待权限审批完成就进行测试

3.2 "99992402"错误：群组信息获取权限的配置要点

错误码99992402通常伴随No permission to access chat提示，表明机器人无权访问目标群组信息。解决方案包括：

方法一：通过管理后台授权

1. 让群管理员进入群设置
2. 选择「机器人管理」
3. 添加目标机器人并勾选「获取群组信息」权限

方法二：通过API申请权限

curl -X POST \ https://open.feishu.cn/open-apis/chat/v4/add_member \ -H "Authorization: Bearer {access_token}" \ -d '{ "chat_id": "{group_id}", "member_id_type": "app_id", "member_id": "{your_app_id}" }'

3.3 其他常见错误速查表

4. 进阶实战：构建飞书消息通知系统的最佳实践

4.1 用户ID映射表的维护策略

在企业应用中，通常需要将飞书ID与内部系统用户关联。推荐两种方案：

方案A：定时同步全量数据

# 每天凌晨同步全量用户数据 def sync_users(): users = get_user_list(app_id, app_secret) for user in users: db.update_or_create( union_id=user['union_id'], defaults={ 'user_id': user['user_id'], 'name': user['name'], 'department': user['department_ids'][0] } )

方案B：事件驱动增量更新

• 监听user_add、user_update等组织架构变更事件
• 仅处理发生变化的用户数据
• 结合消息队列保证处理可靠性

4.2 群组消息发送的性能优化

当需要向大量群组发送通知时（如部门周报），需注意：

1. 异步处理：将消息发送任务放入队列，避免阻塞主流程
2. 频率控制：单个应用每分钟最多发送50条消息
3. 缓存群组ID：对静态群组ID进行本地缓存，减少API调用

# 使用celery实现异步发送 @app.task def async_send_group_message(chat_id, content): try: resp = feishu_api.send_message(chat_id, content) return resp['message_id'] except Exception as e: log_error(f"Send failed: {chat_id}, {str(e)}") raise self.retry(exc=e)

4.3 敏感操作的双重验证机制

对于重要通知（如薪资发放提醒），建议实现：

1. 消息发送前在内部系统留存记录
2. 通过飞书消息卡片获取用户确认
3. 记录消息阅读状态和用户反馈

// 消息卡片交互示例 { "config": {"wide_screen_mode": true}, "elements": [{ "tag": "action", "actions": [{ "tag": "button", "text": "确认收到", "type": "primary", "value": "confirm" }] }] }

在实际项目中，我曾遇到因未做消息确认导致的重要通知遗漏。后来引入这套机制后，关键信息的到达率从78%提升到了99%。