# 机器人菜单使用指南 机器人菜单指启用了机器人能力的应用所提供的交互选项的集合。通过为机器人应用配置自定义菜单，你可以将应用的常用入口固定在机器人聊天的输入框上。用户可通过这些交互选项与该机器人应用互动，实现快捷操作，如发起新话题、技能切换等。 本文档介绍如何在开发者后台配置机器人菜单。 ## 展示样式 机器人菜单的展示样式可分为可切换菜单样式和悬浮菜单样式，其定义如下表所示： | **展示样式** | **描述** | **支持版本** | **图示** | | -------- | -------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 可切换菜单 | 菜单选项与输入框在同一位置，用户可通过点击左侧按钮在菜单和输入框之间切换。与悬浮菜单相比，该样式更简洁。 | 5.27 及以上。在低于此版本的客户端上，可切换菜单将不再展示。 | ![可切换菜单-中文.gif](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/3f8706f127cf02a8e90e237700d080cf_GoMfFY3S9x.gif?height=1080&lazyload=true&width=1922) | | 悬浮菜单 | 菜单选项悬浮在输入框上方，用户可直接点击菜单按钮进行交互。与可切换菜单相比，该样式允许菜单项常驻在用户界面，不影响用户输入。 | 7.22 及以上。在低于此版本的客户端上，悬浮菜单将不再展示。 |![悬浮菜单-中文.gif](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/0054a19040ff67f32ebde0353191deb2_dj0ByyXYBB.gif?height=1080&lazyload=true&width=1920) ## 使用限制 目前，机器人菜单仅支持单聊场景，不支持群聊场景。 ## 配置步骤 配置机器人菜单的步骤如下所示： 1. 进入[开发者后台](https://open.feishu.cn/app)，选择要配置菜单的应用，或创建一个新的应用，然后点击应用图标进入应用详情页。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/2ab652236e509d152209df64b7a1c593_zRoKg7XMro.png?height=1514&lazyload=true&maxWidth=650&width=2550) 1. 在左侧导航栏点击 **添加应用能力** 页面，然后点击 **机器人** 下方的 **添加能力** 按钮。 你将进入机器人能力配置页面。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/9fd2d607a4cb3ea42bb695b35981e8b6_MRdt6lPEWx.png?height=1606&lazyload=true&maxWidth=650&width=2586) 1. 在机器人能力配置页面，点击 **机器人自定义菜单** 右侧的编辑按钮，将菜单状态切换至 **开启**。 1. 参考以下动图，选择菜单的展示样式和默认展示样式，配置菜单并保存。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/e87dba5936746571168eef2f1e048784_40FPEfAqIL.gif?height=734&lazyload=true&maxWidth=650&width=1864) 在配置菜单时，有以下限制： - 机器人菜单名称最多支持配置 60 个字符。建议精简文案，避免小屏设备无法展示完整内容。 - 对于可切换菜单样式，一个机器人最多可配置 3 个主菜单，每个主菜单最多可配置 5 个子菜单。 - 对于悬浮菜单样式，一个机器人最多可配置 5 个主菜单，每个主菜单最多可配置 10 个子菜单。 1. 创建应用版本并发布，使配置生效。菜单在设备上生效可能有延迟，版本发布成功后，**请稍候 5 分钟**再查看菜单效果。 ## 响应动作说明 在配置机器人菜单时，你可选择以下三种响应动作，说明如下所示： - **跳转至指定链接**：你可以为桌面端和移动端飞书分别配置跳转链接，或配置 Applink，实现例如打开小程序、打开群聊等飞书客户端内的跳转。详情参考 [AppLink 协议介绍](https://open.feishu.cn/document/uYjL24iN/ucjN1UjL3YTN14yN2UTN)。 - **发送文字消息**：将菜单文案作为消息发送。该动作仅支持飞书 V7.22 及以上版本，在低于此版本的客户端上，配置了该动作的菜单项将不再展示。 - **推送事件**：订阅用户点击菜单项的事件，使开放平台将该事件推送至你的服务端。具体步骤如下所示： 1. 参考[配置订阅方式](https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/request-url-configuration-case)，选择并配置开放平台发送事件的方式； 2. 在开发者后台 **事件与回调 > 事件配置** 页面，点击 **添加事件**。 3. 搜索并订阅“机器人自定义菜单事件”，然后点击 **确认添加**。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/ac77cdd97524a32f32dfee14f4f98caa_laGXt7Ueul.png?height=777&lazyload=true&maxWidth=650&width=1122) 3. 在机器人菜单中自定义用户点击菜单事件的唯一标识，该标识将作为[机器人自定义菜单事件](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/application-v6/bot/events/menu)回调中 `event_key` 的值发送给你的服务器。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/20739f1ce69651ee027e279d5a5e5279_7ff1JiesZv.png?height=793&lazyload=true&maxWidth=650&width=1470) 4. 创建应用版本并发布，使配置生效。当用户点击该菜单时，你将收到如[机器人自定义菜单事件](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/application-v6/bot/events/menu)文档中事件体的回调。 5. （后续操作）在接收到用户的点击事件后，你可以通过服务端 OpenAPI 调用的方式响应用户操作，例如在聊天里为用户发送使用帮助卡片。 ## 常见问题 ### 将悬浮菜单样式切换至可切换菜单样式时，提示超出限制，要如何解决？ ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/86d5ed1d773ac73441ff8f36bedf99d0_kmG07A1HZW.png?height=677&lazyload=true&maxWidth=550&width=1133) 由于可切换菜单支持配置的菜单数量相对于悬浮菜单较少，因此你需要将主菜单数量减少至最多 3 个，将每个主菜单的子菜单数量减少至最多 5 个。 ### 悬浮菜单配置成功了，为什么没有生效？ 请参考以下排查建议解决： 1. 请确保飞书版本在 7.22 及以上。在低于此版本的客户端上，悬浮菜单将不再展示。 2. 请确保悬浮菜单配置后，创建了应用版本并完成了发布。版本发布成功后，请 5 分钟后再查看菜单效果。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/80f002bea81cbafac05abdc7547e232c_TZUPApROy0.png?height=771&lazyload=true&maxWidth=650&width=1521) 4. 如果你的应用是通过智能伙伴搭建平台（Aily）创建的 AI 应用，那么该悬浮菜单由智能伙伴搭建平台管理，开发者后台的配置默认不生效。详情参考[Aily 飞书机器人升级说明](https://aily.feishu.cn/hc/1u7kleqg/qmu3uklz#fdeaae2c)。