飞书机器人通知

介绍

游戏打包完成后,群里需要一条消息:成功还是失败、版本号、提交、耗时、下载地址。测试同学最好能直接扫码安装;失败时还要把日志带上。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. 创建应用并添加机器人能力

  1. 登录飞书开发者后台,点击「创建企业自建应用」,填名称、描述和图标。
  2. 进入应用详情,在「应用能力」→「添加应用能力」里添加「机器人」。
  3. 机器人能力添加后要发布应用才生效,这一步先记着,后面统一发版。

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),然后点「申请线上发布」。

管理员会在飞书管理后台的「工作台」→「应用审核」里看到待审核任务,或者在飞书审批里收到通知。审核通过后应用才正式上线。

如果你不是管理员,可以把下面这段直接发给管理员:

 1  2  3  4  5  6  7  8  9 10 11 12 13 
应用名:FeishuAppBot(企业自建应用) 用途:游戏打包结果通知;GM 工具日志、截图上报 需要权限: - im:message(应用身份,发消息) - im:resource(应用身份,上传图片/文件) - im:chat:readonly(应用身份,查群 ID,可选) - contact:user.employee_id:readonly(应用身份,可选) 目标群:研发群、QA 群 可用范围:研发、QA 需要你帮忙: 1. 审核并发布应用版本; 2. 如果权限需要单独开通,请一并开通; 3. 确认机器人可以加入目标群。 

开发阶段还有一个省事的办法:飞书开放平台提供「测试企业和人员」,在测试企业里权限和配置变更可以直接生效,不需要管理员审核。等联调完再切回正式版,只提交一次审核。这个适合先验证接口,不适合替代正式发布。

4. 把机器人加入目标群

应用发布后,在飞书群里打开「设置」→「群机器人」→「添加机器人」,搜索应用名,把机器人加进群。

两个检查点:

  • 机器人必须在目标群里,否则发消息会报 230002。
  • 群不能设置成「仅群主/管理员可发言」,否则机器人可能被禁言,报 230018 或 230035。

5. 获取 App ID、App Secret 和 chat_id

App ID 和 App Secret 在「凭证与基础信息」页。App Secret 泄露后可以在开发者后台重置,旧值立即失效。

chat_id 有两种拿法:

  • 飞书客户端 7.60 及以上:群设置页面直接显示群 ID,点右上角群菜单就能看到。
  • 调接口查机器人所在的群列表:
1 2 
curl -s -H "Authorization: Bearer $TOKEN" /  "https://open.feishu.cn/open-apis/im/v1/chats?page_size=100" 

返回的 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 调用流程

飞书应用机器人发一条带图片或文件的消息,固定是三步:

1 
tenant_access_token → 上传资源(可选)→ 发送消息 

文本和卡片可以跳过上传;图片要先传 /im/v1/images 拿 image_key,文件要先传 /im/v1/files 拿 file_key,再分别用 msg_type=image 和 msg_type=file 发出去。

1. 获取 tenant_access_token

自建应用的经典接口:

1 2 3 
curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal /  -H "Content-Type: application/json" /  -d '{"app_id":"cli_xxx","app_secret":"xxx"}' 

成功时返回:

1 2 3 4 5 6 
{ "code": 0, "msg": "ok", "tenant_access_token": "t-xxx", "expire": 7200 } 

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. 发送消息

1 2 3 
POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id Authorization: Bearer t-xxx Content-Type: application/json; charset=utf-8 

请求体:

1 2 3 4 5 
{ "receive_id": "oc_xxx", "msg_type": "text", "content": "{/"text/":/"打包成功/"}" } 

注意 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 缓存和上传后发送的结构:

 1  2  3  4  5  6  7  8  9  10  11  12  13  14  15  16  17  18  19  20  21  22  23  24  25  26  27  28  29  30  31  32  33  34  35  36  37  38  39  40  41  42  43  44  45  46  47  48  49  50  51  52  53  54  55  56  57  58  59  60  61  62  63  64  65  66  67  68  69  70  71  72  73  74  75  76  77  78  79  80  81  82  83  84  85  86  87  88  89  90  91  92  93  94  95  96  97  98  99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 
import io import json import os import time import qrcode import requests TOKEN_URL = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" MESSAGE_URL = "https://open.feishu.cn/open-apis/im/v1/messages" IMAGE_URL = "https://open.feishu.cn/open-apis/im/v1/images" FILE_URL = "https://open.feishu.cn/open-apis/im/v1/files" _token = None _expire_at = 0.0 def get_credentials(): app_id = os.environ.get("CI_FEISHU_APP_ID", "") app_secret = os.environ.get("CI_FEISHU_APP_SECRET", "") chat_id = os.environ.get("CI_FEISHU_CHAT_ID", "") if not app_id or not app_secret or not chat_id: print("Skip feishu notify: missing credentials") return None return app_id, app_secret, chat_id def get_token(app_id, app_secret): global _token, _expire_at now = time.time() if _token and now < _expire_at - 60: return _token response = requests.post( TOKEN_URL, json={"app_id": app_id, "app_secret": app_secret}, timeout=30, ) data = response.json() if data.get("code") != 0: print(f"Get tenant_access_token failed: {data}") return None _token = data.get("tenant_access_token") _expire_at = now + int(data.get("expire", 0)) return _token def send_message(msg_type, content): credentials = get_credentials() if not credentials: return False app_id, app_secret, chat_id = credentials token = get_token(app_id, app_secret) if not token: return False payload = { "receive_id": chat_id, "msg_type": msg_type, "content": json.dumps(content, ensure_ascii=False), } response = requests.post( MESSAGE_URL, params={"receive_id_type": "chat_id"}, headers={"Authorization": f"Bearer {token}"}, json=payload, timeout=30, ) data = response.json() if data.get("code") != 0: print(f"Send feishu message failed: {data}") return False return True def send_markdown(markdown): return send_message("interactive", { "elements": [{ "tag": "div", "text": {"tag": "lark_md", "content": markdown}, }], }) def send_build_card(ok, project, version, duration, download_url): title = "打包成功" if ok else "打包失败" template = "green" if ok else "red" markdown = ( f"**项目**:{project}/n" f"**版本**:{version}/n" f"**耗时**:{duration}/n" f"[下载地址]({download_url})" ) card = { "config": {"wide_screen_mode": True}, "header": { "template": template, "title": {"tag": "plain_text", "content": title}, }, "elements": [{ "tag": "div", "text": {"tag": "lark_md", "content": markdown}, }], } return send_message("interactive", card) def send_image(image_bytes, file_name="image.png", content_type="image/png"): if not image_bytes: return False credentials = get_credentials() if not credentials: return False app_id, app_secret, _ = credentials token = get_token(app_id, app_secret) if not token: return False response = requests.post( IMAGE_URL, headers={"Authorization": f"Bearer {token}"}, files={ "image_type": (None, "message"), "image": (file_name, image_bytes, content_type), }, timeout=120, ) data = response.json() image_key = data.get("data", {}).get("image_key") if data.get("code") != 0 or not image_key: print(f"Upload feishu image failed: {data}") return False return send_message("image", {"image_key": image_key}) def send_qrcode(url): qr = qrcode.QRCode( version=1, error_correction=qrcode.constants.ERROR_CORRECT_L, box_size=10, border=4, ) qr.add_data(url) qr.make(fit=True) image = qr.make_image(fill_color="black", back_color="white") buffer = io.BytesIO() image.save(buffer, format="PNG") return send_image(buffer.getvalue(), "qrcode.png") def send_file(file_name, file_bytes): if not file_bytes or len(file_bytes) > 30 * 1024 * 1024: print("Skip feishu file: empty or larger than 30 MB") return False credentials = get_credentials() if not credentials: return False app_id, app_secret, _ = credentials token = get_token(app_id, app_secret) if not token: return False response = requests.post( FILE_URL, headers={"Authorization": f"Bearer {token}"}, files={ "file_type": (None, "stream"), "file_name": (None, file_name), "file": (file_name, file_bytes, "application/octet-stream"), }, timeout=120, ) data = response.json() file_key = data.get("data", {}).get("file_key") if data.get("code") != 0 or not file_key: print(f"Upload feishu file failed: {data}") return False return send_message("file", {"file_key": file_key}) 

说明:项目里的 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 的请求去重,重试时不会发两条。

一个最小的调用示例:

 1  2  3  4  5  6  7  8  9 10 11 12 13 14 
if __name__ == "__main__": ok = build() # 你的打包逻辑 send_build_card( ok=ok, project="UnityCIGame", version="1.2.3", duration="12m 34s", download_url="https://example.com/download/1.2.3", ) if ok: send_qrcode("https://example.com/download/1.2.3") else: with open("build.log", "rb") as f: send_file("build.log", f.read()) 

GM 工具通知:Unity 侧

三个按钮

SROptions.Feishu.cs 是一个 partial class SROptions,用 SRDebugger 的 Category/DisplayName 把三个方法挂到「工具」分类下:

  • 发送日志到飞书:把系统剪贴板内容当文本发出去,适合快速贴一段报错或玩家 UID。
  • 发送所有日志到飞书:读取 SRDebugger 控制台的全部条目(含堆栈),写成 .log 文件上传。
  • 发送截图到飞书:等帧结束,读全屏像素,编码成 JPG,上传后发图片消息。

代码大致是这样:

 1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 
using System; using System.Collections; using System.ComponentModel; using System.Text; using SRDebugger.Internal; using UnityEngine; public partial class SROptions {  [Category("工具"), DisplayName("发送日志到飞书")] public void Log2Feishu() { FeishuAppBot.SendText(GUIUtility.systemCopyBuffer); }   [Category("工具"), DisplayName("发送所有日志到飞书")] public void SendLogFileToFeishu() { var fileName = $"{DateTime.Now:yyyyMMdd-HHmmss}.log"; FeishuAppBot.SendLogFile(fileName, GetAllConsoleLogs()); }   [Category("工具"), DisplayName("发送截图到飞书")] public void ScreenShot2Feishu() { TimerMgr.Run(CaptureScreenshotForFeishu()); } private IEnumerator CaptureScreenshotForFeishu() { yield return new WaitForEndOfFrame(); var rect = new Rect(0f, 0f, Screen.width, Screen.height); var texture = new Texture2D((int)rect.width, (int)rect.height, TextureFormat.RGB24, false); texture.ReadPixels(rect, 0, 0); texture.Apply(); var jpeg = texture.EncodeToJPG(); UnityEngine.Object.Destroy(texture); FeishuAppBot.SendImage(jpeg); } public static string GetAllConsoleLogs() { var result = new StringBuilder(); foreach (var entry in Service.Console.AllEntries) { for (var i = 0; i < entry.Count; i++) { result.AppendLine(entry.Message); result.AppendLine(entry.StackTrace); } } return result.ToString(); } } 

项目里用的是 DataTime.Now 和 TimerMgr.Run,前者是工程里的时间封装,后者是启动协程的封装。上面的示例换成了标准 DateTime,TimerMgr.Run 保留原样;如果你的工程没有这个封装,换成自己的协程启动方式即可。

发送层做了什么

FeishuAppBot.cs 对外只有三个方法:

1 2 3 
FeishuAppBot.SendText(string text); FeishuAppBot.SendLogFile(string fileName, string fileContent); FeishuAppBot.SendImage(byte[] jpegBytes); 

内部做了几件容易被忽略的事:

  • 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
文章版权归作者所有,未经允许请勿转载。

THE END
分享
二维码
< <上一篇
下一篇>>