飞书与腾讯会议API对接实战：SSO、鉴权与事件回调全解析

1. 为什么要把飞书和腾讯会议拉到一起1.1 一个真实的需求场景事情是这样的我们团队日常协作重度依赖飞书文档、审批、多维表格、机器人通知全在上面跑。但视频会议这块公司采购的是腾讯会议的企业版会议室硬件、Rooms、大型研讨会都绑在腾讯会议生态里。结果就出现了一个很割裂的体验——在飞书里排好了日程到点还得手动复制会议号去腾讯会议开会议纪要、录制文件又散落在腾讯会议后台想同步回飞书文档得靠人肉搬运。这种“两套系统各干各的”状态小团队忍忍就过去了但人一多、会议一密沟通成本就指数级上升。所以我们的目标很明确让飞书成为统一入口腾讯会议作为底层会议能力被调用用户感知不到切换但背后两个平台的数据是打通的。这里要澄清一个概念所谓“对接”不是把两个产品合并而是通过API SSO 事件回调三条链路把身份、会议、数据串起来。热搜词里出现的“飞书”“腾讯会议”“对接”“API”“SSO”正好对应了这件事的五个核心要素下面我会逐个拆开讲。1.2 对接能解决哪些具体问题先列一下我们实际落地后收益最明显的几个点方便你判断自己的场景是否值得做日程自动带会议链接在飞书日历创建日程时自动调用腾讯会议 API 生成会议号并回填到日程描述里参会人点开就能进。一键发起会议飞书机器人里发一条指令直接拉起一个腾讯会议会议号回传到当前会话。录制与纪要回流会议结束后通过腾讯会议的事件回调拿到录制文件地址和智能纪要自动写入飞书多维表格或文档。统一身份用飞书做 IdP身份提供方通过 SSO 登录腾讯会议管理后台免去两套账号密码。会议室资源联动飞书审批通过后自动在腾讯会议预定对应会议室。这五条里前三条是大多数团队最刚需的后两条偏管理侧。我建议你按“日程带链接 → 机器人发起 → 录制回流”这个顺序推进因为复杂度是递增的收益也是递增的。1.3 适合谁来读这篇如果你是完全不懂 API 的产品或运营同学这篇会让你理解对接的边界在哪、哪些需求技术上可行、哪些是坑如果你是开发同学我会给出具体的鉴权流程、参数结构和踩坑记录可以直接抄作业。整体上我假设读者对 HTTP 接口、OAuth 有基本概念但不要求你之前做过飞书或腾讯会议的开发。2. 整体架构设计与选型考量2.1 三条链路的分工在动手写代码之前先把架构想清楚否则后面会反复返工。我们的方案是三条链路并行链路作用关键技术触发方向身份链路统一登录、权限校验SSO / OAuth2.0飞书 → 腾讯会议业务链路创建会议、查会议、改会议REST API飞书应用 → 腾讯会议事件链路会议结束、录制生成通知Webhook 回调腾讯会议 → 飞书应用这三条链路里身份链路是基础因为业务链路调用腾讯会议 API 时需要 access_token而这个 token 的获取方式和你用哪种鉴权模式强相关。很多人一上来就写创建会议的代码结果卡在鉴权上就是因为没先把身份链路理清楚。2.2 为什么选服务端中转而不是前端直连热搜词里有“vue3 引入飞书 sdk”这类前端方案但我要泼一盆冷水腾讯会议的 API 调用绝对不要放在前端。原因有三个第一腾讯会议的 access_token 是应用级别的凭证一旦泄露别人可以拿着你的身份创建会议、读取录制风险极高。前端代码对用户是可见的等于把钥匙挂在门上。第二跨域问题。腾讯会议的部分接口不支持浏览器直接跨域调用你会在控制台看到一堆 CORS 报错折腾半天也绕不过去。第三事件回调必须有一个公网可达的服务端地址来接收前端做不到。所以正确的架构是前端飞书应用/机器人→ 你的服务端 → 腾讯会议 API。服务端负责持有密钥、换取 token、转发请求、接收回调。这个中转层虽然多写一点代码但安全性和可维护性完全不是一个量级。2.3 鉴权模式的选择JWT 还是 OAuth腾讯会议开放平台提供两种主要的鉴权方式选错了后面会很痛苦JWT 模式应用级用 AppId SecretId SecretKey 生成 JWT再换取 access_token。适合服务端后台任务比如定时同步会议、批量处理录制。OAuth2.0 模式用户级用户授权后拿到 code换 user_access_token。适合需要以“某个用户身份”操作的场景比如代表用户创建他名下的会议。我们的选择是两者都用后台定时任务用 JWT用户主动发起的操作走 OAuth。这里有个经验如果你的场景只是“创建会议并回填链接”其实 JWT 就够了因为会议归属可以是应用而非个人。只有当你要读取“某个用户的个人会议列表”时才必须用 OAuth。注意JWT 生成的 token 有有效期通常是 30 分钟左右一定要做缓存和自动刷新不要每次请求都重新生成否则会触发频率限制。2.4 飞书侧的应用形态选择飞书这边你需要创建一个“企业自建应用”然后按需开启能力机器人能力用于在群里发指令、推送会议通知。日历能力用于读写日程、回填会议链接。云文档能力用于把录制纪要写入多维表格或文档。网页应用能力如果你要做管理后台用这个承载。权限申请是个磨人的活飞书的权限粒度很细建议一开始就把需要的权限列全一次性申请否则每次加权限都要重新走审批很耽误进度。常见的几个权限包括calendar:calendar、im:message、bitable:app等。3. 核心细节解析与实操要点3.1 腾讯会议 JWT 鉴权的完整计算过程这是整个对接里最容易出错的一环我把计算过程拆到每一步。腾讯会议的 JWT 用的是 HS256 算法payload 里必须包含appId、iat签发时间、exp过期时间、aud、iss。具体步骤准备三个值AppId、SecretId、SecretKey在腾讯会议开放平台的应用详情页能拿到。构造 payloadiat和exp用 Unix 时间戳秒exp - iat不要超过 1800 秒。用 SecretKey 作为密钥对 header payload 做 HS256 签名。把 JWT 放到请求头Authorization: Bearer jwt调用换取 access_token 的接口。用 Python 实现大概是这样import time import jwt # PyJWT def build_jwt(app_id, secret_id, secret_key): now int(time.time()) payload { appId: app_id, iat: now, exp: now 1800, aud: https://meeting.tencent.com, iss: secret_id, } token jwt.encode(payload, secret_key, algorithmHS256) return token拿到 JWT 后再调https://api.meeting.tencent.com/v1/access-token换取真正的 access_token。这里有个坑返回的 access_token 有效期是 7200 秒但建议提前 5 分钟刷新避免边界时间请求失败。3.2 飞书事件订阅的验证机制飞书的事件订阅Event Subscription在配置回调地址时会先发一个challenge验证请求你的服务端必须原样返回 challenge 值否则配置不通过。这个验证逻辑很多人第一次会漏掉。验证通过后飞书推送的事件是加密的如果你开启了加密需要用 Encrypt Key 解密。事件体里包含schema、header、event三部分header.event_type告诉你这是什么事件比如calendar.event.created。提示飞书事件推送有重试机制如果你的服务端返回非 200飞书会重试多次。所以你的处理逻辑必须幂等同一个 event_id 处理多次不能产生副作用。3.3 会议创建接口的关键参数腾讯会议的创建会议接口POST /v1/meetings参数不少我挑几个容易踩坑的说instanceid如果是周期性会议这个字段必填且要和recurring_rule配合。start_time/end_time格式是 Unix 时间戳秒不是毫秒传错了会议时间会变成 1970 年。meeting_type0 是普通会议1 是周期性会议选错会导致后续更新会议时接口报错。password可选但如果你的企业安全策略要求会议必须有密码这里不传会被拒绝。返回结果里最重要的是meeting_number会议号和meeting_id会议唯一标识。回填到飞书日程时用 meeting_number后续更新/取消会议时用 meeting_id两者别搞混。3.4 数据映射表的设计飞书日程和腾讯会议之间需要一张映射表来关联否则会议更新时你不知道该改哪个。我们用的是飞书多维表格存这张映射字段设计如下字段名类型说明feishu_event_id文本飞书日程的唯一 IDtencent_meeting_id文本腾讯会议的唯一 IDmeeting_number文本会议号用于展示status单选待开始/进行中/已结束/已取消record_url文本录制文件地址回调后回填这张表是整个对接的“账本”所有状态变更都围绕它。我强烈建议你把它建起来哪怕一开始只用两个字段后面扩展会省很多事。4. 实操过程与核心环节实现4.1 环境准备与依赖安装先把基础环境搭好。服务端我用的是 Python FastAPI原因是异步支持好、写回调接口方便。依赖清单pip install fastapi uvicorn pyjwt requests cryptography飞书 SDK 官方有 Python 版本但实测下来直接用 requests 调 REST 接口更灵活SDK 反而会隐藏一些细节出问题不好排查。所以我这里不引入 SDK全部手写 HTTP 调用。环境变量统一管理密钥不要硬编码export FEISHU_APP_IDcli_xxxxxx export FEISHU_APP_SECRETxxxxxx export TENCENT_APP_IDxxxxxx export TENCENT_SECRET_IDxxxxxx export TENCENT_SECRET_KEYxxxxxx4.2 飞书日程创建事件的接收与处理完整流程是这样的用户在飞书创建日程 → 飞书推送calendar.event.created事件 → 你的服务端解析事件 → 调用腾讯会议创建会议 → 把会议号回填到飞书日程。接收事件的代码骨架from fastapi import FastAPI, Request app FastAPI() app.post(/feishu/event) async def feishu_event(request: Request): body await request.json() # 处理 challenge 验证 if challenge in body: return {challenge: body[challenge]} # 解密并处理事件 event decrypt_event(body) if event[header][event_type] calendar.event.created: handle_calendar_created(event[event]) return {code: 0}handle_calendar_created里要做的事提取日程的标题、开始时间、结束时间、参会人然后调腾讯会议接口创建会议最后调飞书更新日程接口把会议号写进描述。这里有个细节飞书日程的时间是带时区的 ISO8601 字符串比如2024-06-01T10:00:0008:00而腾讯会议要的是 Unix 时间戳。转换时一定要用带时区的解析否则会差 8 小时。我踩过这个坑会议全部提前了 8 小时被同事吐槽了一整天。4.3 腾讯会议创建会议的完整调用封装一个创建会议的函数import requests def create_tencent_meeting(access_token, subject, start_ts, end_ts): url https://api.meeting.tencent.com/v1/meetings headers { Authorization: fBearer {access_token}, Content-Type: application/json, } payload { subject: subject, start_time: start_ts, end_time: end_ts, meeting_type: 0, password: 123456, } resp requests.post(url, jsonpayload, headersheaders) data resp.json() if data.get(code) ! 0: raise Exception(f创建会议失败: {data}) return data[meeting_number], data[meeting_id]调用成功后把meeting_number拼成链接https://meeting.tencent.com/dm/xxxxx回填到飞书日程描述里。参会人打开日程就能看到链接点击直接进会。4.4 录制回调的接收与纪要回流会议结束后腾讯会议会推送录制完成的事件到你的回调地址。事件体里包含meeting_id和record_files数组每个文件有下载地址和有效期。处理逻辑根据meeting_id查映射表找到对应的飞书日程。下载录制文件注意地址有有效期通常 24 小时要尽快处理。如果有智能纪要调腾讯会议接口获取纪要文本。把纪要写入飞书多维表格把录制链接写入日程描述。注意录制文件的下载地址是带签名的临时地址不要存到数据库里长期使用过期后会 403。正确做法是存文件本身或转存到对象存储。4.5 机器人指令发起会议在飞书群里 机器人 发“开会”机器人回复一个会议链接。实现方式是订阅im.message.receive_v1事件解析消息内容匹配关键词后调创建会议接口再用机器人发消息接口回复。这里要注意飞书机器人的消息有格式要求纯文本用text类型带链接的用post富文本类型体验更好。回复时记得带上receive_id群 ID 或用户 ID和receive_id_type类型传错消息发不出去。5. 常见问题与排查技巧实录5.1 鉴权类问题速查报错信息原因解决401 UnauthorizedJWT 过期或签名错误检查 exp 是否超时SecretKey 是否正确403 Forbidden权限不足检查应用是否开通对应接口权限token 无效access_token 过期实现自动刷新提前 5 分钟换新频率限制请求过于频繁加缓存token 复用避免重复生成5.2 时间与时区问题这是最高频的坑。飞书用 ISO8601 带时区腾讯会议用 Unix 时间戳中间转换必须显式指定时区。我建议统一在服务端转成 UTC 时间戳展示时再转回本地时区这样逻辑最清晰。5.3 事件重复推送飞书和腾讯会议的事件推送都可能重复如果你的处理逻辑不幂等会出现同一场会议被创建两次的情况。解决办法是用event_id做去重处理前先查一下这个 ID 是否处理过处理过就直接返回成功。5.4 回调地址不可达回调地址必须是公网可达的 HTTPS 地址本地开发时用内网穿透工具临时暴露。但要注意穿透工具的地址每次重启会变配置回调时要及时更新否则事件收不到。生产环境建议用固定的域名 证书。5.5 会议号回填失败有时候创建会议成功了但回填飞书日程失败导致用户看不到链接。这种情况要做补偿把失败的记录写进重试队列定时重试。我们用的是简单的数据库表 定时任务跑起来很稳。6. 一些实操心得与扩展方向6.1 我踩过的三个印象最深的坑第一个是时区前面说过了会议时间全错。第二个是 token 缓存一开始每次请求都重新生成 JWT结果触发了腾讯会议的频率限制接口直接返回 429。后来加了内存缓存token 有效期 7200 秒缓存 6900 秒问题解决。第三个是事件解密飞书的事件如果开启了加密body 里是密文需要先用 Encrypt Key 做 AES 解密我一开始没开加密测试通过开了加密后全部报错排查了半天。6.2 性能与稳定性建议token 缓存必做能省掉大量重复鉴权请求。异步处理事件回调里不要做耗时操作先返回 200把实际处理丢到队列里异步做避免超时导致重试。日志留痕每次 API 调用都记录请求参数和返回结果出问题时能快速定位。监控告警对创建会议失败率、回调延迟做监控超过阈值告警。6.3 还能往哪些方向扩展对接跑通之后可以继续做几件事一是把会议数据接入飞书多维表格做统计分析比如每周会议时长、参会人数分布二是结合飞书审批实现“会议室预定审批通过后自动创建会议”三是把腾讯会议的智能纪要接入内部知识库做会议内容的检索。这些都是在基础对接之上的增值玩法按需推进即可。整体做下来我的感受是飞书和腾讯会议的对接难点不在单个接口的调用而在身份、时间、事件这三条线的对齐。把这三块理顺了剩下的就是体力活。希望这篇记录能帮你少走点弯路。