飞书开放平台 Server API 文档

主题

添加群菜单 ​

在指定群组中添加一个或多个群菜单。成功调用后接口会返回当前群组内所有群菜单信息。

前提条件 ​

  • 应用需要开启机器人能力。
  • 调用当前接口的机器人必须在对应的群组内。

使用限制 ​

  • 该接口是向群内追加菜单，群内已存在的菜单不会被覆盖。
  • 一个群内最多有 3 个一级菜单，每个一级菜单最多配置 5 个二级菜单。
  • 不支持在已有的一级菜单中追加二级菜单。
  • 该接口仅支持群模式为 group 的群组，你可以调用获取群信息接口，在返回结果中查看 chat_mode 参数取值是否为 group。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/im/v1/chats/:chat_id/menu_tree
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可im:chat 获取与更新群组信息 im:chat.menu_tree:write_only 操作群菜单

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

路径参数 ​

名称类型描述
chat_idstring群 ID。获取方式：
- 创建群，从返回结果中获取该群的 chat_id。 - 调用获取用户或机器人所在的群列表接口，可以查询用户或机器人所在群的 chat_id。 - 调用搜索对用户或机器人可见的群列表，可搜索用户或机器人所在的群、对用户或机器人公开的群的 chat_id。
注意：仅支持群模式为 群组（group） 的群组 ID。你可以调用获取群信息接口，在返回结果中查看 chat_mode 参数取值是否为 group。
示例值："oc_a0553eda9014c201e6969b478895c230"

请求体 ​

名称类型必填描述
menu_treechat.menu_tree是要向群内追加的菜单
  └ chat_menu_top_levelschat_menu_top_level\[\]是一级菜单列表
注意：一个群内最多有 3 个一级菜单。
    └ chat_menu_itemchat_menu_item是一级菜单信息
      └ action_typestring是一级菜单类型
注意：
- 如果一级菜单有二级菜单，则此一级菜单的值必须为 NONE。 - 菜单类型创建后不可更改。
示例值："NONE"
可选值有：
- NONE: 无类型，如果需要在一级菜单内添加二级菜单，则该一级菜单需要设置为 NONE。 - REDIRECT_LINK: 跳转链接类型，取该值时需要设置对应的跳转链接（redirect_link）。
      └ redirect_linkchat_menu_item_redirect_link否一级菜单的跳转链接
        └ common_urlstring否公用跳转链接，必须以 http/https 开头。
示例值："https://open.feishu.cn/"
        └ ios_urlstring否iOS 端跳转链接，当该字段不设置时，iOS 端默认使用 common_url 值。必须以 http/https 开头。
示例值："https://open.feishu.cn/"
        └ android_urlstring否Android 端跳转链接，当该字段不设置时，Android 端默认使用 common_url 值。必须以 http/https 开头。
示例值："https://open.feishu.cn/"
        └ pc_urlstring否PC 端跳转链接，当该字段不设置时，PC 端默认使用 common_url 值。必须以 http/https 开头。
使用说明：在 PC 端点击群菜单后，如果需要 url 对应的页面在飞书侧边栏展开，可以在 url 前加上 https://applink.feishu.cn/client/web_url/open?mode=sidebar-semi&url=，例如 https://applink.feishu.cn/client/web_url/open?mode=sidebar-semi&url=https://open.feishu.cn/
示例值："https://open.feishu.cn/"
        └ web_urlstring否Web 端跳转链接，当该字段不设置时，Web 端默认使用 common_url 值。必须以 http/https 开头。
示例值："https://open.feishu.cn/"
      └ image_keystring否一级菜单图标的 key 值。通过 上传图片 接口上传 message 类型图片获取 image_key，并传入该值。
注意：如果一级菜单有二级菜单，则此一级菜单不能设置图标。
示例值："img_v2_b0fbe905-7988-4282-b882-82edd010336j"
      └ namestring是菜单名称
注意：一级、二级菜单名称字符数要在 1 ~ 120 范围内。
示例值："群聊"
      └ i18n_namesi18n_names否菜单国际化名称
注意：一级、二级菜单名称字符数要在 1 ~ 120 范围内。
        └ zh_cnstring否中文名
示例值："评审报名"
        └ en_usstring否英文名
示例值："Sign up"
        └ ja_jpstring否日文名
示例值："サインアップ"
    └ childrenchat_menu_second_level\[\]否二级菜单列表
      └ chat_menu_itemchat_menu_item否二级菜单信息
        └ action_typestring否二级菜单类型
示例值："NONE"
可选值有：
- NONE: 无类型 - REDIRECT_LINK: 跳转链接类型，取该值时需要设置跳转链接（redirect_link）。
        └ redirect_linkchat_menu_item_redirect_link否二级菜单跳转链接
          └ common_urlstring否公用跳转链接，必须以 http/https 开头。
示例值："https://open.feishu.cn/"
          └ ios_urlstring否iOS 端跳转链接，当该字段不设置时，iOS 端默认使用 common_url 值。必须以 http/https 开头。
示例值："https://open.feishu.cn/"
          └ android_urlstring否Android 端跳转链接，当该字段不设置时，Android 端默认使用 common_url 值。必须以 http/https 开头。
示例值："https://open.feishu.cn/"
          └ pc_urlstring否PC 端跳转链接，当该字段不设置时，PC 端默认使用 common_url 值。必须以 http/https 开头。 使用说明：在 PC 端点击群菜单后，如果需要 url 对应的页面在飞书侧边栏展开，可以在 url 前加上 https://applink.feishu.cn/client/web_url/open?mode=sidebar-semi&url=，例如 https://applink.feishu.cn/client/web_url/open?mode=sidebar-semi&url=https://open.feishu.cn/
示例值："https://open.feishu.cn/"
          └ web_urlstring否Web 端跳转链接，当该字段不设置时，Web 端默认使用 common_url 值。必须以 http/https 开头。
示例值："https://open.feishu.cn/"
        └ image_keystring否二级菜单图标的 key 值。通过 上传图片 接口上传 message 类型图片获取 image_key，并传入该值。
示例值："img_v2_b0fbe905-7988-4282-b882-82edd010336j"
        └ namestring否菜单名称
注意：一级、二级菜单名称字符数要在 1 ~ 120 范围内
示例值："群聊"
        └ i18n_namesi18n_names否菜单国际化名称
注意：一级、二级菜单名称字符数要在 1 ~ 120 范围内
          └ zh_cnstring否中文名
示例值："评审报名"
          └ en_usstring否英文名
示例值："Sign up"
          └ ja_jpstring否日文名
示例值："サインアップ"

请求体示例 ​

json
{
    "menu_tree": {
        "chat_menu_top_levels": [
            {
                "chat_menu_item": {
                    "action_type": "NONE",
                    "redirect_link": {
                        "common_url": "https://open.feishu.cn/",
                        "ios_url": "https://open.feishu.cn/",
                        "android_url": "https://open.feishu.cn/",
                        "pc_url": "https://open.feishu.cn/",
                        "web_url": "https://open.feishu.cn/"
                    },
                    "image_key": "img_v2_b0fbe905-7988-4282-b882-82edd010336j",
                    "name": "群聊",
                    "i18n_names": {
                        "zh_cn": "评审报名",
                        "en_us": "Sign up",
                        "ja_jp": "サインアップ"
                    }
                },
                "children": [
                    {
                        "chat_menu_item": {
                            "action_type": "NONE",
                            "redirect_link": {
                                "common_url": "https://open.feishu.cn/",
                                "ios_url": "https://open.feishu.cn/",
                                "android_url": "https://open.feishu.cn/",
                                "pc_url": "https://open.feishu.cn/",
                                "web_url": "https://open.feishu.cn/"
                            },
                            "image_key": "img_v2_b0fbe905-7988-4282-b882-82edd010336j",
                            "name": "群聊",
                            "i18n_names": {
                                "zh_cn": "评审报名",
                                "en_us": "Sign up",
                                "ja_jp": "サインアップ"
                            }
                        }
                    }
                ]
            }
        ]
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ menu_treechat.menu_tree添加群菜单后，该群组内所有群菜单的信息。
    └ chat_menu_top_levelschat_menu_top_level\[\]一级菜单列表
      └ chat_menu_top_level_idstring一级菜单 ID，后续删除、修改、排序等群菜单管理操作均需要使用菜单 ID。
      └ chat_menu_itemchat_menu_item一级菜单信息
        └ action_typestring菜单类型
可选值有：
- NONE: 无类型，当一级菜单下有二级菜单时，类型取值为 NONE。 - REDIRECT_LINK: 跳转链接类型
        └ redirect_linkchat_menu_item_redirect_link跳转链接
          └ common_urlstring公用跳转链接
          └ ios_urlstringiOS 端跳转链接，当该字段不设置时，iOS 端默认使用 common_url 值。
          └ android_urlstringAndroid 端跳转链接，当该字段不设置时，Android 端默认使用 common_url 值。
          └ pc_urlstringPC 端跳转链接，当该字段不设置时，PC 端默认使用 common_url 值。
说明：以 https://applink.feishu.cn/client/web_url/open?mode=sidebar-semi&url= 开头的链接表示在飞书侧边栏展开。
          └ web_urlstringWeb 端跳转链接，当该字段不设置时，Web 端默认使用 common_url 值。
        └ image_keystring图标的 key 值。通过下载图片接口可将图标下载到本地（只能下载由当前机器人上传的图片）。
注意：一级菜单下存在二级菜单时不能设置图标。
        └ namestring菜单名称
        └ i18n_namesi18n_names菜单国际化名称
          └ zh_cnstring中文名
          └ en_usstring英文名
          └ ja_jpstring日文名
      └ childrenchat_menu_second_level\[\]二级菜单列表
        └ chat_menu_second_level_idstring二级菜单 ID
        └ chat_menu_itemchat_menu_item二级菜单信息
          └ action_typestring菜单类型
可选值有：
- NONE: 无类型 - REDIRECT_LINK: 跳转链接类型
          └ redirect_linkchat_menu_item_redirect_link跳转链接
            └ common_urlstring公用跳转链接
            └ ios_urlstringiOS 端跳转链接，当该字段不设置时，iOS 端默认使用 common_url 值。
            └ android_urlstringAndroid 端跳转链接，当该字段不设置时，Android 端默认使用 common_url 值。
            └ pc_urlstringPC 端跳转链接，当该字段不设置时，PC 端默认使用 common_url 值。
说明：以 https://applink.feishu.cn/client/web_url/open?mode=sidebar-semi&url= 开头的链接表示在飞书侧边栏展开。
            └ web_urlstringWeb 端跳转链接，当该字段不设置时，Web 端默认使用 common_url 值。
          └ image_keystring图标的 key 值。通过下载图片接口可将图标下载到本地（只能下载由当前机器人上传的图片）。
          └ namestring菜单名称
          └ i18n_namesi18n_names菜单国际化名称
            └ zh_cnstring中文名
            └ en_usstring英文名
            └ ja_jpstring日文名

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "menu_tree": {
            "chat_menu_top_levels": [
                {
                    "chat_menu_top_level_id": "7117116451961487361",
                    "chat_menu_item": {
                        "action_type": "NONE",
                        "redirect_link": {
                            "common_url": "https://open.feishu.cn/",
                            "ios_url": "https://open.feishu.cn/",
                            "android_url": "https://open.feishu.cn/",
                            "pc_url": "https://open.feishu.cn/",
                            "web_url": "https://open.feishu.cn/"
                        },
                        "name": "菜单",
                        "i18n_names": {
                            "zh_cn": "菜单",
                            "en_us": "Menu",
                            "ja_jp": "メニュー"
                        }
                    },
                    "children": [
                        {
                            "chat_menu_second_level_id": "7039638308221468675",
                            "chat_menu_item": {
                                "action_type": "REDIRECT_LINK",
                                "redirect_link": {
                                    "common_url": "https://open.feishu.cn/",
                                    "ios_url": "https://open.feishu.cn/",
                                    "android_url": "https://open.feishu.cn/",
                                    "pc_url": "https://open.feishu.cn/",
                                    "web_url": "https://open.feishu.cn/"
                                },
                                "image_key": "img_v2_b0fbe905-7988-4282-b882-82edd010336j",
                                "name": "报名",
                                "i18n_names": {
                                    "zh_cn": "报名",
                                    "en_us": "Sign up",
                                    "ja_jp": "サインアップ"
                                }
                            }
                        }
                    ]
                }
            ]
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
400232001Your request contains an invalid request parameter.参数错误，参考接口文档提供的参数描述，检查输入参数是否有误。
400232008Your request specifies a chat whose type is NOT supported currently.不支持的群模式（chat_mode）或群类型（chat_type）。你可以调用获取群信息接口，查看群信息是否符合当前接口的要求。
400232009Your request specifies a chat which has already been dissolved.群组已被解散，无法操作。
400232011Operator can NOT be out of the chat.操作者不在群组中。你需要将当前调用 API 的应用或用户加入待操作的群组后重试。
400232014The token used in the request does NOT have the permissions necessary to complete the request.操作者没有权限进行该操作，请检查是否已开通调用接口所需要的权限。
400232024Users do not have the visibility of the app, or the operator does not have collaboration permissions with the target users.机器人对用户没有可见性，或操作者与用户间没有协作权限。 - 如果是机器人对用户没有可见性，需要在开发者后台 > 应用详情页 > 应用发布 > 版本管理与发布 编辑应用对用户的可见性并发布应用。具体操作参考配置应用可用范围。 - 如果是操作者与用户之间没有协作权限，请检查是否与目标用户有协作权限，如屏蔽、未添加为联系人等
400232025Bot ability is not activated.应用未启用机器人能力。你需要登录开发者后台，在应用详情页的 应用能力 > 添加应用能力 页面内，添加 机器人 能力，并发布应用使配置生效。具体操作参见机器人能力。
400232055The operator does not have chat tab, chat menu, chat widget manage permission没有会话标签页、会话菜单和小组件的管理权限。如果在飞书客户端群设置中 谁可以管理标签页、小组件和会话菜单 选择了 仅群主和管理员，则只允许群主或者管理员进行操作。
400232033The operator or invited bots does NOT have the authority to manage external chats without the scope.当前被操作的群为外部群，暂不支持操作外部群。只有开启对外共享能力的机器人支持外部群，详情参见机器人支持外部群和外部用户单聊。
400232034The app is unavailable or inactivated by the tenant.应用在本租户下未安装或未启用。需要先安装应用，再使用应用调用接口。
400232056The operator is not the image's owner, no permission to complete the request.机器人需要使用自己上传的图片。
400232070The number of chat_menu_top_level has reached the limit.chat_menu_top_levels 数量达到上限。群内一级菜单的数量不能超过 3 个。
400232071The number of chat_menu_second_level has reached the limit.一个一级菜单下的二级菜单数不能超过 5 个。
400232073The group menu is being modified, please try again later.群内菜单正在修改中，请稍后重试。
400232078The chat menu is illegal.群菜单内容非法。

更多错误码信息，参见通用错误码。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有