飞书机器人通知
介绍
游戏打包完成后,群里需要一条消息:成功还是失败、版本号、提交、耗时、下载地址。测试同学最好能直接扫码安装;失败时还要把日志带上。GM 工具也一样:真机上点一下,把当前日志或截图发到群里,比插线、导日志快得多。
这套东西在企业微信里用一个群机器人 webhook 就能做。2022 年我写过微信群机器人发送二维码和微信群机器人发送 Unity 日志,前者把下载链接变成二维码,后者在 GM 工具里上传日志。转到飞书之后,文本和卡片仍然简单,但想发本地图片和文件时,飞书群自定义机器人就不够用了。
先说结论:
- 只发文本或卡片:用飞书群自定义机器人(webhook)。群里添加就能用,不需要管理员审核。
- 要发本地图片、日志文件,或者想通过接口查
chat_id:用企业自建应用机器人,申请im:resource、im:message等权限。应用版本和权限需要企业管理员审核。 - 本文的代码来自 FeishuAppBot 项目:Python 侧接 CI,负责打包卡片和下载二维码;Unity 侧接 SRDebugger 的 GM 面板,负责发剪贴板、控制台日志和截图。CI 失败时发日志的
send_file()是本文补充的。
项目里的几个文件:
| 文件 | 作用 |
|---|---|
Python/feishu_bot.py |
CI 侧发送卡片、图片、二维码 |
Unity/FeishuAppBot.cs |
Unity 侧发送文本、文件、图片 |
Unity/SROptions.Feishu.cs |
SRDebugger「工具」分类下的三个 GM 按钮 |
README.md |
应用创建、权限、环境变量说明 |
Python 侧依赖 requests、qrcode、pillow;Unity 侧依赖 Newtonsoft.Json 和 SRDebugger。
本文假设你已经有一个飞书企业、能在开发者后台创建自建应用,并且能找到企业管理员审核版本。如果创建应用或发布版本的权限不在你手里,把下面那段清单直接发给管理员即可。
两种飞书机器人
飞书里能往群发消息的机器人主要有两种,能力边界差别很大。
| 能力 | 群自定义机器人(webhook) | 自建应用机器人 |
|---|---|---|
| 接入方式 | 群设置里添加,拿一个 webhook URL | 开发者后台创建应用,开启机器人能力 |
| 管理员审核 | 不需要 | 需要,权限和版本由管理员审核 |
| 文本 / 富文本 / 卡片 | 支持 | 支持 |
| 图片 | 支持 image 类型,但只能引用已有的 image_key |
先上传,拿 image_key 再发 |
| 文件 | 不支持 | 先上传,拿 file_key 再发 |
| 上传本地资源 | 没有上传接口 | im/v1/images、im/v1/files |
获取群 chat_id |
不提供 | 可通过群列表或群信息接口获取 |
| 单条请求体 | 20 KB | 文本 150 KB;卡片 30 KB |
| 频率 | 100 次/分钟、5 次/秒 | 1000 次/分钟、50 次/秒;同群机器人共享 5 QPS |
这里有个容易误解的地方:飞书群自定义机器人是支持图片消息类型的,但它的图片消息只认 image_key。webhook 本身没有上传接口,拿不到本地截图的 image_key,所以实际效果就是「发不了本地图」。文件更直接:自定义机器人的消息类型里根本没有 file。
这就是为什么默认 webhook 机器人做文本通知很舒服,一旦要在 GM 工具里「点一下发截图」或者「失败时附日志」,就必须申请自建应用。自建应用多了创建、权限、发版、管理员审核几步,但换来的是完整的上传和发送能力。
创建自建应用
1. 创建应用并添加机器人能力
- 登录飞书开发者后台,点击「创建企业自建应用」,填名称、描述和图标。
- 进入应用详情,在「应用能力」→「添加应用能力」里添加「机器人」。
- 机器人能力添加后要发布应用才生效,这一步先记着,后面统一发版。
2. 申请权限
在「开发配置」→「权限管理」里开通权限。下面这张表按申请页的原始状态列出本项目实际开通的 9 行,最后一列是本文的用途:
| 权限标识 | 名称 | 身份 | 状态 | 本文用途 |
|---|---|---|---|---|
im:resource |
获取与上传图片或文件资源 | 应用身份 | 已开通 | 上传截图、日志 |
contact:user.employee_id:readonly |
获取用户 user ID | 应用身份 | 已开通(与应用可用范围一致) | 可选 |
im:chat |
获取与更新群组信息 | 用户身份 | 已开通(与用户权限范围一致) | 需要 OAuth,本文不用 |
im:chat |
获取与更新群组信息 | 应用身份 | 已开通 | 群列表、群信息 |
im:chat:read |
查看群信息 | 用户身份 | 已开通(与用户权限范围一致) | 需要 OAuth,本文不用 |
im:chat:read |
查看群信息 | 应用身份 | 已开通 | 群信息 |
im:chat:readonly |
获取群组信息 | 用户身份 | 已开通(与用户权限范围一致) | 需要 OAuth,本文不用 |
im:chat:readonly |
获取群组信息 | 应用身份 | 已开通 | 推荐的最小读权限 |
im:message |
获取与发送单聊、群组消息 | 应用身份 | 已开通 | 发送消息 |
几个取舍:
- 本文走
tenant_access_token,也就是应用身份,所以只看「应用身份」那几行。用户身份那几行是给user_access_token用的,需要走 OAuth 用户授权,CI 和 GM 通知不需要。 im:chat、im:chat:read、im:chat:readonly三个里任选一个就能查群列表和群信息,推荐im:chat:readonly。后台把同一权限的应用身份和用户身份分开显示,很容易误以为要全开。contact:user.employee_id:readonly是字段权限,只在receive_id_type=user_id或需要返回用户user_id时用到。本文按chat_id发群消息,可以不开。- 发本地图片和文件的最小权限组合是
im:message+im:resource;如果还要自动查chat_id,再加一个im:chat*。
权限保存不等于生效。飞书的规则是:基本信息、权限范围、应用功能、事件订阅有变更,都要创建新版本并发布,管理员审核通过后才生效。这也是后面 99991672 最常见的原因:权限页显示「已开通」,但线上跑的还是旧版本。
3. 发布版本,找管理员审核
在「应用发布」→「版本管理与发布」里创建版本,填版本号、更新说明,确认权限变更,设置可用范围(比如研发、QA),然后点「申请线上发布」。
管理员会在飞书管理后台的「工作台」→「应用审核」里看到待审核任务,或者在飞书审批里收到通知。审核通过后应用才正式上线。
如果你不是管理员,可以把下面这段直接发给管理员:
|
|
开发阶段还有一个省事的办法:飞书开放平台提供「测试企业和人员」,在测试企业里权限和配置变更可以直接生效,不需要管理员审核。等联调完再切回正式版,只提交一次审核。这个适合先验证接口,不适合替代正式发布。
4. 把机器人加入目标群
应用发布后,在飞书群里打开「设置」→「群机器人」→「添加机器人」,搜索应用名,把机器人加进群。
两个检查点:
- 机器人必须在目标群里,否则发消息会报
230002。 - 群不能设置成「仅群主/管理员可发言」,否则机器人可能被禁言,报
230018或230035。
5. 获取 App ID、App Secret 和 chat_id
App ID 和 App Secret 在「凭证与基础信息」页。App Secret 泄露后可以在开发者后台重置,旧值立即失效。
chat_id 有两种拿法:
- 飞书客户端 7.60 及以上:群设置页面直接显示群 ID,点右上角群菜单就能看到。
- 调接口查机器人所在的群列表:
|
|
返回的 data.items 里每个群有 chat_id 和 name,按群名找目标群即可。群多的时候注意 has_more 和 page_token,要翻页。
Python 侧不需要把凭证写进代码,用环境变量:
| 变量 | 说明 |
|---|---|
CI_FEISHU_APP_ID |
应用 App ID |
CI_FEISHU_APP_SECRET |
应用 App Secret |
CI_FEISHU_CHAT_ID |
目标群 chat_id |
任一缺失时,项目里的函数会打印 Skip feishu notify: missing credentials 并直接跳过。这个行为在本地开发和 fork 构建里很有用:没有配 secret 就不发通知,不会把构建弄挂。
API 调用流程
飞书应用机器人发一条带图片或文件的消息,固定是三步:
|
|
文本和卡片可以跳过上传;图片要先传 /im/v1/images 拿 image_key,文件要先传 /im/v1/files 拿 file_key,再分别用 msg_type=image 和 msg_type=file 发出去。
1. 获取 tenant_access_token
自建应用的经典接口:
|
|
成功时返回:
|
|
tenant_access_token 最长有效期 2 小时。不要每发一条消息都去换一次 token:在进程内缓存,按返回的 expire 提前 60 秒刷新就够了。剩余有效期小于 30 分钟时,飞书会返回一个新 token,同时旧 token 仍有效,所以并发刷新不会出问题。
飞书现在还提供了 OAuth 2.0 版本的
POST https://accounts.feishu.cn/oauth/v3/token,grant_type=client_credentials,返回字段是access_token和expires_in,而且 token 是 JWT,长度比旧版长很多,存储时至少预留 4 KB。本文代码沿用项目里的经典 internal 接口,因为简单、资料多;新项目可以按官方最新文档迁移,注意不要混用两套字段名。
2. 上传图片或文件
| 资源 | 接口 | multipart 字段 | 限制 | 返回 |
|---|---|---|---|---|
| 图片 | POST /open-apis/im/v1/images |
image_type=message、image |
≤10 MB;支持 JPG/PNG/WEBP/GIF/BMP 等 | image_key |
| 文件 | POST /open-apis/im/v1/files |
file_type=stream、file_name、file |
≤30 MB;不能为空 | file_key |
file_type 按文件类型选:日志、压缩包等通用文件用 stream,PDF 用 pdf,Office 文档用 doc/xls/ppt,视频用 mp4,音频用 opus。file_name 要带扩展名。
文件必须由发送消息的同一个应用上传,否则会报 230017。另外,游戏包通常远超 30 MB,不要试图把 APK 直接传给机器人;发下载链接或二维码更实际。
3. 发送消息
|
|
请求体:
|
|
注意 content 是一个 JSON 字符串,不是对象。不同 msg_type 对应不同的 content:
| 类型 | msg_type |
content 内容 |
|---|---|---|
| 文本 | text |
{"text":"..."} |
| 卡片 | interactive |
{"elements":[...]} |
| 图片 | image |
{"image_key":"img_xxx"} |
| 文件 | file |
{"file_key":"file_xxx"} |
最常见的参数错误是 content 多套了一层 JSON 编码:飞书收到的是一个字符串,里面的 text 字段解析不出来。Python 用 json.dumps(content, ensure_ascii=False) 生成一次字符串就够了;C# 用 JsonConvert.SerializeObject。
发送后的响应里 code 为 0 才算成功。失败时别只看 msg,把 error.log_id 或响应头 X-Tt-Logid 一起记下来,排查或找飞书支持时有用。
游戏打包通知:Python 侧
卡片长什么样
打包通知不需要花哨,一张卡片把状态、版本、耗时和下载入口说清楚就行。项目里目前是一个 div 卡片;实际通知建议再加上 header 颜色:
- 成功:绿色 header,
打包成功。 - 失败:红色 header,
打包失败,附错误摘要。 - 取消/跳过:橙色。
飞书卡片 markdown 支持 <font color='green'> 这样的颜色标签。项目里的 adapt_wechat_markdown() 做了一件小事:把企业微信 CI 文案里的 <font color='warning'> 换成飞书的 <font color='orange'>,这样原来给企业微信写的通知文案可以少改一点。
发送代码
下面是从 feishu_bot.py 整理出来的主流程,保留了环境变量、token 缓存和上传后发送的结构:
|
|
说明:项目里的 Python 封装目前覆盖卡片、图片和二维码,实际卡片是
send_markdown()的单div结构;上面的send_build_card()带 header 的写法是本文的增强示例,send_file()也是本文补充的,方便 CI 在失败时发日志。Unity 侧对应的SendLogFile()已经在FeishuAppBot.cs里实现。示例省略了网络异常捕获,生产环境建议给requests包一层try/except,通知失败只打日志,不要让构建失败。
二维码和日志
二维码解决的是「手机上不好点群链接」的问题。CI 打包完成后,把下载页 URL 传给 send_qrcode(),生成 PNG、上传、发图片消息,测试同学扫码就能装。这个思路和 2022 年那篇企业微信二维码文章一样,只是飞书多了一步上传。
日志则看大小:
- 小于 30 MB:
send_file("build.log", data),失败时把日志文件直接发到群里。 - 大于 30 MB:压缩、截取最后几万行,或者把日志放到内网可访问的地址,卡片里发链接。
- 文本日志如果只想贴最后几十行,也可以直接
send_markdown(),但注意卡片请求体上限是 30 KB,别把整份日志塞进去。
接进 CI
CI 集成有几个原则:
- 通知步骤放在
always()/ 无论前序步骤成功失败都执行的位置,否则失败时最需要通知的时候反而不发。 - 通知失败不要改变构建结果。发送函数返回
False就够了,不要raise到构建脚本。 - App Secret 放 CI 的 secret 存储,不要写进仓库;构建日志里如果打印了 token 或完整响应,记得打码。
- 超时和重试要有,但别无限重试;飞书同一群组 5 QPS,一次构建发一条卡片加一张二维码完全够用。
- 可选:给消息加一个稳定的
uuid,飞书会在 1 小时内对相同uuid的请求去重,重试时不会发两条。
一个最小的调用示例:
|
|
GM 工具通知:Unity 侧
三个按钮
SROptions.Feishu.cs 是一个 partial class SROptions,用 SRDebugger 的 Category/DisplayName 把三个方法挂到「工具」分类下:
- 发送日志到飞书:把系统剪贴板内容当文本发出去,适合快速贴一段报错或玩家 UID。
- 发送所有日志到飞书:读取 SRDebugger 控制台的全部条目(含堆栈),写成
.log文件上传。 - 发送截图到飞书:等帧结束,读全屏像素,编码成 JPG,上传后发图片消息。
代码大致是这样:
|
|
项目里用的是 DataTime.Now 和 TimerMgr.Run,前者是工程里的时间封装,后者是启动协程的封装。上面的示例换成了标准 DateTime,TimerMgr.Run 保留原样;如果你的工程没有这个封装,换成自己的协程启动方式即可。
发送层做了什么
FeishuAppBot.cs 对外只有三个方法:
|
|
内部做了几件容易被忽略的事:
- token 缓存:
_tenantAccessToken和过期时间存静态字段,提前 60 秒刷新。GM 工具可能连续点几个按钮,不应该每次都换 token。 - 长文本拆分:
SendText按完整请求体的字节数切分,每段加[i/n]前缀,单段不超过 150 KB。日志特别长时优先走SendLogFile,不要把几 MB 文本硬拆成几十条消息。 - 大小检查:
SendLogFile限制 30 MB,SendImage限制 10 MB,超限只打 warning,不发起请求。 - multipart 上传:项目里用
HttpWebRequest手写 boundary,file_type=stream、file_name、file三个字段和官方文档一致。 - 同步请求:GM 工具是开发者工具,卡一下无所谓,所以用同步
HttpWebRequest,超时 30 秒、上传 120 秒。不要在正式游戏逻辑里这么干;运行时用UnityWebRequest协程或后台线程,别阻塞主线程。 - 截图时机:必须
yield return new WaitForEndOfFrame()之后再ReadPixels,否则拿到的可能是上一帧或黑屏;Texture2D用完要Destroy,不然连续截图会涨内存。
安全边界:App Secret 不能进正式包
这是本文最需要强调的一点。
项目为了方便,把 YOUR_APP_ID、YOUR_APP_SECRET、YOUR_CHAT_ID 写在 FeishuAppBot.cs 顶部常量里。这对内部 GM 包可以接受,但绝对不能带进对外发布的正式包。App Secret 能直接换 tenant_access_token,等于机器人账号的完整控制权;客户端安装包是可以被反编译的,写进去就等于公开。
飞书官方文档也明确写了:App Secret 属于敏感信息,只能保存在应用服务端,不要写入前端代码、客户端安装包或日志。
建议:
- GM 入口和凭证用
#if DEVELOPMENT_BUILD || UNITY_EDITOR包起来,正式包不编译。 - 更好的做法是客户端不持有 App Secret,只拿一个短期、受限的内部凭证,由内网中转服务去调飞书。
- 一旦发现 Secret 泄露,立即在开发者后台重置,旧 Secret 会立刻失效;但已经签发的
tenant_access_token在过期前仍可能有效,必要时先把机器人移出目标群或停用应用,再排查泄露范围。 - 日志里可能带玩家 UID、订单号、设备信息,只发内部群,必要时脱敏。
踩坑与排查
错误码
| 错误码 | 现象 | 原因 / 处理 |
|---|---|---|
99991672 |
Access denied,提示缺 scope | 应用没申请对应权限。看响应里的 error.permission_violations,申请后重新发版并由管理员审核。 |
99991679 |
Unauthorized | 用的是 user_access_token,但用户没授权对应权限。本文走应用身份不会遇到;如果遇到,检查是不是拿错了 token 类型。 |
230001 |
Invalid request parameter | 参数格式错,常见是 content 双重 JSON 编码、receive_id_type 和 ID 不匹配。 |
230002 |
Bot can not be outside the group | 机器人不在目标群。把应用机器人加进群。 |
230006 |
Bot ability is not activated | 没开机器人能力,或开了但没发版。 |
230013 |
Bot has NO availability to this user | 用户/单聊不在应用可用范围。群消息主要检查机器人在群内;单聊要调可用范围。 |
230017 |
Bot is NOT the owner of the resource | 文件不是当前应用上传的。上传和发送必须用同一个 App ID。 |
230018 |
Operations are NOT allowed at current group settings | 群禁言、仅管理员可发言等设置。 |
230020 |
Triggers the frequency limit | 触发限频,降低发送频率。同群 5 QPS。 |
230025 |
Message content reaches its limit | 文本超 150 KB 或卡片超 30 KB。拆分、截断或改成文件。 |
230034 |
The receive_id is invalid | chat_id 抄错,或 receive_id_type 不是 chat_id。 |
230035 |
Send Message Permission deny | 群禁言、机器人被屏蔽、租户沟通权限管控。 |
234006 |
File size exceed the max value | 文件 >30 MB 或图片 >10 MB。 |
234007 |
App does not enable bot feature | 没开机器人能力。 |
234011 |
Can’t recognize the image format | 图片格式不支持,或文件不是有效图片。 |
常见错误清单
- 权限页显示已开通,接口还是 99991672:权限变更后没有创建新版本并审核发布。去「版本管理与发布」看线上版本是不是旧的。
- 本地图片发成文本路径:
msg_type用了text或者post,没有先调/images拿image_key。 - 文件发出去打不开/报 230017:上传和发送用了不同的应用,或者上传时
file_type和实际格式不匹配。 - 卡片发不出去:卡片 JSON 超 30 KB,或者 markdown 里有不合法的标签;先用纯文本确认链路通。
- token 过期:没有缓存或缓存时间写死;按
expire/expires_in动态算,提前刷新。 - CI 日志泄露 token:项目早期为了排查打印了 token 响应;生产环境只打印
code、msg和log_id。 - 机器人被禁言:检查群设置,或者换一个有发言权限的群。
调试顺序建议:先发一条纯文本,确认 token、chat_id、机器人在群三个条件都满足;再发卡片;最后发图片和文件。每步只引入一个变量,比一次全上容易定位。参数拿不准时,先在API 调试台里把接口调通,再把请求体抄回代码,比在 CI 里反复试快。
总结
飞书机器人通知不难,难的是先选对类型:
- 只在群里发文本、卡片:群自定义机器人 webhook,零审核,最省事。
- 要发本地截图、日志文件,或者要用接口查群:企业自建应用机器人,申请
im:message+im:resource(按需加im:chat:readonly),发版并由管理员审核。 - 图片和文件都是「先上传拿 key,再发消息」;文件不能超过 30 MB,游戏包发链接或二维码。
- App Secret 只放服务端/CI secret;Unity 客户端里的硬编码只限内部 GM 包,正式包必须移除。
项目现在的效果:CI 打包完成后,飞书群里收到一张带版本、耗时和下载链接的卡片,成功时附二维码;失败时可以用本文补充的 send_file() 附日志。GM 工具里点三个按钮,就能把剪贴板、全部控制台日志或当前截图发到同一个群。
相关文章:
参考资料:
版权声明:
作者:dingding
链接:https://www.techfm.club/p/239371.html
来源:TechFM
文章版权归作者所有,未经允许请勿转载。

共有 0 条评论