飞书机器人接入演示Demo：自动回复客户私有化部署等咨询问题

做销售演示Demo时遇到一个很典型的问题：客户在飞书群里问了一句“你们支持私有化部署吗？”，我嘴上说着“稍等我查一下”，手上疯狂翻报价表和PPT，翻了两分钟群里已经冷场了。后来我干脆做了一个带飞书机器人接入的Demo，让客户把话题发到群里，机器人自动从预设的知识库或者飞书多维表格里把查询结果回复出来。这个方案实测下来很稳，客户体验也直接拉满，顺手把这条链路的完整做法和踩过的坑都整理出来。

这篇文章适合两类人：一类是做售前、产品和销售支持，想在自己Demo里加一个“会说话”的交互环节；另一类是开发者，想低成本做一个飞书问答机器人，接收客户话题并自动回复查询结果。全文从场景拆解到代码实现再到排错经验，全部按可落地标准来写。

1. 项目拆解：一个会自己查数据的飞书机器人需要什么

1.1 场景复盘：客户话题从哪来，查询结果回哪去

先把这个标题拆开看，核心需求其实就一句话：客户在飞书上抛出一个话题，我们的Demo要接住它，去某个地方查出结果，再把结果回复给客户。话题千变万化，但常见的有几类：价格、部署方式、开放接口、定制能力、试用方式。回复的结果也不一定是纯文本，有可能是报价单、产品参数对比表、甚至是多维表格的链接。

我当时的做法是先画了一条链路：飞书客户端发消息 -> 飞书服务器把消息事件推送到我们的回调地址 -> Demo程序解析消息内容 -> 根据话题关键词去查询数据 -> 调用飞书消息API回复结果。拆成四个环节后再逐一实现，思路就清晰了。每个环节都不复杂，但连起来容易出问题，尤其是配置和权限环节，后面单独讲。

1.2 技术选型：为什么用飞书机器人而不是自建App

有人会问，做一个网页版Demo查数据库不就行了，为什么非要接飞书群？答案是演示场景不一样。客户在使用过程中，大概率是待在自己的IM工具里提问的，你让他在浏览器里打开一个Demo页面，再输入问题，这中间已经多了一层跳转。把查询能力直接放到飞书群里，客户只需要像平时聊天一样说话，机器人就给结果，这几乎是零门槛体验。

对比企业微信和钉钉，飞书开放平台有两个特别适合做Demo的点：一是事件订阅机制很完善，消息回调、加群事件、机器人被@都能订阅到；二是多维表格的API很开放，可以把查询数据源直接做成一张在线表格，业务同学自己就能改数据。这些能力组合起来，正好覆盖了一个“接收话题并回复查询结果”的Demo所有需求。当然企业微信、钉钉也能做，但飞书把开发者体验做得更顺，尤其是回调调试这一块，有现成的调试台可以直接模拟事件。

1.3 整体架构与数据流

实际代码跑起来之后，整个数据流是这样的：

飞书客户端发消息给机器人，飞书后台会把一个JSON事件POST到开发者配置的Webhook地址。Demo程序收到事件后，先判断消息类型是不是text，然后从content字段里取出用户发的文本。接着做话题识别，最简单的做法是关键词匹配，也可以接一个本地问答库或者一张多维表格。查询到结果后，Demo拿着tenant_access_token调用飞书的消息API，把结果发回对应的chat_id。这个过程中，Demo本身是一个常驻的HTTP服务，每次消息进来都是独立处理，无状态，非常好调试。

这种架构最大的好处是灵活。数据源可以是本地JSON、SQLite、MySQL或飞书多维表格，替换成本很低。回复形式可以是文本、消息卡片，甚至发送附件。后面我在进阶玩法里会展开演示现场最加分的几种用法。

2. 开发前的准备：创建应用、开权限、配事件（这步最容易被卡住）

2.1 在飞书开放平台创建一个应用

开发第一步是在飞书开放平台后台创建一个企业自建应用。入口在开发者后台的“创建应用”里，类型选择企业自建应用。创建完成后，会拿到两个关键凭证：App ID和App Secret。App ID是应用的唯一标识，App Secret是调用API时的密钥，二者都要保存好。尤其是App Secret，一定不能提交到Git仓库里，我习惯用环境变量去加载。

接下来在应用能力页里添加“机器人”能力，这一步相当于让这个应用变成了一个可以出现在聊天里的机器人。添加之后，机器人默认会出现在企业通讯录里，管理员可以把机器人拉进群，或者大家直接搜索到机器人发起单聊。飞书机器人的展示名称和头像建议提前设成正式的名称，演示的时候客户在群里看到的是“销售助手”这种名字，比看到一个“test_bot”印象分高很多。

2.2 权限配置：哪些权限必须开通

很多人在这一步被卡住，因为飞书的权限体系是按最小化原则设计的，你调哪个API就必须先申请对应的权限。做消息接收和回复，至少需要开三个。

表格列一下核心权限：

开通位置在“权限管理”页面，直接搜索权限标识然后开通。这里有两个容易忽略的细节。第一，权限开完之后不会立刻生效，需要创建一个应用版本并发布，等管理员审核通过之后，新权限才会生效。第二，如果只在自己企业测试，可以把自己加为应用的管理员，但发布流程还是得走一遍。我自己第一次调试时就是吃了这个亏，权限明明开了，调用API还是报权限错误，最后发现是版本没发布。

2.3 事件订阅与回调地址配置

事件订阅是接收客户消息的关键。在应用后台的“事件与回调”页面，添加一个事件：接收消息（im.message.receive_v1）。添加之后需要配置一个请求地址，也就是回调URL。这个URL必须是一个公网可以访问的HTTPS地址，本地开发时可以用内网穿透工具把本地的5000端口暴露成公网地址，也可以用一台云服务器来跑Demo。

配置回调地址时，飞书会发送一个challenge验证请求，你的回调接口收到这个请求后，需要把请求体里的challenge字段原样返回，格式是JSON。具体来说，飞书POST过来这样的数据：

{ "challenge": "ajls384kdjx98XX", "token": "xxxx", "type": "url_verification" }

我们的接口要返回：

{ "challenge": "ajls384kdjx98XX" }

这一步验证通过以后，事件订阅才算配成功。另外，事件回调里可以开启Encrypt Key加密，开启后所有回调消息体都会被加密，Demo代码里要增加解密逻辑。第一个Demo建议先不加密，跑通链路后再考虑加。

2.4 版本发布：改了配置不生效的根源

上面提到权限变更或者事件订阅调整后，都需要发布新版本才能生效。飞书的应用发布流程是：在“版本管理与发布”里创建版本，填写版本号和更新说明，然后提交审核。审核主体一般是自己企业的管理员，如果公司内部用，管理员通过很快。发布成功后的版本，权限、机器人能力、事件订阅配置才会真正作用于线上应用。

调试阶段还有个小技巧：可以在“事件调试”页面手动模拟一条消息事件，不经过真实聊天就推送到回调地址。这个功能非常省事，我第一次就是靠它确认了回调链路是通的。

3. 核心实现：从收到消息到回复结果的完整链路

3.1 环境准备与Demo目录结构

技术栈我选的是Python + Flask + requests，因为一套下来依赖很少，部署也简单。Python 3.10以上版本，两个pip包就够：

pip install flask requests

如果喜欢用飞书官方SDK，也可以装lark-oapi，但Demo阶段用requests直接把接口调起来，反而更容易理解每一步在干什么。

Demo的目录结构可以很精简：

feishu-demo/ ├── app.py # 主服务，事件入口 ├── config.py # 配置、问答库 ├── feishu_client.py # 飞书API封装 ├── requirements.txt ├── .env # App Secret等敏感配置（不要提交Git） └── README.md

3.2 回调服务骨架：先通过challenge验证

先写一个最简的Flask服务，接受飞书的事件POST，并处理challenge验证。

import json import os from flask import Flask, request, jsonify app = Flask(__name__) @app.route("/webhook/event", methods=["POST"]) def handle_event(): data = request.get_json(force=True) # 飞书验证回调地址 if data.get("type") == "url_verification": return jsonify({"challenge": data.get("challenge")}) # 打印事件内容，方便调试 print("收到事件：", json.dumps(data, ensure_ascii=False)) return jsonify({"code": 0, "msg": "success"}) if __name__ == "__main__": app.run(host="0.0.0.0", port=5000, debug=True)

这个服务启动后，先用内网穿透工具把5000端口暴露出去，然后把生成的HTTPS地址填到飞书的事件回调URL里，点击验证，如果challenge逻辑没问题，配置就能直接通过。这个极简版本跑通后，再开始加业务逻辑。

3.3 解析消息内容：从事件里取出客户话题

飞书推送的消息事件结构里，客户说的话在event.message.content字段中，但content是一串JSON字符串。text类型消息的内容形如：

{ "text": "你好，我想问一下价格" }

所以在代码里要先拿到event.message，判断message_type，再对content做json.loads，才能取到text字段。我的处理逻辑如下：

event = data.get("event", {}) message = event.get("message", {}) msg_type = message.get("message_type", "") chat_id = message.get("chat_id", "") if msg_type == "text": content = json.loads(message.get("content", "{}")) text = content.get("text", "").strip() # 此时text就是客户的话题

一个容易忽略的点是，群聊里如果客户是@机器人后再提问，text里会带上被@的机器人名字，比如“@销售助手 支持私有化吗”。这种情况要么在事件里读mentions字段清洗，要么用字符串替换把@的片段去掉。单聊场景没有这个问题，Demo阶段建议优先跑通单聊。

3.4 查询逻辑设计：关键词路由与兜底回复

“查询结果”背后需要一个数据源。Demo阶段我用最朴素的方式：一个Python字典当作问答库，再加一层关键词路由。结构清晰，客户也能理解。

QA_DATA = { "私有化部署": "我们支持私有化部署，支持Docker Compose和K8s两种方式，最小配置建议4核8G，交付周期约1周。", "价格": "基础版按年订阅，旗舰版支持私有化，具体报价可以找销售获取一份报价单。", "试用": "可以在官网申请14天试用，Demo环境也提供给客户体验。", "定制化": "支持界面、字段、审批流等模块的定制化开发，具体需要商务沟通范围。", } def query(text: str) -> str: """根据关键词匹配话题，返回查询结果""" if any(k in text for k in ["私有化", "部署", "私有"]): return QA_DATA["私有化部署"] if any(k in text for k in ["价格", "报价", "多少钱", "收费"]): return QA_DATA["价格"] if any(k in text for k in ["试用", "体验", "试一下"]): return QA_DATA["试用"] if any(k in text for k in ["定制", "定制化", "二次开发"]): return QA_DATA["定制化"] return "这个话题我还没收录，稍后我请同事来回复你。"

关键词的顺序是有讲究的，包含关系越强的词越要靠前。比如“私有化部署的价格”这句话，既命中了“私有化”，又命中了“价格”，实际业务里客户想表达的核心是价格，所以价格判断应该放在私有化后面，否则就会回复成部署信息。这属于演示前固定话术排序的经验活儿，可以先按“价格 > 定制 > 部署 > 试用”的优先级试一遍。

3.5 回复消息：用tenant_access_token调用API

查询到结果之后，需要把内容回复到同一个会话里。飞书开放平台发消息的链路是：先用App ID和App Secret换取tenant_access_token，再调用im/v1/messages接口发送。

获取token的接口：

def get_tenant_access_token(): resp = requests.post( "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", json={"app_id": APP_ID, "app_secret": APP_SECRET}, timeout=5, ) data = resp.json() return data.get("tenant_access_token")

token有效期默认两小时，可以通过expire字段判断，Demo阶段每次获取也没问题，因为够快。发送消息的接口：

def send_text(chat_id, text): token = get_tenant_access_token() body = { "receive_id": chat_id, "msg_type": "text", "content": json.dumps({"text": text}), } resp = requests.post( "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id", headers={"Authorization": f"Bearer {token}"}, json=body, timeout=5, ) return resp.json()

receive_id_type传chat_id，receive_id直接传事件里的chat_id，单聊和群聊都能覆盖，这是最简单的方式。

3.6 完整代码串起来：一条消息从收到到回复

把上面的逻辑拼起来，就是一个能跑的Demo。加粗提醒：发送消息这段是同步阻塞的，如果后续查询逻辑变重，建议把“处理+回复”放到子线程里执行，回调先马上返回HTTP 200，避免飞书那边认为超时。

import json import os import requests from flask import Flask, request, jsonify app = Flask(__name__) APP_ID = os.environ.get("APP_ID") APP_SECRET = os.environ.get("APP_SECRET") QA_DATA = { "私有化部署": "我们支持私有化部署，支持Docker Compose和K8s两种方式，最小配置建议4核8G，交付周期约1周。", "价格": "基础版按年订阅，旗舰版支持私有化，具体报价可以找销售获取一份报价单。", "试用": "可以在官网申请14天试用，Demo环境也提供给客户体验。", } def get_tenant_access_token(): resp = requests.post( "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", json={"app_id": APP_ID, "app_secret": APP_SECRET}, timeout=5, ) return resp.json().get("tenant_access_token") def send_text(chat_id, text): token = get_tenant_access_token() body = { "receive_id": chat_id, "msg_type": "text", "content": json.dumps({"text": text}), } resp = requests.post( "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id", headers={"Authorization": f"Bearer {token}"}, json=body, timeout=5, ) return resp.json() def query(text: str) -> str: if any(k in text for k in ["价格", "报价", "多少钱", "收费"]): return QA_DATA["价格"] if any(k in text for k in ["私有化", "部署", "私有"]): return QA_DATA["私有化部署"] if any(k in text for k in ["试用", "体验", "试一下"]): return QA_DATA["试用"] return "这个话题我还没收录，稍后我请同事来回复你。" @app.route("/webhook/event", methods=["POST"]) def handle_event(): data = request.get_json(force=True) if data.get("type") == "url_verification": return jsonify({"challenge": data.get("challenge")}) event = data.get("event", {}) message = event.get("message", {}) chat_id = message.get("chat_id", "") if message.get("message_type") == "text": content = json.loads(message.get("content", "{}")) text = content.get("text", "").strip() answer = query(text) send_text(chat_id, answer) return jsonify({"code": 0, "msg": "success"}) if __name__ == "__main__": app.run(host="0.0.0.0", port=5000, debug=True)

这个版本已经可以在真实飞书环境里跑通了。你可以用手机给机器人发一句“你们价格是多少”，几秒后就会收到回复。整个调试过程我强烈建议打开debug=True，把事件原文打印出来看一眼，很多解析问题一眼就能定位。

4. 进阶玩法：让查询结果变成一张表（这才是打动客户的关键）

4.1 用消息卡片发送结构化呈现

文本回复适合简短信息，但是当查询结果涉及多个产品、多个参数时，纯文本就会显得乱。飞书的消息卡片可以承载标题、列表、字段分组，观感上升一个档次。

发送卡片消息时，msg_type改成interactive，content字段放卡片的JSON字符串。比如查询“有哪些版本”，回复一张产品列表卡片：

def send_card(chat_id, title, items): token = get_tenant_access_token() elements = [] for item in items: elements.append({ "tag": "div", "text": { "tag": "lark_md", "content": f"**{item['name']}**\n{item['desc']}" } }) card = { "header": { "template": "blue", "title": {"tag": "plain_text", "content": title} }, "elements": elements } body = { "receive_id": chat_id, "msg_type": "interactive", "content": json.dumps(card), } resp = requests.post( "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id", headers={"Authorization": f"Bearer {token}"}, json=body, timeout=5, ) return resp.json()

飞书后台还有一个“卡片搭建工具”，可以拖拽生成卡片JSON再复制出来，非常方便。我第一次用这个工具把卡片样式调好后，直接复制JSON到代码里，省了很多试错时间。Demo演示时，这种卡片回复明显比一段文字更有产品感。

4.2 对接飞书多维表格：让数据源变成在线表格

如果希望Demo的查询数据能随时被业务同学修改，而不是每次都要改代码重启，可以把数据源切到飞书多维表格上。多维表格本质上就是一张在线数据库，飞书开放平台提供了读取记录的API。

在多维表格里建一张“产品知识库”表，字段可以设成：关键词、答复内容、分类。然后在开放平台把bitable:app权限开了，发布版本后，代码里按条件读记录：

def query_from_bitable(app_token, table_id, keyword): token = get_tenant_access_token() url = ( f"https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}" f"/tables/{table_id}/records?page_size=100" ) resp = requests.get( url, headers={"Authorization": f"Bearer {token}"}, timeout=5, ) items = resp.json().get("data", {}).get("items", []) for item in items: fields = item.get("fields", {}) if keyword in fields.get("关键词", ""): return fields.get("答复内容", "") return "没有找到对应结果。"

这一版的最大价值是：数据和逻辑分离了。业务同学直接改多维表格的行，Demo程序一秒钟都不用动，查到的就是最新内容。演示现场我甚至可以当着客户的面，在手机飞书里更新一行表格，然后告诉客户“你再问一遍试试”，这种即时的数据变化演示，效果比讲十页PPT都强。

4.3 演示现场的小设计：帮助菜单与转人工兜底

一个成熟的Demo不会只回答预设问题。我加了两个细节，现场反馈特别好。第一个是关键词“菜单”或者“帮助”触发功能菜单，用卡片把机器人能查的话题列出来，客户不用猜。第二个是当某个问题没有命中时，除了回复兜底文案，还会把这条消息记录到多维表格里，变成“待跟进问题”，这样客户在演示时随口抛出的问题也不会遗漏，反而成了销售跟进线索。

举个例子，收到“支持国外客户访问吗”这种没有预设答案的问题，回复里带上“查询耗时0.21秒”这种附加信息，然后自动把客户的问题和open_id记入一张“线索表”。这个细节看着小，但演示现场客户对“精准识别并自动沉淀”的感知非常强烈。

5. 常见问题与排查实录（踩坑合集）

5.1 回调验证失败：401/403和challenge

配置回调地址时报“请求网址验证失败”，是最常见的第一个坎。大概率是这几种情况：本地服务没启动，外网地址访问不到；或者接口里没有正确处理challenge；又或者返回的JSON格式里多了额外字段。飞书要求challenge原样返回，但很多人的接口误返回了整个请求体，导致校验不过。排查方法是先用内网穿透工具把本地端口暴露出去，浏览器直接访问回调URL，确认能通，再用curl模拟POST一个challenge请求到本地接口，看返回是否符合要求。

curl -X POST -H "Content-Type: application/json" \ -d '{"challenge":"test123","token":"abc","type":"url_verification"}' \ http://localhost:5000/webhook/event

如果本地返回的JSON里有“challenge”: “test123”，那就没问题。

5.2 机器人收不到消息又不能发消息

先确认机器人是否已经被拉进对应的群聊，或者客户是否在单聊里找到机器人。其次确认事件订阅是否添加了“接收消息”事件。还有一个很容易忽略的地方：事件回调地址配置成功后，飞书后台会有一个“事件订阅状态”的开关，有些配置是默认关闭推送的，需要手动开启。

发不出消息时的排查顺序：先看返回JSON里的code和msg，飞书API的错误码基本都能直接告诉你问题。常见的有两种：一种是没有发消息权限，对应权限没开通或者版本没发布；另一种是receive_id_type不对，在单聊里误用了chat_id类型，导致找不到会话。建议先把返回结果完整打印出来，再根据code去开放平台文档查询。

5.3 事件重复推送：同一个问题回复两次

飞书事件回调有重试机制，如果我们的接口处理时间太长没有及时返回200，飞书会认为推送失败，隔一段时间重新推送同一个事件。如果Demo的逻辑是“收到消息就处理并回复”，重复推送就意味着客户收到两条一样的回复。

解决方法有两个。最直接的是让回调接口快速返回，把耗时操作放到异步任务里，接口本身只做校验和入队，毫秒级返回200。第二个是幂等处理，用事件里的header.event_id做一个最近消息ID缓存，重复事件直接跳过。我在代码里加了一个简单的内存集合，判断event_id是否出现过。

processed_event_ids = set() event_id = data.get("header", {}).get("event_id", "") if event_id in processed_event_ids: return jsonify({"code": 0, "msg": "duplicate"}) processed_event_ids.add(event_id)

生产环境可以用Redis替代内存集合，Demo用set足够。

5.4 本地调试的几个实战技巧

第一，日志必须分级。进入回调之后，把事件类型、message_type、content原始内容全部print一遍，不要只打印处理后的结果，否则排查时很难还原现场。第二，使用飞书开放平台自带的“事件调试”功能，它在后台直接模拟真实事件POST到你的回调地址，不用反复真实发消息。第三，内网穿透工具尽量选择支持HTTPS的免费方案，否则飞书那边URL验证过不去。第四，所有敏感配置不要硬编码在代码里，特别是App Secret。我在项目里用python-dotenv加载.env文件，演示时换账号只需要改.env，几秒钟切环境。

6. 从Demo到落地：这些年攒下的实操体会

6.1 Demo阶段的取舍：先窄后宽

第一次做这个Demo的人容易一上来就想做全：识别所有意图、接多维表格、发卡片、上AI。我的建议是先把最小链路跑通，也就是“文本消息 -> 关键词匹配 -> 文本回复”，这条链路通了，你对接下来的调试会非常有信心。之后再逐步加卡片、加多维表格、加异步处理。每加一个能力，都先在小范围场景验证再推广。

我自己第一版只处理单聊，连群聊@机器人的清洗都没做；第二版才加了群聊支持；第三版把数据源切到多维表格。每一版都能独立演示，这样即使现场临场出问题，也能快速回退到上一版。

6.2 几个我特别想提醒的细节

回调地址必须支持HTTPS，这是飞书对生产环境回调的基本要求，本地调试可以借用内网穿透的HTTPS域名，但正式部署一定要有自己的域名和证书。发消息接口的content字段是字符串不是对象，很多人第一次发interactive卡片时，直接把字典塞进content，结果报参数错误，要用json.dumps先转成字符串。还有一点，飞书会校验消息内容的格式和长度，超长文本最好分多条发送，或者用卡片截断展示。

另外一个容易被忽略的点是时区与耗时。在回复内容里附带查询耗时的时候，用time.perf_counter而不是time.time，精度更稳定。演示现场机器性能波动大，perf_counter测出来的耗时不会骗人，也能侧面证明Demo的查询能力是真实在跑，不是提前编好的答案。

6.3 这个能力后续还能怎么扩展

这套“接收话题并回复查询结果”的链路，本质上就是一个业务机器人框架。后面你可以把问答库换成真正的业务API，比如客户问订单进度，Demo直接查ERP接口返回物流状态；也可以接入大模型，把关键词匹配升级成语义理解，客户问法和答案库就不再要求字面匹配了；还可以让机器人把客户的意向自动写入多维表格，形成销售线索表，这已经是在做一个有业务流程的Agent雏形了。飞书官方的妙搭和无代码搭建工具也能做类似的事，但自研Demo的优势在于可控性，你完全掌握每个环节的行为，演示时想突出哪个环节都可以扩展。

最后再多说一句个人体会：最初我以为接入飞书很复杂，真正做下来发现核心就是一个Webhook加两个API，难点全在权限配置和消息结构上。但恰恰是这些细节，决定了演示现场顺不顺利。把App Secret放进环境变量，把事件日志打开，把兜底话术写好，这三件事做好，Demo就成功了一半。等到客户在群里@机器人并且看到它自动回复的那一刻，你会觉得之前调的每个接口、排的每个错都值了。