企业官网建设流程全解析

"飞书 - 腾讯会议对接实践"这个话题，最近问的人特别多。我在企业做内部工具集成时，正好把这套流程完整走过一遍——从飞书机器人推送会议链接，到腾讯会议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 Secret（SDK Key），同时需要配置你的服务器IP白名单——腾讯会议API对来源IP有严格限制，不在白名单内的请求会被拒绝。这个环节我建议提前确认好服务器出口IP，别等到调接口时才去加白。

腾讯会议API的鉴权方式用的是JWT（JSON 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 }

如果你用Python，PyJWT库的写法也类似。这里有个重要提醒：JWT的签名算法必须是HS256，如果用了其他算法，腾讯会议网关会直接拒绝。另外，secret_id和secret_key是两个不同的值，千万别只填了一个就跑去调试。

2.3 飞书云文档授权凭证的获取方法

这个点是近期被问得最多的，因为很多人在用dify这类工具时，第一次连接飞书云文档都会卡在授权凭证上。其实飞书的云文档授权走的是OAuth 2.0的标准流程，核心是拿到user_access_token。

流程是这样的：

1. 在飞书开放平台配置重定向URI，比如https://your-server.com/feishu/callback
2. 引导用户访问授权页面：https://open.feishu.cn/open-apis/authen/v1/authorize?app_id=你的AppID&redirect_uri=重定向URI&scope=drive:drive
3. 用户同意后，飞书会重定向到你的回调地址，并带上code参数
4. 用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_id=xxx可以拉取录制文件列表，包括录制地址、文件大小、录制时长等。腾讯会议录制转码一般需要几分钟，所以建议在会议结束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文档填参数的问题了。

我个人的体会是，与其追求一个大而全的"集成平台"，不如从一个小而实用的自动化场景切入，比如先让机器人帮你完成"创建会议+发通知"这个动作，跑顺了再逐步加录制归档、会中控制。这样每一步都有可见的成果，排查问题也有边界，不太容易陷入"对接了一周还在原地"的困境。