先说个我最近被问得最多的事。团队内部用飞书管项目、拉群、发通知但开会统一走腾讯会议。日子一长运营同学天天手动复制会议链接往飞书群里贴“下午 3 点会议”这句人肉台词每天至少出现十次。更麻烦的是飞书日历里没有会议入口腾讯会议的预约记录也没法自动同步回飞书。搭建一套飞书和腾讯会议的对接服务让视频会议的预约、提醒、入会和后续归档都能自动流转就成了很多团队的刚需。这篇文章我打算把我实际跑通的对接方案完整写出来从权限准备、API 调用到消息卡片再到那些文档里不会写的坑一次讲清楚。适合负责企业内部工具集成的同学也适合正在做办公自动化、机器人通知开发的工程师参考。1. 对接这件事到底在对接什么1.1 两个产品的边界与“对接”的本质飞书的核心是企业协作消息、文档、日历、审批、多维表格它解决的是“信息怎么在组织里流动”。腾讯会议的核心是音视频会议预约、入会、录制、纪要它解决的是“人怎么在远程坐进同一个会议室”。这两个产品本身不是替代关系边界也不完全重叠重叠区集中在“日历事件”和“会议通知”这两块。飞书日历里可以建日程但日程本身不能直接生成腾讯会议腾讯会议可以预约会议但预约结果不会自动出现在飞书群里。于是团队只能靠人工在两个系统之间搬运信息搬运的成本在几十人的团队里还能忍到了几百人、上千人就完全失控了。所以“对接”这件事本质不是把两个产品合并也不是在某一个产品里模拟另一个产品的功能而是通过两边的开放 API在它们之间搭一条自动化的数据通道。这个通道要完成的核心动作就三个把会议预约信息从腾讯会议捞出来、把会议提醒推送到飞书、把用户的入会动作引导回腾讯会议。打个比方飞书是办公室前台腾讯会议是会议室。对接方案就是给前台装了一个“自动订会议室 自动发通知”的插件前台不用再扯着嗓子喊“哪位同事去开一下 3 楼的会议室”。1.2 先想清楚你要做轻量通知还是深度集成对接方案没有标准答案我建议你在动工之前先回答一个问题团队目前最痛的是哪一环如果只是“通知靠人肉转发、链接容易丢”那做一个轻量方案就够了后端定时任务或事件触发调腾讯会议 API 创建会议拿到入会链接后通过飞书机器人推送到群里用户点卡片上的按钮直接入会。这个方案开发量小一两天能跑通稳定性和维护成本都可控。如果团队还有更进一步的诉求比如想做到“飞书日历上建日程就自动生成腾讯会议”“会议结束后机器人自动把参会记录和纪要回传到群里”那就需要上深度集成。深度集成的关键在于打通两边的账号体系和事件回调开发量翻倍但日常使用体验也真的会好很多。对比维度轻量通知模式深度集成模式会议创建后端手动调用 API 创建飞书日历事件回调自动触发用户入会点卡片按钮打开链接链接自动写入日程日历直达会后数据无状态回传、纪要推送、录制文件归档开发量低中高适用团队先解决通知混乱追求日程/会议全链路自动化我的建议是没有特殊要求就别一上来就搞大而全。先把“自动创建 机器人通知”跑通团队立刻能感受到便利再根据反馈决定要不要继续往深度走。2. 开工前先把权限和凭证理清楚2.1 飞书侧创建一个企业自建应用飞书的开放能力都是挂在“应用”这个载体上的。你要做的第一步是登录飞书开放平台创建一个“企业自建应用”。这里强调一下一定要选“企业自建应用”不是“商店应用”因为只有自建应用才能拿到企业内部的数据权限和机器人能力。创建完成后需要在应用详情页里添加“机器人”能力。这一步别忽略很多同学把应用建好了却忘了开机器人能力后面调用消息 API 一直报错还以为是权限配置有问题。机器人能力开启后飞书会自动给这个应用生成一个机器人账号你可以把这个机器人拉进任意群。接下来是权限配置。飞书开放平台的权限点非常多如果不做裁剪审核流程会拖得很慢而且没必要。我实测下来做会议通知对接一般只需要这几类权限im:message发送消息的基础权限im:message:send_as_bot以机器人身份发送消息contact:user.base:readonly读取用户基础信息用于把用户姓名和飞书 open_id 做映射如果要做日历联动再加上calendar:calendar和calendar:calendar.event相关权限配置好权限之后还有一个非常容易踩的坑修改权限后必须在应用版本管理里“创建版本”并发布新权限才会生效。你光在权限页面勾选不发布版本API 调用时依然会报权限不足。我第一次对接时就被这个卡了半小时最后才发现是发布版本的流程没走完。最后在“凭证与基础信息”页面你能拿到两个关键凭证App ID 和 App Secret。这两个值要保存在服务端不要出现在前端代码或配置文件里。2.2 腾讯会议侧拿到企业应用的密钥腾讯会议开放平台的接入方式和飞书不太一样。飞书是创建应用后直接给 App ID / App Secret腾讯会议这边则要求你先有企业管理员账号在腾讯会议开放平台创建“企业自建应用”审核通过后才会给你 Client ID 和 Client Secret。这个过程看起来只是换个叫法实际上有一个很重要的区别腾讯会议的很多 API 要求调用者具备企业身份个人开发者账号能调用的接口非常有限。如果你所在的公司有腾讯会议企业版务必让管理员在开放平台完成企业认证否则后面创建会议的接口大概率会返回权限错误。拿到 Client ID 和 Client Secret 之后需要先换取 access_token。腾讯会议的 OAuth 流程和主流平台类似核心请求是这样的POST https://api.meeting.qq.com/v1/oauth2/access_token Content-Type: application/json { client_id: your_client_id, client_secret: your_client_secret, grant_type: client_credentials }这里有个细节要注意腾讯会议的 access_token 有效期默认是 120 分钟。理论上过期后需要重新获取但实际开发时不可能每次都现拿现用必须做一个 token 缓存比如存到 Redis 或内存里快过期时再刷新避免高频调用被打回。另外腾讯会议在调用业务接口时有一套自己的签名机制Header 里需要带X-TC-Key、X-TC-Nonce、X-TC-Timestamp、X-TC-Signature这几个参数。签名算法本身不复杂但拼接顺序和编码细节很容易搞错。我强烈建议直接拉官方提供的 SDK 来生成签名别手写。手写签名这个坑我至少见过三个人栽进去最后都是换 SDK 解决的。3. 实战让飞书机器人自动创建会议并推送到群3.1 先定数据流整个对接的数据流先把它画清楚后面写代码才不会乱。触发源 → 后端服务 → 腾讯会议 API → 后端组装消息卡片 → 飞书 API → 目标群我实际用的方案是一个 Python 后端服务提供 HTTP 接口给内部系统触发。触发方式有两种一种是定时任务每天上午扫一遍当天需要开的会议自动创建并发送提醒另一种是飞书群里的指令用户在群里发送特定关键词机器人响应并创建会议。如果你只需要跑通流程先从第一种开始代码简单调试也方便。这个后端服务相当于一个中间翻译层同时对接两个平台。建议把所有 API 调用封装成独立模块不要散落在业务代码里后面出了问题也好排查。3.2 获取飞书 tenant_access_token飞书的消息接口用的是tenant_access_token这是应用级别的 token不涉及具体用户授权。获取方式很简单import requests import json APP_ID your_app_id APP_SECRET your_app_secret def get_tenant_access_token(): url https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal headers {Content-Type: application/json; charsetutf-8} payload { app_id: APP_ID, app_secret: APP_SECRET } response requests.post(url, headersheaders, jsonpayload) data response.json() if data.get(code) ! 0: raise Exception(f获取 tenant_access_token 失败: {data}) return data[tenant_access_token]这个 token 的有效期通常是 2 小时和腾讯会议那边一样建议缓存起来不要每次发送都重新获取。我在生产环境里是把它放到 Redis 里带上过期时间调用前先检查缓存没有或快过期才重新请求。3.3 调腾讯会议 API 创建会议拿到腾讯会议的 access_token 之后就可以创建会议了。我个人习惯先把官方 SDK 初始化好避免手写签名下面代码以官方 Python SDK 的调用方式为例from tencentcloud.common import credential from meeting import MeetingClient # 初始化客户端 cred credential.Credential(client_id, client_secret) client MeetingClient(cred) # 定义会议参数 meeting_param { topic: 产品周会-飞书对接测试, start_time: 1743753600, # 注意这里是 Unix 秒级时间戳 end_time: 1743757200, media_type: 1, # 1: 视频会议 meeting_type: 0, # 0: 预约会议 userid: zhangsan, # 会议创建者在腾讯会议侧的用户 ID settings: { mute_enable: 1, watermark: 1 } } meeting client.create_meeting(meeting_param)创建成功后响应里会返回几个容易混淆的字段这里重点说一下meeting_id会议的唯一标识是系统内部的 ID一串数字meeting_code入会号码也就是用户在腾讯会议客户端里输入的那串数字join_url入会链接用户点开可以直接跳转给用户展示的时候应该用meeting_code和join_url不要把meeting_id直接发到群里。meeting_id是给程序用的发给用户没有任何意义反而会让用户误以为这是入会号码。还有一个容易忽略的点start_time和end_time必须是 Unix 秒级时间戳并且是 UTC 时间。国内业务一般用的是北京时间 UTC8你在组装时间戳时一定要先做时区转换否则创建的会议时间会和预期差 8 个小时。这个坑我踩过当时参会人收到的会议时间是凌晨 2 点群里一片问号。3.4 构造飞书消息卡片并发出会议创建成功之后下一步就是把会议信息以卡片的形式发到飞书群里。飞书的卡片消息功能很强大可以展示结构化信息还可以带交互按钮。我用的卡片结构是这样的{ config: { wide_screen_mode: true }, header: { title: { tag: plain_text, content: 会议提醒产品周会 }, template: blue }, elements: [ { tag: div, text: { tag: lark_md, content: **会议主题**产品周会-飞书对接测试\n**开始时间**2025-04-04 15:00\n**结束时间**2025-04-04 16:00 } }, { tag: div, text: { tag: lark_md, content: **入会号码**123 456 789\n**入会密码**1234 } }, { tag: action, actions: [ { tag: button, text: { tag: plain_text, content: 一键入会 }, type: primary, url: https://meeting.tencent.com/dm/xxxxx } ] } ] }构造好卡片之后调用飞书的消息发送接口import requests def send_group_message(tenant_access_token, chat_id, card_content): url https://open.feishu.cn/open-apis/im/v1/messages?receive_id_typechat_id headers { Authorization: fBearer {tenant_access_token}, Content-Type: application/json; charsetutf-8 } payload { receive_id: chat_id, msg_type: interactive, content: json.dumps(card_content, ensure_asciiFalse) } response requests.post(url, headersheaders, jsonpayload) data response.json() if data.get(code) ! 0: raise Exception(f发送飞书消息失败: {data}) return data这里有一个非常关键的细节content字段必须是 JSON 字符串不能直接传 dict更不能把 dict 塞进去让 requests 帮你序列化。我见过很多新手在这里报错提示 content 格式不对就是因为json.dumps这一步漏了。另外chat_id不是群名称也不是群的 URL它是飞书内部为每个会话分配的唯一 ID。获取方式有两种一种是在飞书开放平台的“调试台”里选择对应的群直接复制 chat_id另一种是通过 API 拉取机器人所在的群列表。第一种方式在开发阶段最方便。3.5 进阶联动日历事件触发与状态回传如果你想让体验再进一步可以考虑日历联动。飞书开放平台支持事件订阅你可以配置一个回调地址接收calendar.event.created事件。当用户在飞书日历里新建日程时你的后端服务会收到一个回调这时候自动调腾讯会议 API 创建会议再把join_url写回日程的 description 或 location 字段用户点开飞书日程就直接进入会议。这个联动方案的配置要点是在飞书开放平台的应用详情里开通“事件订阅”配置请求地址 URL同时系统会让你填一个 Encrypt Key 和 Verification Token。启用加密后所有回调内容都会用 AES 加密你需要用官方 SDK 解密。不要自己造轮子去解直接用飞书提供的加解密库省心很多。会议结束后的状态回传可以做得简单一点不需要监听腾讯会议的实时状态而是让机器人定时查询当天创建的会议列表如果会议状态变更为“已结束”就往群里发一条总结卡片附上会议时长和参会人数。这样既不用复杂的事件订阅又能让团队看到会议的完整闭环。4. 实测中会踩的坑问题与排查技巧4.1 飞书侧最容易翻车的三个地方第一个坑是“权限发布版本没更新”。飞书的权限调整必须通过创建新版本并发布才能生效。很多人改了权限之后发现 API 还是报权限错误多半就是漏了这一步。解决办法很简单去应用详情页的“版本管理与发布”里创建版本提交发布等审核通过后权限才会真正放开。第二个坑是“回调验签失败”。配置事件订阅时如果开启了 Encrypt Key回调请求会带上加密的加密字符串你必须在收到请求后先用 AES 解密才能拿到真实的事件 JSON。很多同学在本地测试时用 ngrok 暴露一个 HTTP 服务结果发现飞书后台一直提示“回调验证失败”原因不是服务没起来而是没有正确处理加密逻辑。建议直接用官方 SDK 里提供的解密方法不要自己折腾。第三个坑是“chat_id 和 open_id 混淆”。飞书的receive_id_type参数支持chat_id、open_id、user_id等几种类型传错类型或传错 ID消息都发不出去。开发阶段最简单的方式是在飞书群里添加机器人后调用群列表接口拉取chat_id不要手动去复制聊天链接里的数字。4.2 腾讯会议侧的签名与 token 坑腾讯会议的签名机制是让很多开发者头疼的地方。每次请求都要在 Header 里带上X-TC-Key、X-TC-Nonce、X-TC-Timestamp、X-TC-Signature签名算法要求把请求方法、路径、参数按特定规则拼接后做 HMAC-SHA256 加密。拼接顺序稍微错一位服务端就会返回签名校验失败。我建议你直接使用腾讯会议开放平台提供的 SDK因为 SDK 已经帮你处理了签名逻辑。如果你非要手写签名请务必把官方文档里的示例跑通之后再改参数不要直接用真实的 client_id 去试否则会被验证错误误导分不清是参数问题还是签名问题。access_token 的情况前面提过有效期 120 分钟。实际开发中如果你的服务是常驻进程建议把 token 缓存在内存或 Redis 里。如果服务重启了token 缓存清空重新请求一次即可。这里提一个容易忽略的点腾讯会议的 access_token 获取接口有频率限制别在每次创建会议时都去请求新的 token否则会触发限流返回 429 错误。4.3 时间、时区与编码细节时间问题是这次对接里最容易忽视又最容易出事的细节。腾讯会议 API 接收的时间戳是 Unix 秒而且是 UTC 时间。国内团队如果直接把本地时间转成时间戳会发现会议创建成功后显示时间提前或推后 8 小时。解决办法是先从日历或表单里拿到会议开始时间的 datetime 对象明确它是Asia/Shanghai时区再调用.timestamp()方法转换成 Unix 时间戳。反过来从腾讯会议响应里读时间戳时要先转成 UTC datetime再显示成北京时间。编码方面腾讯会议返回的join_url是经过 URL 编码的长链接如果你要把它拼进飞书卡片的url字段建议先用unquote解码一次再拼接个别情况下飞书会对超长 URL 做截断导致点击后打不开。4.4 常见问题速查表现象可能原因排查方向飞书 API 提示权限不足权限变更后未发布新版本检查应用版本管理与发布机器人无法发送消息到群机器人未添加到群或未开通机器人能力检查应用是否启用机器人是否拉机器人进群飞书回调验签失败Encrypt Key 未解密或验签逻辑错误使用官方 SDK 解密检查回调地址是否公网可达腾讯会议返回 401access_token 过期或签名错误检查 token 缓存和签名头参数腾讯会议会议时间差 8 小时时间戳时区未转换明确时区后转 Unix 时间戳卡片按钮点击后无法打开链接URL 编码问题或链接被截断解码后拼接优先用短链接创建会议提示 userid 无效用户在腾讯会议侧不存在检查腾讯会议通讯录与飞书用户映射4.5 断点排查的实战方法两个系统联调最怕的就是两边都报错不知道先查哪边。我实际用的方法是先在日志里把两个 API 的请求和响应完整打印出来然后单独验证每一个平台。具体顺序是先用腾讯会议开放平台的 API 调试工具把所有参数填好确认能成功创建会议并拿到join_url。这一步不依赖你的代码能快速定位问题是在参数上还是签名上。确认腾讯会议侧没问题后再用飞书开放平台的调试台先发一条纯文本消息到测试群确认机器人和权限都正常。两边各自通了再联调中间的逻辑排查效率会高很多。如果你用的是 Python建议在每次调用第三方 API 的地方都加一条日志记录请求地址、请求头和返回体。对接初期日志越详细越好等稳定了再减少日志输出。我在生产环境里保留了完整日志线上出问题时排查起来非常舒服。写在最后飞书和腾讯会议的对接本质上做的就是“信息搬运自动化”这件事。跑通之后团队不用再手动复制会议链接决策信息能更快地同步到每个相关人员手里这种变化是肉眼可见的。我自己的体会是刚起步别贪多。先把“自动创建会议 机器人通知”跑通团队立刻能感受到便利“以后不用复制链接了”这种反馈比任何指标都直接。跑顺了再加日历联动、会后纪要回传一步一步来系统才会越用越顺手。还有一点接口文档看再多也不如先调通一个最简单的发消息接口有了第一个成功请求后面的路会顺很多。