飞书与腾讯会议API对接实战：从手动开会到全流程自动化

说实话我在公司内部第一次把飞书和腾讯会议打通的时候团队群里瞬间就炸了。原因是之前每次开周会都是先有人在飞书群里甩一个腾讯会议链接然后另外一个人再手动去改会议时间还有人总在问“这会议有录屏吗”。后来我花了两个晚上把这两套系统连起来所有流程全部自动化群里从“人工低效协作”直接变成了“机器人全程托管”。这篇文章就把我踩过的坑、最终落地的方案、以及很多文档里不会写的细节完整复盘一遍。内容会偏实践代码和接口调用都会有照着抄作业基本能跑通。1. 背景与整体设计为什么要做飞书和腾讯会议的对接1.1 业务痛点会议流程里的“隐形时间黑洞”先说下我当时的实际场景。公司用的是飞书做组织协同和消息流转腾讯会议作为外部客户沟通和内部培训的常驻工具。两者本身都挺好用但只要它们不联动问题就特别明显创建会议靠手工每天助理需要登录腾讯会议后台或客户端手动创建会议再把链接、会议号、密码一条条复制到飞书群一多就容易漏。会议信息不同步飞书日程里建了会议但腾讯会议那边没有任何纪要、录屏、参会记录每次复盘都要找人去要。通知靠人肉催会议开始后没提醒线上接入人数不足也没人知道经常出现主持人开着会等半天才有人进。没有统一的“事后归档”会议结束后的录屏、纪要、任务分派结果散落在不同地方很难追踪。对接之后我理想中的流程是这样的飞书群里输入一个斜杠指令或者机器人触发关键词。后台自动调用腾讯会议 API 创建一场会议。飞书机器人把会议链接、会议号、密码、时间、主题全部推送回群。会议开始前飞书再自动推送提醒。会议结束或收到事件回调后自动把会议链接、时长、参会情况汇总到飞书文档或群内卡片里。这套流程看着不复杂但真正落地时两边开放平台的认证机制、鉴权方式、回调规则都有不少坑。下面我把整个部署过程拆开来讲。1.2 技术选型API对接和机器人哪个方案更适合先说结论如果只是“发个链接到群里”飞书自定义机器人 Webhook 就够了不需要开发飞书应用也不需要鉴权。但如果要做“双向联动”“读取会议状态”“自动归档”就必须走飞书开放平台的自建应用 腾讯会议开放平台的 API。我在最初设计时对比过几个方案方案一飞书自定义机器人 腾讯会议手动复制信息。这个只能说比纯手工强一点能做到“把链接丢进群里”但做不到自动创建会议也不会有状态回传我直接放弃了。方案二飞书自建应用机器人 腾讯会议开放平台 API。这是我最终采用的方案两边都用官方开放接口数据链路完整权限可控支持后续扩展。方案三通过低代码平台/Dify 这类工具去串。这个适合没有开发能力的团队但它封装的太死遇到鉴权细节、字段自定义、回调逻辑反而更难排查所以我只把它作为辅助手段。对于有 API 接入经验的团队方案二绝对是最稳的。它不仅解决“发通知”这个表面问题还能把会议生命周期都管起来。2. 飞书侧准备应用创建、权限配置、机器人消息卡片2.1 创建飞书自建应用拿到 App ID 和 App Secret飞书开放平台的后台地址是open.feishu.cn进去后选“开发者后台”创建企业自建应用。这一步几乎所有教程都会写但有几个细节经常被忽略。第一应用创建后默认没有任何权限。你必须到“权限管理”里开通至少这几项im:message:send_as_bot以机器人身份发送消息。im:chat:readonly读取群信息用来拿到 chat_id。contact:user.base:readonly如果有需要按用户维度推送就得开。drive:drive:readonly或drive:file:readonly如果后面要自动创建飞书云文档并写入会议纪要需要文件相关权限。第二权限开通后不是立刻生效需要发布应用版本。很多新手在这里卡住“为什么我明明开了权限接口还是返回 permission denied”因为应用必须发布新版本后权限才会真正更新。第三App ID 和 App Secret 在“凭证与基础信息”页面。App Secret 一定要放在服务端环境变量里不要写进前端代码或直接贴在飞书群里。我在公司内网 Git 仓库里都会做脱敏处理。2.2 获取群聊 chat_id让机器人知道往哪发飞书机器人的消息接口里receive_id 支持多种 ID 类型包括 open_id、user_id、chat_id。我常用的是 chat_id因为会议通知基本都是发到具体群里的。获取 chat_id 有三种常用方式第一种把机器人拉进目标群然后用“获取机器人所在群列表”的接口遍历返回的群组根据群名称匹配。第二种在群里发一条消息然后通过“获取群信息”接口按 thread_id 反查这种方式比较绕。第三种也是我经常用的直接在飞书开放平台的事件订阅里配置接收im.message.receive_v1事件当群里有人 机器人触发指令时事件回调的 payload 里就直接带上了 chat_id顺手存进配置表就行。实际开发时我推荐用第二种思路配合事件回调。因为单纯靠接口拉群列表还需要群名称做映射一旦重名就会串。2.3 配置事件订阅让飞书能“听到”群里的指令飞书的事件订阅是整个对接的入口之一。在开发者后台的“事件与回调”里你需要先配置一个回调地址飞书会发送一个 URL 验证请求你的服务端要按官方要求返回加密串验证通过后才能正常接收事件。这里有一个很典型的坑飞书要求回调地址必须公网可访问而且需要先完成“加密策略”的配置。如果你直接把 localhost 填进去那是永远验证不过的。我当时是先用内网穿透工具调试等逻辑通了再部署到测试服务器这个问题才算解决。收到im.message.receive_v1事件后要解析出消息内容和发送者信息。对于“创建会议”这种指令型交互我建议把消息内容按文本解析比如“/create_meeting 15:00 客户需求评审”后台提取时间和主题再去调腾讯会议 API。2.4 消息卡片从“纯文本”升级到“可交互按钮”一开始我的机器人只会发纯文本把会议链接和会议号拼在一起。后来发现纯文本有两个问题一是链接很长手机上容易被截断二是没有“一键入会”“复制会议号”这类快捷入口用户体验一般。飞书消息卡片可以很好地解决这个问题。卡片里面可以放按钮按钮支持回调。我做的卡片长这样标题会议主题 时间。正文会议号、密码、入会链接。按钮一点击后跳转腾讯会议客户端/网页入会用 meet 协议或链接跳转。按钮二点击后机器人再发一条会议日程卡片到群里。按钮三会议结束后点击“生成纪要”触发服务端拉取腾讯会议云录制信息并写入飞书文档。实现卡片时重点要处理好按钮的 callback 数据。飞书卡片回调会 POST 到你配置的回调地址你需要通过action.value判断用户点了哪个按钮。比如我约定的value结构是{action:join_meeting,meeting_id:xxx,join_url:xxx}后端收到后根据 action 分支处理。具体代码结构大概是def handle_card_callback(data): action data.get(action, {}).get(value, {}) if action.get(action) join_meeting: meeting_id action.get(meeting_id) # 构造跳转链接或更新卡片 elif action.get(action) generate_notes: # 调用腾讯会议 API 查询录制然后创建飞书文档 pass3. 腾讯会议侧准备开放平台应用、鉴权签名、核心接口3.1 注册开放平台应用理解 Client ID 与 Client Secret腾讯会议开放平台的入口在腾讯会议官网底部的“开放平台”或者直接搜“腾讯会议开放平台”。进入后先注册企业账号然后创建一个应用。应用创建后会拿到Client ID类似飞书的 App ID。Client Secret相当于密钥。Secret ID和Secret Key它们是用于签名请求的和上面两个不是一回事。这里的配置项有点多特别容易搞混。我第一次对接时误以为 Client Secret 就是用来做请求签名的结果调接口一直报1001或签名错误。后来认真看文档才明白腾讯会议的 API 鉴权核心是“密钥对签名”不是简单的 OAuth2 Bearer Token。3.2 请求签名机制腾讯会议 API 的“入场券”腾讯会议开放平台的每个请求都需要在 HTTP Header 里带上以x-tc-开头的参数包括X-TC-Key你的 Secret ID。X-TC-Timestamp当前时间的 Unix 时间戳秒级。X-TC-Nonce随机字符串每次请求都要不同。X-TC-Signature通过 Secret Key 对特定字符串做 HMAC-SHA256 后得到的签名值。签名字符串的拼接规则其实不复杂把请求方法GET/POST/PUT、请求路径、时间戳、随机串按文档顺序拼在一起再带上请求体body最后用 Secret Key 做 HMAC 加密。这里我直接贴一段我这边封装好的 Python 签名代码核心逻辑如下import hashlib import hmac import time import random import string def generate_signature(secret_key, method, path, timestamp, nonce, body_str): # 腾讯会议的签名串由多个字段拼接而成 sign_str f{method}\n{path}\n{timestamp}\n{nonce}\n{body_str}\n signature hmac.new( secret_key.encode(utf-8), sign_str.encode(utf-8), hashlib.sha256 ).hexdigest() return signature需要注意几个点body_str必须是请求体的 JSON 原始字符串不能是重新序列化后的否则字段顺序不同会导致签名对不上。有的接口要求 POST 请求签名串里 method 要写大写有的接口是 PUT也要对应改。时间戳必须是服务器当前时间偏差超过一定范围也会拒绝请求。这个签名机制在刚开始调试时会比较痛苦因为它不返回具体哪一步错了只告诉你“签名校验失败”。我的建议是不要手搓去腾讯会议开放平台下载官方 SDK 或参考官方示例官方有 Java、Python、Go 的完整示例直接封装好后只暴露“传参调用”的接口给自己项目用。3.3 创建会议接口核心入参与返回字段腾讯会议 API 里最常用的就是“创建会议”接口路径大致是POST /v1/meetings。核心入参包括meeting_id如果是预定会议并希望固定会议号可以指定否则留空会自动生成。subject会议主题。start_timeUnix 时间戳。end_timeUnix 时间戳。meeting_type0 是普通会议1 是周期性会议。settings里面可以设置入会密码、是否开启等候室、是否允许参会者改名等。hosts指定主持人这里要填腾讯会议侧的 userid或者用手机号/邮箱映射。这里有一个非常容易踩的坑userid不是你在腾讯会议 App 上看到的昵称而是企业管理员在后台给用户分配的唯一标识或者是通过“用户管理”接口查询到的 userid。如果你直接用手机号去当主持人接口会报“用户不存在”。创建成功后接口会返回会议号、入会链接、主持人密钥等字段。你需要把join_url和meeting_code保存下来后续发飞书消息时就靠它们。我建议把腾讯会议的调用统一封装成一个服务模块举个例子class TencentMeetingClient: def create_meeting(self, subject, start_time, end_time, settingsNone): path /v1/meetings body { subject: subject, start_time: int(start_time), end_time: int(end_time), meeting_type: 0, settings: settings or {} } headers self.build_headers(POST, path, body) return self.request(POST, path, headersheaders, jsonbody)这样后面在飞书机器人逻辑里只需要调用这个客户端的方法代码会干净很多。3.4 查询会议、修改会议、获取录制文件除了创建会议日常对接还会用到两个接口查询会议详情GET /v1/meetings/{meeting_id}返回参会人列表、会议状态、开始/结束时间。获取会议录制文件GET /v1/records/{meeting_id}这里能拿到云录制地址、录制文件大小、上传时间等。这些接口配合飞书事件回调就可以实现“会议结束后自动归档”。但录制文件有一个前提会议必须开启了云录制且录制完成上传后接口才能查到。如果会议只是本地录制接口是拉不到录制文件的。当时我在做“会议纪归档”时发现录制状态的同步有明显延迟。会议刚结束马上调录制接口经常得到空列表。后来我在代码里加了重试机制会议结束事件到达后先等待约 5 到 10 分钟再轮询录制接口最多轮询三次取到录制文件后再写入飞书文档。4. 端到端落地飞书指令触发、会议创建、消息推送、结果归档4.1 服务端整体结构FastAPI Python 实现回调两端我的整体架构非常简单一个 FastAPI 服务开放两个路由/feishu/callback接收飞书事件回调和卡片回调。/tencent/callback接收腾讯会议事件回调。服务启动时我会加载飞书和腾讯会议的凭证配置。为了不把密钥写死在代码里我把它放到环境变量中并在服务启动时校验必填项import os APP_ID os.getenv(FEISHU_APP_ID) APP_SECRET os.getenv(FEISHU_APP_SECRET) TMEETING_CLIENT_ID os.getenv(TMEETING_CLIENT_ID) TMEETING_SECRET_ID os.getenv(TMEETING_SECRET_ID) TMEETING_SECRET_KEY os.getenv(TMEETING_SECRET_KEY) TMEETING_REG_ID os.getenv(TMEETING_REG_ID)注册 ID 这个字段很容易被忽略。腾讯会议开放平台要求调用某些 API 时带X-TC-RegisteredID也就是应用注册时生成的注册 ID。如果漏了这个参数接口会返回“缺少参数”或“鉴权失败”。整个服务的数据流是飞书群里有人 机器人发送“创建会议 15:00 需求评审” → 飞书事件回调到 FastAPI → FastAPI 解析指令 → 调用腾讯会议创建会议接口 → 成功后组装飞书消息卡片 → 调用飞书消息接口推送到群 → 用户点击“生成纪要” → 拉取腾讯会议录制 → 创建飞书云文档并写内容 → 再次推送卡片通知。4.2 飞书消息推送从获取 token 到发送卡片飞书发送消息前需要先换取tenant_access_token。这个 token 有有效期官方建议缓存起来不要每次请求都重新获取否则容易触发频率限制。代码逻辑大致是import requests def get_tenant_access_token(): url https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal payload {app_id: APP_ID, app_secret: APP_SECRET} resp requests.post(url, jsonpayload) data resp.json() return data.get(tenant_access_token)拿到 token 后调用“发送消息”接口这里我用的是消息接口中的交互卡片类型。卡片的 JSON 结构是飞书官方定义的可以直接套模板。我记得第一次发送卡片时卡片里放了多个按钮但按钮始终不显示。排查半天发现是卡片结构里elements层级写错了——飞书消息卡片分为header、elements两层按钮必须放在elements这个数组里不能放在顶层。这个如果照着官方文档写基本没问题但如果你是从网上找的旧代码很容易踩坑。4.3 腾讯会议事件回调配置公网地址、验签、处理会议状态腾讯会议的开放平台也支持配置事件回调比如会议开始、会议结束、参会人入会/离会等事件。这个回调是腾讯会议主动 POST 到你配置的地址上它和我们主动调用 API 是两条相反的链路。拿到这个回调之后可以做的事就更多了。比如会议开始时飞书群自动推送“会议已开始参会人 x 人”。会议结束时飞书群自动推送“会议已结束会议时长 xx 分钟”。有用户入会时飞书可以推送参会人昵称。腾讯会议事件回调的 URL 也需要公网可访问。回调解密逻辑与飞书不同腾讯会议是用 AES 加密的需要用应用密钥对event_data做解密。这一块官方文档给的是 Java 示例我团队里没有 Java 环境所以我用 Python 重写了一遍解密逻辑。当时发现腾讯会议回调的event_type大概有这些meeting.created会议创建。meeting.started会议开始。meeting.ended会议结束。participant.joined有参会者入会。participant.left有参会者离会。这些事件类型需要在腾讯会议开放平台的“事件订阅”里提前申请。申请后还要等审核不是配置完立刻生效。我一开始没配好以为回调没通后来才发现是事件订阅权限没通过审核。4.4 会议结束后自动生成飞书云文档串联“腾讯会议 飞书文档”会议结束后的归档是整个对接流程里最有价值的一环。腾讯会议创建时如果开启了云录制那么会议结束后会生成录制文件如果没有录制那么至少也能拿到会议的开始/结束时间以及参会人列表。我的文档生成逻辑是这样的收到meeting.ended回调等待 5 分钟。调用腾讯会议“获取会议录制文件”接口拿到录制地址。调用腾讯会议“获取参会成员列表”接口拿到参会人姓名、入会时间、离会时间。在飞书云文档中创建一个新文档使用“导入”接口写入内容。最后在群里推送一条消息卡片说明“会议纪要已生成”附带文档链接。飞书云文档创建接口在drive/v1/files需要开drive:drive权限。写入内容时可以用docx/blocks接口把 Markdown 或富文本内容转成飞书文档块。如果你不写代码也可以借助 Dify 这类工具去编排“会议结束后 → 生成文档”的流程但要注意 Dify 对接飞书云文档时第一步也是要解决授权凭证的问题。所谓“飞书云文档授权凭证”本质上就是让第三方应用拿到一个可以操作云空间的 token要么用user_access_token要么用tenant_access_token。前者需要管理员授权后者只需要企业自建应用权限。我更推荐后者因为它不依赖某个具体用户服务端随时可调用。5. 踩坑记录常见问题与排查思路5.1 腾讯会议 API 返回“签名校验失败”这个报错出现频率最高。排查步骤我整理成了一张速查表检查项具体说明Secret Key 是否正确注意区分 Client Secret 和 Secret Key签名用的是 Secret Keybody 原始字符串签名时用的 body 必须和实际请求发送的 body 完全一致包括属性顺序时间戳必须用秒级时间戳且时间偏差不能过大随机串 Nonce每个请求必须不同不能写死请求路径路径要带/v1/meetings不能只写域名RegisteredID部分接口必须带头部X-TC-RegisteredID如果你已经确认签名逻辑没问题建议在服务端打印出签名串对比官方文档里给出的示例拼接格式。很多时候不是算法错而是拼的字段顺序不对。5.2 创建会议报“主持人不存在”或“用户未注册”这个问题分为两种情况。第一种你传入的hosts.userid在腾讯会议后台不存在解决办法是先调用“用户管理”接口查一下这个用户是否被添加为企业成员。第二种你传的是手机号或邮箱但该用户没有绑定腾讯会议企业版也会报错。我当时测试时是用自己个人腾讯会议账号注册的开放平台应用然后在 hosts 里填了我自己的手机号怎么调都报错。后来换成企业版账号下的 userid 才成功。提醒一句开放平台 API 默认只支持企业版账号个人版会有很多限制。5.3 飞书回调地址验证不通过飞书在配置事件订阅时会发送 URL 验证请求要求服务端正确响应challenge字段。这里最容易出的问题有两个一个是服务端没有正确解析请求体中的challenge另一个是没有处理加密参数。飞书在“加密策略”里如果开启了“加密”事件请求体中的encrypt字段就是加密后的字符串需要先用 AES 解密再获取challenge。我建议开发初期先关闭加密等验证通过后再开启这样能少走弯路。5.4 消息卡片按钮没有反应按钮没有反应一般不是飞书的问题而是你的回调服务没有正确响应卡片的回调请求。飞书的卡片回调也走你配置的事件订阅地址通过type区分是普通消息事件还是卡片回调事件。如果你在代码入口处只处理了message类型的事件卡片回调就会被忽略。另外卡片回调要求在一定时间内响应成功如果响应超时飞书会认为失败并重试。建议把耗时的操作放到异步任务队列里快速响应飞书再慢慢处理业务逻辑。5.5 腾讯会议不能使用电脑自带摄像头不是对接问题但经常被一起问后面我注意到很多人搜“腾讯会议不能使用电脑自带摄像头吗”点进来看对接文章。这里也顺带说一下腾讯会议是支持电脑自带摄像头的如果在设置里看不到摄像头通常是以下原因腾讯会议的“视频设置”里选择了错误的摄像头设备。系统权限没有给腾讯会议摄像头访问权限尤其是 macOS 和 Win11。摄像头正被其他软件比如飞书视频会议占用腾讯会议无法同时调用。这个问题和 API 对接无关但确实是企业用户高频问题。如果你做的对接系统里集成了“一键入会”最好在帮助文档里也写清楚这个排查路径能节省大量答疑时间。6. 安全与权限这些细节决定企业能不能用6.1 密钥管理要严格不要硬编码飞书 App Secret、腾讯会议 Secret Key 都属于最高级别敏感信息。一旦泄露别人就能冒充你的应用创建会议、发送消息、读取录制文件。我的建议所有密钥放入环境变量或密钥管理服务不要提交到 Git。定期轮换密钥尤其是有人离职后。服务端日志里不要打印完整密钥和签名串。6.2 权限最小化只开当前需要的权限飞书自建应用的权限项很多不要图省事直接勾选“全部权限”。我建议按实际功能逐步开通。比如只做会议通知就不要开云文档权限要做纪要归档再单独开通drive相关权限。腾讯会议那边也是一样应用申请时选择所需的接口范围即可。6.3 频率限制与超时处理两边开放平台都有接口频率限制。飞书的 token 接口限制尤其明显如果不做缓存短时间大量请求会被限流。腾讯会议的会议创建接口也有 QPS 限制一般在几到几十之间对内部自动化场景完全够用。在代码层面我建议所有对腾讯会议的调用都加上重试机制。腾讯会议有些接口在极端情况下会返回超时或 500 错误特别是拉取录制文件这种异步生成的资源重试加等待基本能解决。6.4 Webhook 公网地址的保密性飞书和腾讯会议的回调地址如果被恶意请求打到会导致资源被频繁触发。建议在回调服务里校验来源 IP 白名单或者至少校验请求头中的签名信息拒绝不合法来源。腾讯会议回调可以用验签逻辑确认来源飞书回调可以用加密策略 自定义 header 校验。如果你只是跑内网服务可以再加一层网关鉴权。7. 我踩过几次坑之后的最终建议如果让我重新做一遍这个对接我会按以下顺序推进先画清楚“谁会发起会议、会议信息要流向哪里、会后要沉淀什么”业务链路比代码更重要。飞书侧先建好机器人打通“发消息到群”这条线。腾讯会议侧先手动调通“创建会议”接口确保签名没问题。再用事件回调串起“会议结束→通知飞书”的闭环。最后才是做飞书文档归档、卡片交互这些锦上添花的功能。这个顺序的好处是每一步都能独立验证定位问题快。我第一次做的时候一上来就打算把卡片、回调、文档归档全做完结果到处是问题根本不知道是飞书的问题还是腾讯会议的问题。拆开以后整个开发时间大概缩短了一半。最后分享一个非常实用的小技巧在飞书事件回调的服务入口把所有原始请求体打日志保留一周。不管是飞书还是腾讯会议它们的回调 payload 结构偶尔会更新出问题时查日志是最快的定位方式。我也因为提前留了日志好几次都在群里几分钟内定位到问题团队成员还以为是“高可用系统”做得好其实只是日志留得全而已。