飞书开放平台 Server API 文档

主题

更新会话标签页 ​

更新指定的会话标签页信息，包括名称、类型以及内容等。仅支持更新文档类型（doc）或 URL （url）类型的标签页。

前提条件 ​

  • 应用需要开启机器人能力。
  • 调用当前接口的用户或者机器人必须在对应的会话内。

使用限制 ​

  • 调用该接口仅支持更新 doc、url 类型的标签页，即 tab_type 参数传值时，只能传入 doc 或 url，传入其他枚举值将会报错。如果你需要更新其他类型的会话标签页，需要在飞书客户端内操作，详情参见会话内标签页。
  • 如果群组配置了 仅群主和群管理员可以管理标签页，则仅群主或者群管理员可以更新会话标签页。
  • 操作内部群时，操作者须与群组在同一租户下。

请求 ​

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

请求头 ​

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

路径参数 ​

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

请求体 ​

名称类型必填描述
chat_tabschat.tab\[\]否会话标签页
  └ tab_idstring否会话标签页 ID，ID 可以在添加会话标签页或者拉取会话标签页接口返回值中获取。
示例值："7101214603622940671"
  └ tab_namestring否会话标签页名称
注意：会话标签页的名称不能超过 60 个字符
示例值："文档"
  └ tab_typestring是会话标签页类型
注意：只支持更新 doc、url 类型的标签页，其他字段为只读字段
示例值："doc"
可选值有：
- message: 消息类型 - doc_list: 云文档列表 - doc: 文档 - pin: Pin - meeting_minute: 会议纪要 - chat_announcement: 群公告 - url: URL - file: 文件 - files_resources: 合并类型，包含文件、Doc文档、URL链接 - images_videos: 合并类型，包含图片、视频 - task: 任务
  └ tab_contentchat_tab_content否会话标签页内容
    └ urlstring否URL 地址，在 tab_type 取值为 url 时生效
注意：
- tab_type 取值为 url 时url不能为空
- 必须以 http 或 https 开头
示例值："https://www.feishu.cn"
    └ docstring否云文档链接，在 tab_type 取值为 doc 时生效
注意：
- tab_type 取值为 doc 时doc不能为空
- 必须以 http 或 https 开头
- 当前操作者必须有云文档的协作者权限
示例值："https://example.feishu.cn/wiki/wikcnPIcqWjJQwkwDzrB9t40123xz"
    └ meeting_minutestring否会议纪要，因不支持更新 meeting_minute 类型的会话标签页，该字段为只读字段，无需传值。
示例值："https://example.feishu.cn/docs/doccnvIXbV22i6hSD3utar4123dx"
    └ taskstring否任务，因不支持更新 task 类型的会话标签页，该字段为只读字段，无需传值。
示例值："https://bytedance.feishu.cn/client/todo/task_list?guid=fa03fb6d-344b-47d9-83e3-049e3b3da931"
  └ tab_configchat_tab_config否会话标签页的配置
注意：仅当 tab_type 取值为 url 时，该参数生效
    └ icon_keystring否会话标签页的图标。需要先调用上传图片 接口，图片类型设置为 message 上传图片，然后获取 image_key 后传入当前参数。
示例值："img_v2_b99741-7628-4abd-aad0-b881e4db83ig"
    └ is_built_inboolean否会话标签页是否在 App 内嵌打开
示例值：false

请求体示例 ​

json
{
    "chat_tabs": [
        {
            "tab_id": "7101214603622940671",
            "tab_name": "文档",
            "tab_type": "doc",
            "tab_content": {
                "url": "https://www.feishu.cn",
                "doc": "https://example.feishu.cn/wiki/wikcnPIcqWjJQwkwDzrB9t40123xz",
                "meeting_minute": "https://example.feishu.cn/docs/doccnvIXbV22i6hSD3utar4123dx",
                "task": "https://bytedance.feishu.cn/client/todo/task_list?guid=fa03fb6d-344b-47d9-83e3-049e3b3da931"
            },
            "tab_config": {
                "icon_key": "img_v2_b99741-7628-4abd-aad0-b881e4db83ig",
                "is_built_in": false
            }
        }
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ chat_tabschat.tab\[\]会话标签页
    └ tab_idstring会话标签页 ID
    └ tab_namestring会话标签页名称
    └ tab_typestring会话标签页类型
可选值有：
- message: 消息类型 - doc_list: 云文档列表 - doc: 文档 - pin: Pin - meeting_minute: 会议纪要 - chat_announcement: 群公告 - url: URL - file: 文件 - files_resources: 合并类型，包含文件、Doc文档、URL链接 - images_videos: 合并类型，包含图片、视频 - task: 任务
    └ tab_contentchat_tab_content会话标签页内容
      └ urlstringurl 类型标签页对应的 URL 地址
      └ docstring文档类型标签页对应的云文档链接
      └ meeting_minutestring会议纪要类型标签页对应的会议纪要地址
      └ taskstring任务
    └ tab_configchat_tab_config会话标签页配置
      └ icon_keystring会话标签页图标。可调用下载图片（只能下载由当前机器人上传的图片），将图标下载至本地查看
      └ is_built_inboolean会话标签页是否在 App 内嵌打开

响应体示例 ​

json
{
    "code": 0,
    "msg": "ok",
    "data": {
        "chat_tabs": [
            {
               "tab_id": "7101214603622940633",
                "tab_type": "message"
            },
            {
                "tab_id": "7103849256556953620",
                "tab_name": "update",
                "tab_type": "doc",
                "tab_content": {
                    "doc": "https://example.feishu.cn/docx/doxbcjoYDoEtuwC0k0hryQBkSV1"
                }
            },
            {
                "tab_id": "7103849256561164308",
                "tab_name": "url-update",
                "tab_type": "url",
                "tab_content": {
                    "url": "https://www.feishu.cn/"
                }
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
400232001Your request contains an invalid request parameter.参数错误，参考接口文档提供的参数描述，检查输入参数是否有误。
400232006Your request specifies a chat_id which is invalid.无效的 chat_id，请检查 chat_id 是否正确。获取方式： - 创建群，从返回结果中获取该群的 chat_id。 - 调用获取用户或机器人所在的群列表接口，可以查询用户或机器人所在群的 chat_id。 - 调用搜索对用户或机器人可见的群列表，可搜索用户或机器人所在的群、对用户或机器人公开的群的 chat_id。
400232009Your request specifies a chat which has already been dissolved.群组已被解散，无法操作。
400232010Operator and chat can NOT be in different tenants.操作者和被操作的群组应该在同一租户下。
400232011Operator can NOT be out of the chat.操作者不在群组中。你需要将当前调用 API 的应用或用户加入待操作的群组后重试。
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.应用未启用机器人能力。你需要登录开发者后台，在应用详情页的 应用能力 > 添加应用能力 页面内，添加 机器人 能力，并发布应用使配置生效。具体操作参见机器人能力。
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.应用在本租户下未安装或未启用。需要先安装应用，再使用应用调用接口。
400232047The length of the tab name reaches the limit.会话标签页名称过长。不能超过 60 个字符。
400232048The chat tab content is illegal.会话标签页内容非法。检查 tab_content 参数，传入正确值，例如 url 需要以 http、https 开头。
400232049The chat tab content is illegal.更新或者删除操作仅支持 doc 或者 url 类型的会话标签页。
400232050Operate chat tab unsupported chat type.请求的群类型不支持会话标签页。仅支持群模式为 群组（group）、单聊（p2p） 的群组 ID。你可以调用获取群信息接口，在返回结果中查看 chat_mode 参数取值是否为 group、p2p。
400232051The operator does not have doc permission.操作者必须拥有云文档权限。你可以调用增加协作者权限接口，为当前操作者添加云文档权限。
400232055The operator does not have chat tab, chat menu, chat widget manage permission没有会话标签页、会话菜单和小组件的管理权限。如果在飞书客户端群设置中 谁可以管理标签页、小组件和会话菜单 选择了 仅群主和管理员，则只允许群主或者管理员进行操作。
400232056The operator is not the image's owner, no permission to complete the request.机器人需要使用自己上传的图片。

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

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

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