飞书 - 腾讯会议对接实践这个话题最近问的人特别多。我在企业做内部工具集成时正好把这套流程完整走过一遍——从飞书机器人推送会议链接到腾讯会议API自动创建会议再到飞书云文档授权凭证的踩坑基本都遇到了。如果你也在搞类似的对接或者正准备从零开始做这篇应该能帮你少走不少弯路。先说清楚这个对接能解决什么实际问题。我见过太多团队开会前要在腾讯会议里手动创建会议然后复制会议号、密码再切到飞书群里粘贴发送。会议结束以后纪要和录屏又散落在各个地方。飞书和腾讯会议的对接本质上就是把这些重复动作自动化飞书侧负责触达和消息流转腾讯会议侧负责会议生命周期管理中间用API把两者串起来。适合谁看准备做企业内部工具集成的开发、运维或者在飞书上做自动化机器人的同学都可以参考。1. 对接前要先想清楚你到底要打通哪些环节1.1 先梳理工作流而不是一上来就调API很多人在对接时容易犯一个错误——打开开放平台文档就开始申请权限、写代码结果做到一半发现方案根本走不通。我建议你先画一条线从会议发起到会议结束中间有哪几个节点需要飞书参与。拿最典型的场景来说一条完整的会议生命周期大概是这样的发起人在飞书群里说一句明天下午三点开周会机器人自动在腾讯会议后台创建一场会议拿到会议号、入会链接、密码机器人把会议信息推送到飞书群并且在每个人日历里创建一个日程会前15分钟机器人再次提醒参会人会中有人需要录制或开启字幕机器人收到指令后调用腾讯会议API控制会后机器人拉取录制文件地址和纪要发回群里归档这个流程里有三个关键对接点会议创建与查询腾讯会议API、消息推送与日程写入飞书API、指令触发飞书机器人回调。想清楚这几个点再去翻文档就有的放矢了。1.2 三种主流对接路径怎么选我实测下来飞书与腾讯会议的对接大致有三条路可以走各有适用场景。第一种飞书机器人 腾讯会议开放API最推荐飞书机器人负责接收指令和发送消息腾讯会议开放平台提供REST API完成会议创建、查询、录制拉取。这种方式最灵活理论上可以实现会议全生命周期管理而且飞书侧不需要复杂的UI一个机器人加几个卡片就够了。第二种飞书小程序内嵌腾讯会议SDK如果你们对开会体验要求很高比如要在飞书内直接拉起腾讯会议客户端那就需要通过腾讯会议的JS-SDK配合飞书小程序容器来做。但这套方案有个前提——需要企业有自建应用的资质而且小程序审核流程相对长。如果只是内部使用没必要一上来就这么重。第三种只做链接跳转不做深度API也就是飞书机器人只负责发一个腾讯会议通用入会链接或者会议邀请链接用户点击后跳转到腾讯会议客户端。这种方案实现成本最低但没法自动创建专属会议也拿不到录制和纪要适合临时应急长期用会觉得很鸡肋。我的建议是如果你是第一次做从第一种方案入手先把核心链路跑通再按需扩展。2. 前置准备飞书应用和腾讯会议API的配置细节2.1 创建飞书应用并拿到身份凭证飞书这边的准备工作比较标准但有几个细节容易忽略。登录飞书开放平台open.feishu.cn进入开发者后台创建企业自建应用。创建时应用名称建议直接写成会议助手之类的业务名因为后面机器人发消息时这个名字会直接展示给用户。创建完成后你要在凭证与基础信息页面拿到两个关键参数App ID和App Secret。App ID相当于应用的身份证号App Secret相当于密码调用飞书API时用这两个参数换取tenant_access_token或user_access_token。这里有一个很多人第一次都会踩的坑飞书的权限不是默认开通的需要在权限管理里逐个申请。以会议对接场景为例你需要至少申请以下权限im:message:send_as_bot机器人发送消息calendar:calendar读写日历用于创建日程contact:user.base:readonly读取用户基本信息用于识别谁发的指令drive:drive访问云文档如果在纪要里要拉取飞书文档权限申请后不是立刻生效的需要发布应用版本并且如果是企业自建应用通常还要企业管理员审核通过。我之前就因为没发布版本调接口一直报权限错误排查了半天才发现是这个问题。2.2 开通腾讯会议企业API并配置JWT鉴权腾讯会议这边的对接入口是腾讯会议开放平台。注意个人版腾讯会议是没有开放API权限的必须是企业版或教育版并且需要在腾讯会议官网提交企业自建应用申请。审核通过后你会拿到一组App ID和App SecretSDK Key同时需要配置你的服务器IP白名单——腾讯会议API对来源IP有严格限制不在白名单内的请求会被拒绝。这个环节我建议提前确认好服务器出口IP别等到调接口时才去加白。腾讯会议API的鉴权方式用的是JWTJSON Web Token而不是简单的Access Token。每次请求前需要用你的App ID和App Secret生成一个JWT放到HTTP Header的X-TC-Key和X-TC-Token里。JWT的有效期默认是20分钟过期后需要重新生成。JWT生成的核心代码其实不长我习惯用Go写内部工具这里给一个Go的示例package main import ( fmt time github.com/golang-jwt/jwt ) func generateJWT(appID, secretID, secretKey string) string { now : time.Now() claims : jwt.MapClaims{ app_id: appID, iat: now.Unix(), exp: now.Add(20 * time.Minute).Unix(), secret_id: secretID, } token : jwt.NewWithClaims(jwt.SigningMethodHS256, claims) signed, err : token.SignedString([]byte(secretKey)) if err ! nil { panic(err) } return signed }如果你用PythonPyJWT库的写法也类似。这里有个重要提醒JWT的签名算法必须是HS256如果用了其他算法腾讯会议网关会直接拒绝。另外secret_id和secret_key是两个不同的值千万别只填了一个就跑去调试。2.3 飞书云文档授权凭证的获取方法这个点是近期被问得最多的因为很多人在用dify这类工具时第一次连接飞书云文档都会卡在授权凭证上。其实飞书的云文档授权走的是OAuth 2.0的标准流程核心是拿到user_access_token。流程是这样的在飞书开放平台配置重定向URI比如https://your-server.com/feishu/callback引导用户访问授权页面https://open.feishu.cn/open-apis/authen/v1/authorize?app_id你的AppIDredirect_uri重定向URIscopedrive:drive用户同意后飞书会重定向到你的回调地址并带上code参数用code换取user_access_token调用/open-apis/authen/v1/oidc/access_token接口这里有个技巧飞书的授权码有效期为5分钟而且只能用一次。换来的user_access_token有效期是2小时但可以结合refresh_token无限续期。所以在设计内部工具时一定要把refresh_token存好否则用户每两个小时就要重新授权一次体验很糟糕。注意云文档授权凭证和企业自建应用是绑定的如果你换了应用旧应用换来的token在新应用下是无效的。3. 核心实操把飞书机器人变成腾讯会议的遥控器3.1 场景一飞书消息触发自动创建腾讯会议先说最实用的一个场景用户往指定的飞书群里发一条创建会议 明天15:00 项目评审机器人自动在腾讯会议后台创建会议然后把会议信息推回群里。实现这个功能你需要两个核心接口调用飞书侧使用长连接模式WebSocket接收消息事件。在飞书开放平台为应用开启机器人能力并订阅im.message.receive_v1事件。推荐使用长连接而不是Webhook回调因为长连接不需要暴露公网回调地址内网部署时特别方便。腾讯会议侧调用创建会议接口POST https://api.meeting.qq.com/v1/meetings。请求体里需要传会议主题、开始时间、结束时间、会议类型等参数。这里有一个参数选择要注意——会议类型建议用预约会议别用快速会议。快速会议创建后默认立即开始而且有效期很短不适合预先安排日程的场景。请求体大致如下{ subject: 项目评审, type: 1, start_time: 1718359200, end_time: 1718362800, settings: { mute_enable: 1, allow_enter_before_host: 1, watermark: 1 } }创建成功后接口会返回meeting_id、meeting_code、join_url等字段。meeting_code就是我们常说的腾讯会议号用户可以通过会议号入会join_url是完整入会链接点击后直接唤起客户端。拿到这些信息后通过飞书机器人发送一条富文本消息或卡片消息到群里。我一般用interactive card把会议主题、时间、会议号、入会链接、密码等都放在卡片里参会人直接在卡片上点击加入会议就能跳转体验比复制粘贴会议号好太多。3.2 场景二机器人发送会议提醒和会后纪要自动创建会议只是第一步另一个高频需求是会前提醒 会后纪要归档。会前提醒的实现思路是在创建会议时同时往飞书日历创建一个日程并在日程里设置提醒。飞书日历API支持在event创建时设置reminder字段。如果你不想依赖日历也可以自己在服务端写一个定时任务在会议开始前固定时间比如15分钟调用飞书机器人API发送提醒消息。我在实际项目中用的是日历机器人双提醒方案日历负责系统级提醒机器人负责在群里发送带会议链接的消息。这样既不会漏提醒也能让还没进群的参会者通过群消息一键入会。会后纪要和录制文件的分发依赖腾讯会议的录制文件查询接口。会议结束后调用GET https://api.meeting.qq.com/v1/records?meeting_idxxx可以拉取录制文件列表包括录制地址、文件大小、录制时长等。腾讯会议录制转码一般需要几分钟所以建议在会议结束15分钟后再去拉取不然很容易拿到空列表。拿到录制链接后机器人再往群里发一张会议总结卡片内容包括会议回放链接、录制密码如果有、会议纪要文档链接。这里可以顺便对接飞书云文档——自动创建一篇会议纪要文档把参会人、会议时间、录制链接都整理好再把文档链接推群里。云文档的创建接口是POST /open-apis/docx/v1/documents创建后可以通过/open-apis/docx/v1/raw_content接口写入内容整个过程完全可以自动化。3.3 场景三会中控制与飞书卡片按钮交互如果你觉得机器人只能发消息还不够还可以把飞书卡片做成一个会议遥控器。通过卡片上的按钮参会人可以触发一系列会中控制操作比如全体静音调用腾讯会议接口PUT /v1/meetings/{meeting_id}/mute控制参会人麦克风开始录制调用POST /v1/meetings/{meeting_id}/record让云端录制立即开始结束会议调用PUT /v1/meetings/{meeting_id}/status把会议状态改为结束实现机制是飞书的卡片回传交互callback。用户在飞书里点击卡片按钮后飞书会把callback请求发到你的服务器如果使用长连接模式则通过事件推送。你的服务器根据按钮的value字段值调用对应的腾讯会议API完成操作后再更新卡片状态。这里要特别提醒一点敏感操作要在服务端做二次鉴权。因为飞书卡片按钮是任何人都能点的如果不校验点击者身份开会时可能被无关人员误操作直接把会议结束了。我通常在卡片回传时解析open_id然后跟会议的创建者或管理员列表比对不在白名单内直接拒绝。3.4 如果遇到腾讯会议不能使用电脑自带摄像头多半是权限问题在对接过程中我收到过不少类似的反馈用飞书跳转腾讯会议时进入会议后摄像头不能使用提示未检测到摄像头或者直接黑屏。排查下来绝大多数情况根本不是API对接问题而是腾讯会议客户端的权限配置。腾讯会议在macOS和Windows上都需要摄像头权限。尤其是macOS系统设置里的隐私与安全性必须勾选腾讯会议对摄像头的访问权限。如果你是通过企业IT策略统一安装的腾讯会议有可能是MDM策略把摄像头权限禁用了这在Windows上更常见——组策略里禁用了摄像头的进程访问。还有一种情况是腾讯会议客户端启动时使用了兼容模式或者运行在虚拟机里。虚拟机的摄像头透传没配置好时腾讯会议检测不到宿主机的摄像头设备。如果你是在Windows虚拟机里测试飞书跳转可以先在腾讯会议设置里手动切换摄像头设备试试如果列表为空基本可以断定就是虚拟机的摄像头映射问题。代码层面确认一下在创建会议时腾讯会议API有个settings.auto_record和mute_enable之类的设置项但没有强制开启参会人摄像头的选项——设备权限完全由客户端本地控制服务端管不了。所以网上流传的修改API参数开启摄像头的说法不成立。4. 常见问题与排查实录4.1 飞书机器人消息发送失败遇到机器人发消息不成功先从三个方向排查第一Token是否正确。飞书的tenant_access_token需要通过App ID和App Secret动态获取有效期2小时。我见过有人把token硬编码在代码里第二天跑挂了还不知道为什么。要写一个token缓存机制过期自动刷新。第二机器人是否在群内。飞书机器人只能往自己所在的群发消息。要把机器人拉进群否则调用接口回报invalid chat_id或者bot not in chat。这个错误在测试阶段特别容易踩。第三应用是否发布。自建应用开发完成后在开放平台后台需要点击创建版本并发布管理员审核通过后应用权限才真正生效。在测试企业里可以跳过审核但正式环境必须要走这套流程。4.2 腾讯会议API返回鉴权失败或无权限腾讯会议API的鉴权失败原因相对集中JWT过期或签名错误排查时先打印JWT的payload确认app_id和secret_id字段值服务器IP不在白名单。这个错误最容易让人困惑因为返回的错误信息可能是通用的鉴权失败不会明确告诉你IP不在白名单。解决方法是登录腾讯会议开放平台在应用详情里检查IP白名单配置调用接口时漏了X-TC-*自定义Header。腾讯会议要求请求头里同时带X-TC-Key和X-TC-Token缺一个都会鉴权失败此外腾讯会议API有QPS限制默认一般是每秒1次或2次。如果内部工具并发调用较多注意做一下请求限速或重试不然容易触发429 Too Many Requests。4.3 飞书云文档授权后立即失效这个问题在对接飞书云文档时出现频率极高。明明用户已经完成了授权页面上也确实拿到了code但用code换token时却报错。我排查过多次有几种典型原因授权码使用了错误的接口换取token。飞书有新旧两套接口老接口是/open-apis/authen/v1/access_token新接口是/open-apis/authen/v1/oidc/access_token。如果你创建应用时勾选了使用新版本就必须走OIDC接口。用错接口拿到的是无效token甚至会报invalid code。scope不匹配。授权时请求的scope和换取token时校验的scope必须一致。如果你在授权URL里只申请了contact:user.base:readonly但应用配置里还勾选了其他权限飞书在部分情况下会拒绝发token。重定向URI必须完全匹配。飞书对redirect_uri的校验是严格字符串匹配包括结尾的斜杠。https://example.com/callback和https://example.com/callback/在飞书看来是两个地址授权时如果带上了多余的斜杠就会失败。4.4 云文档上传或下载超时如果你在对接过程中需要把本地文件上传到飞书云空间或者把云文档下载到本地可能会遇到大文件超时的问题。飞书云盘API对文件上传限制了单文件大小超过20MB的文件必须用分片上传接口不能直接一次性上传。分片上传的流程是先初始化上传任务然后分片上传最后完成上传。每个分片建议控制在4MB左右这样在普通办公网络下比较稳定。一个小细节飞书云盘下载文件时如果文件比较大HTTP响应可能会很慢很多HTTP客户端默认没有设置读取超时时间直接超时了。我建议在下载接口设置至少120秒的读取超时而不是用默认的30秒。5. 一些实操中沉淀下来的经验最后分享几个我在实际项目中沉淀下来的经验不一定写在官方文档里但对排查问题很有用。关于事件订阅的选择飞书开放平台支持Webhook和长连接WebSocket两种事件接收方式。如果服务器有公网IP很多教程会推荐你配Webhook但我个人更推荐长连接。原因很简单长连接不需要在公网暴露回调地址也少配置一层签名校验部署在办公网内部就能直接用。飞书的长连接机制是服务端主动发起websocket连接你只需要在代码里启动一个接收服务然后到开放平台后台订阅事件即可非常省心。关于请求日志对接这类双平台系统最重要的一件事就是把两边的请求日志都留好。我习惯在每个关键接口调用时打一条结构化日志包含请求参数、返回结果、耗时。飞书侧和腾讯会议侧分别记录一旦出问题可以快速定位是哪一边出了问题而不是两边互相猜。联调排障的效率会成倍提升。关于测试环境的隔离如果你要对接的是正式企业环境强烈建议先在测试环境把整套流程跑通。腾讯会议开放平台支持创建一个测试企业飞书开放平台也有测试企业和沙箱环境。两边的测试环境相互独立而且接口限制比正式环境宽松很多。在测试环境里把会议创建、提醒、录制回传整条链路跑通再切正式环境会稳妥很多。飞书和腾讯会议的对接本质上就是三个环节触发、动作、反馈。触发可以是消息指令也可以是定时任务动作是调用腾讯会议API完成业务操作反馈是飞书机器人把结果送回给用户。把这三个环节想清楚剩下的就是照着API文档填参数的问题了。我个人的体会是与其追求一个大而全的集成平台不如从一个小而实用的自动化场景切入比如先让机器人帮你完成创建会议发通知这个动作跑顺了再逐步加录制归档、会中控制。这样每一步都有可见的成果排查问题也有边界不太容易陷入对接了一周还在原地的困境。
飞书与腾讯会议API对接实践：从机器人消息到会议自动化管理
飞书 - 腾讯会议对接实践这个话题最近问的人特别多。我在企业做内部工具集成时正好把这套流程完整走过一遍——从飞书机器人推送会议链接到腾讯会议API自动创建会议再到飞书云文档授权凭证的踩坑基本都遇到了。如果你也在搞类似的对接或者正准备从零开始做这篇应该能帮你少走不少弯路。先说清楚这个对接能解决什么实际问题。我见过太多团队开会前要在腾讯会议里手动创建会议然后复制会议号、密码再切到飞书群里粘贴发送。会议结束以后纪要和录屏又散落在各个地方。飞书和腾讯会议的对接本质上就是把这些重复动作自动化飞书侧负责触达和消息流转腾讯会议侧负责会议生命周期管理中间用API把两者串起来。适合谁看准备做企业内部工具集成的开发、运维或者在飞书上做自动化机器人的同学都可以参考。1. 对接前要先想清楚你到底要打通哪些环节1.1 先梳理工作流而不是一上来就调API很多人在对接时容易犯一个错误——打开开放平台文档就开始申请权限、写代码结果做到一半发现方案根本走不通。我建议你先画一条线从会议发起到会议结束中间有哪几个节点需要飞书参与。拿最典型的场景来说一条完整的会议生命周期大概是这样的发起人在飞书群里说一句明天下午三点开周会机器人自动在腾讯会议后台创建一场会议拿到会议号、入会链接、密码机器人把会议信息推送到飞书群并且在每个人日历里创建一个日程会前15分钟机器人再次提醒参会人会中有人需要录制或开启字幕机器人收到指令后调用腾讯会议API控制会后机器人拉取录制文件地址和纪要发回群里归档这个流程里有三个关键对接点会议创建与查询腾讯会议API、消息推送与日程写入飞书API、指令触发飞书机器人回调。想清楚这几个点再去翻文档就有的放矢了。1.2 三种主流对接路径怎么选我实测下来飞书与腾讯会议的对接大致有三条路可以走各有适用场景。第一种飞书机器人 腾讯会议开放API最推荐飞书机器人负责接收指令和发送消息腾讯会议开放平台提供REST API完成会议创建、查询、录制拉取。这种方式最灵活理论上可以实现会议全生命周期管理而且飞书侧不需要复杂的UI一个机器人加几个卡片就够了。第二种飞书小程序内嵌腾讯会议SDK如果你们对开会体验要求很高比如要在飞书内直接拉起腾讯会议客户端那就需要通过腾讯会议的JS-SDK配合飞书小程序容器来做。但这套方案有个前提——需要企业有自建应用的资质而且小程序审核流程相对长。如果只是内部使用没必要一上来就这么重。第三种只做链接跳转不做深度API也就是飞书机器人只负责发一个腾讯会议通用入会链接或者会议邀请链接用户点击后跳转到腾讯会议客户端。这种方案实现成本最低但没法自动创建专属会议也拿不到录制和纪要适合临时应急长期用会觉得很鸡肋。我的建议是如果你是第一次做从第一种方案入手先把核心链路跑通再按需扩展。2. 前置准备飞书应用和腾讯会议API的配置细节2.1 创建飞书应用并拿到身份凭证飞书这边的准备工作比较标准但有几个细节容易忽略。登录飞书开放平台open.feishu.cn进入开发者后台创建企业自建应用。创建时应用名称建议直接写成会议助手之类的业务名因为后面机器人发消息时这个名字会直接展示给用户。创建完成后你要在凭证与基础信息页面拿到两个关键参数App ID和App Secret。App ID相当于应用的身份证号App Secret相当于密码调用飞书API时用这两个参数换取tenant_access_token或user_access_token。这里有一个很多人第一次都会踩的坑飞书的权限不是默认开通的需要在权限管理里逐个申请。以会议对接场景为例你需要至少申请以下权限im:message:send_as_bot机器人发送消息calendar:calendar读写日历用于创建日程contact:user.base:readonly读取用户基本信息用于识别谁发的指令drive:drive访问云文档如果在纪要里要拉取飞书文档权限申请后不是立刻生效的需要发布应用版本并且如果是企业自建应用通常还要企业管理员审核通过。我之前就因为没发布版本调接口一直报权限错误排查了半天才发现是这个问题。2.2 开通腾讯会议企业API并配置JWT鉴权腾讯会议这边的对接入口是腾讯会议开放平台。注意个人版腾讯会议是没有开放API权限的必须是企业版或教育版并且需要在腾讯会议官网提交企业自建应用申请。审核通过后你会拿到一组App ID和App SecretSDK Key同时需要配置你的服务器IP白名单——腾讯会议API对来源IP有严格限制不在白名单内的请求会被拒绝。这个环节我建议提前确认好服务器出口IP别等到调接口时才去加白。腾讯会议API的鉴权方式用的是JWTJSON Web Token而不是简单的Access Token。每次请求前需要用你的App ID和App Secret生成一个JWT放到HTTP Header的X-TC-Key和X-TC-Token里。JWT的有效期默认是20分钟过期后需要重新生成。JWT生成的核心代码其实不长我习惯用Go写内部工具这里给一个Go的示例package main import ( fmt time github.com/golang-jwt/jwt ) func generateJWT(appID, secretID, secretKey string) string { now : time.Now() claims : jwt.MapClaims{ app_id: appID, iat: now.Unix(), exp: now.Add(20 * time.Minute).Unix(), secret_id: secretID, } token : jwt.NewWithClaims(jwt.SigningMethodHS256, claims) signed, err : token.SignedString([]byte(secretKey)) if err ! nil { panic(err) } return signed }如果你用PythonPyJWT库的写法也类似。这里有个重要提醒JWT的签名算法必须是HS256如果用了其他算法腾讯会议网关会直接拒绝。另外secret_id和secret_key是两个不同的值千万别只填了一个就跑去调试。2.3 飞书云文档授权凭证的获取方法这个点是近期被问得最多的因为很多人在用dify这类工具时第一次连接飞书云文档都会卡在授权凭证上。其实飞书的云文档授权走的是OAuth 2.0的标准流程核心是拿到user_access_token。流程是这样的在飞书开放平台配置重定向URI比如https://your-server.com/feishu/callback引导用户访问授权页面https://open.feishu.cn/open-apis/authen/v1/authorize?app_id你的AppIDredirect_uri重定向URIscopedrive:drive用户同意后飞书会重定向到你的回调地址并带上code参数用code换取user_access_token调用/open-apis/authen/v1/oidc/access_token接口这里有个技巧飞书的授权码有效期为5分钟而且只能用一次。换来的user_access_token有效期是2小时但可以结合refresh_token无限续期。所以在设计内部工具时一定要把refresh_token存好否则用户每两个小时就要重新授权一次体验很糟糕。注意云文档授权凭证和企业自建应用是绑定的如果你换了应用旧应用换来的token在新应用下是无效的。3. 核心实操把飞书机器人变成腾讯会议的遥控器3.1 场景一飞书消息触发自动创建腾讯会议先说最实用的一个场景用户往指定的飞书群里发一条创建会议 明天15:00 项目评审机器人自动在腾讯会议后台创建会议然后把会议信息推回群里。实现这个功能你需要两个核心接口调用飞书侧使用长连接模式WebSocket接收消息事件。在飞书开放平台为应用开启机器人能力并订阅im.message.receive_v1事件。推荐使用长连接而不是Webhook回调因为长连接不需要暴露公网回调地址内网部署时特别方便。腾讯会议侧调用创建会议接口POST https://api.meeting.qq.com/v1/meetings。请求体里需要传会议主题、开始时间、结束时间、会议类型等参数。这里有一个参数选择要注意——会议类型建议用预约会议别用快速会议。快速会议创建后默认立即开始而且有效期很短不适合预先安排日程的场景。请求体大致如下{ subject: 项目评审, type: 1, start_time: 1718359200, end_time: 1718362800, settings: { mute_enable: 1, allow_enter_before_host: 1, watermark: 1 } }创建成功后接口会返回meeting_id、meeting_code、join_url等字段。meeting_code就是我们常说的腾讯会议号用户可以通过会议号入会join_url是完整入会链接点击后直接唤起客户端。拿到这些信息后通过飞书机器人发送一条富文本消息或卡片消息到群里。我一般用interactive card把会议主题、时间、会议号、入会链接、密码等都放在卡片里参会人直接在卡片上点击加入会议就能跳转体验比复制粘贴会议号好太多。3.2 场景二机器人发送会议提醒和会后纪要自动创建会议只是第一步另一个高频需求是会前提醒 会后纪要归档。会前提醒的实现思路是在创建会议时同时往飞书日历创建一个日程并在日程里设置提醒。飞书日历API支持在event创建时设置reminder字段。如果你不想依赖日历也可以自己在服务端写一个定时任务在会议开始前固定时间比如15分钟调用飞书机器人API发送提醒消息。我在实际项目中用的是日历机器人双提醒方案日历负责系统级提醒机器人负责在群里发送带会议链接的消息。这样既不会漏提醒也能让还没进群的参会者通过群消息一键入会。会后纪要和录制文件的分发依赖腾讯会议的录制文件查询接口。会议结束后调用GET https://api.meeting.qq.com/v1/records?meeting_idxxx可以拉取录制文件列表包括录制地址、文件大小、录制时长等。腾讯会议录制转码一般需要几分钟所以建议在会议结束15分钟后再去拉取不然很容易拿到空列表。拿到录制链接后机器人再往群里发一张会议总结卡片内容包括会议回放链接、录制密码如果有、会议纪要文档链接。这里可以顺便对接飞书云文档——自动创建一篇会议纪要文档把参会人、会议时间、录制链接都整理好再把文档链接推群里。云文档的创建接口是POST /open-apis/docx/v1/documents创建后可以通过/open-apis/docx/v1/raw_content接口写入内容整个过程完全可以自动化。3.3 场景三会中控制与飞书卡片按钮交互如果你觉得机器人只能发消息还不够还可以把飞书卡片做成一个会议遥控器。通过卡片上的按钮参会人可以触发一系列会中控制操作比如全体静音调用腾讯会议接口PUT /v1/meetings/{meeting_id}/mute控制参会人麦克风开始录制调用POST /v1/meetings/{meeting_id}/record让云端录制立即开始结束会议调用PUT /v1/meetings/{meeting_id}/status把会议状态改为结束实现机制是飞书的卡片回传交互callback。用户在飞书里点击卡片按钮后飞书会把callback请求发到你的服务器如果使用长连接模式则通过事件推送。你的服务器根据按钮的value字段值调用对应的腾讯会议API完成操作后再更新卡片状态。这里要特别提醒一点敏感操作要在服务端做二次鉴权。因为飞书卡片按钮是任何人都能点的如果不校验点击者身份开会时可能被无关人员误操作直接把会议结束了。我通常在卡片回传时解析open_id然后跟会议的创建者或管理员列表比对不在白名单内直接拒绝。3.4 如果遇到腾讯会议不能使用电脑自带摄像头多半是权限问题在对接过程中我收到过不少类似的反馈用飞书跳转腾讯会议时进入会议后摄像头不能使用提示未检测到摄像头或者直接黑屏。排查下来绝大多数情况根本不是API对接问题而是腾讯会议客户端的权限配置。腾讯会议在macOS和Windows上都需要摄像头权限。尤其是macOS系统设置里的隐私与安全性必须勾选腾讯会议对摄像头的访问权限。如果你是通过企业IT策略统一安装的腾讯会议有可能是MDM策略把摄像头权限禁用了这在Windows上更常见——组策略里禁用了摄像头的进程访问。还有一种情况是腾讯会议客户端启动时使用了兼容模式或者运行在虚拟机里。虚拟机的摄像头透传没配置好时腾讯会议检测不到宿主机的摄像头设备。如果你是在Windows虚拟机里测试飞书跳转可以先在腾讯会议设置里手动切换摄像头设备试试如果列表为空基本可以断定就是虚拟机的摄像头映射问题。代码层面确认一下在创建会议时腾讯会议API有个settings.auto_record和mute_enable之类的设置项但没有强制开启参会人摄像头的选项——设备权限完全由客户端本地控制服务端管不了。所以网上流传的修改API参数开启摄像头的说法不成立。4. 常见问题与排查实录4.1 飞书机器人消息发送失败遇到机器人发消息不成功先从三个方向排查第一Token是否正确。飞书的tenant_access_token需要通过App ID和App Secret动态获取有效期2小时。我见过有人把token硬编码在代码里第二天跑挂了还不知道为什么。要写一个token缓存机制过期自动刷新。第二机器人是否在群内。飞书机器人只能往自己所在的群发消息。要把机器人拉进群否则调用接口回报invalid chat_id或者bot not in chat。这个错误在测试阶段特别容易踩。第三应用是否发布。自建应用开发完成后在开放平台后台需要点击创建版本并发布管理员审核通过后应用权限才真正生效。在测试企业里可以跳过审核但正式环境必须要走这套流程。4.2 腾讯会议API返回鉴权失败或无权限腾讯会议API的鉴权失败原因相对集中JWT过期或签名错误排查时先打印JWT的payload确认app_id和secret_id字段值服务器IP不在白名单。这个错误最容易让人困惑因为返回的错误信息可能是通用的鉴权失败不会明确告诉你IP不在白名单。解决方法是登录腾讯会议开放平台在应用详情里检查IP白名单配置调用接口时漏了X-TC-*自定义Header。腾讯会议要求请求头里同时带X-TC-Key和X-TC-Token缺一个都会鉴权失败此外腾讯会议API有QPS限制默认一般是每秒1次或2次。如果内部工具并发调用较多注意做一下请求限速或重试不然容易触发429 Too Many Requests。4.3 飞书云文档授权后立即失效这个问题在对接飞书云文档时出现频率极高。明明用户已经完成了授权页面上也确实拿到了code但用code换token时却报错。我排查过多次有几种典型原因授权码使用了错误的接口换取token。飞书有新旧两套接口老接口是/open-apis/authen/v1/access_token新接口是/open-apis/authen/v1/oidc/access_token。如果你创建应用时勾选了使用新版本就必须走OIDC接口。用错接口拿到的是无效token甚至会报invalid code。scope不匹配。授权时请求的scope和换取token时校验的scope必须一致。如果你在授权URL里只申请了contact:user.base:readonly但应用配置里还勾选了其他权限飞书在部分情况下会拒绝发token。重定向URI必须完全匹配。飞书对redirect_uri的校验是严格字符串匹配包括结尾的斜杠。https://example.com/callback和https://example.com/callback/在飞书看来是两个地址授权时如果带上了多余的斜杠就会失败。4.4 云文档上传或下载超时如果你在对接过程中需要把本地文件上传到飞书云空间或者把云文档下载到本地可能会遇到大文件超时的问题。飞书云盘API对文件上传限制了单文件大小超过20MB的文件必须用分片上传接口不能直接一次性上传。分片上传的流程是先初始化上传任务然后分片上传最后完成上传。每个分片建议控制在4MB左右这样在普通办公网络下比较稳定。一个小细节飞书云盘下载文件时如果文件比较大HTTP响应可能会很慢很多HTTP客户端默认没有设置读取超时时间直接超时了。我建议在下载接口设置至少120秒的读取超时而不是用默认的30秒。5. 一些实操中沉淀下来的经验最后分享几个我在实际项目中沉淀下来的经验不一定写在官方文档里但对排查问题很有用。关于事件订阅的选择飞书开放平台支持Webhook和长连接WebSocket两种事件接收方式。如果服务器有公网IP很多教程会推荐你配Webhook但我个人更推荐长连接。原因很简单长连接不需要在公网暴露回调地址也少配置一层签名校验部署在办公网内部就能直接用。飞书的长连接机制是服务端主动发起websocket连接你只需要在代码里启动一个接收服务然后到开放平台后台订阅事件即可非常省心。关于请求日志对接这类双平台系统最重要的一件事就是把两边的请求日志都留好。我习惯在每个关键接口调用时打一条结构化日志包含请求参数、返回结果、耗时。飞书侧和腾讯会议侧分别记录一旦出问题可以快速定位是哪一边出了问题而不是两边互相猜。联调排障的效率会成倍提升。关于测试环境的隔离如果你要对接的是正式企业环境强烈建议先在测试环境把整套流程跑通。腾讯会议开放平台支持创建一个测试企业飞书开放平台也有测试企业和沙箱环境。两边的测试环境相互独立而且接口限制比正式环境宽松很多。在测试环境里把会议创建、提醒、录制回传整条链路跑通再切正式环境会稳妥很多。飞书和腾讯会议的对接本质上就是三个环节触发、动作、反馈。触发可以是消息指令也可以是定时任务动作是调用腾讯会议API完成业务操作反馈是飞书机器人把结果送回给用户。把这三个环节想清楚剩下的就是照着API文档填参数的问题了。我个人的体会是与其追求一个大而全的集成平台不如从一个小而实用的自动化场景切入比如先让机器人帮你完成创建会议发通知这个动作跑顺了再逐步加录制归档、会中控制。这样每一步都有可见的成果排查问题也有边界不太容易陷入对接了一周还在原地的困境。
