飞书开放平台 Server API 文档

主题

创建群 ​

创建群聊，创建时支持设置群头像、群名称、群主以及群类型等配置，同时支持邀请群成员、群机器人入群。

前提条件 ​

应用需要开启机器人能力。

使用限制 ​

商店应用无法使用用户的 user_id，因此使用商店应用调用本接口时用户 ID 类型请选择 open_id 或者 union_id。

注意事项 ​

  • 如果你需要在已创建的群聊内邀请用户或机器人入群，可调用将用户或机器人拉入群聊接口。
  • 调用 API 只能创建普通消息群，消息形式可以选择对话消息或者话题消息。如果你需要直接创建话题群，请通过飞书客户端创建群组，创建时群模式选择 话题。
  • 已添加外部共享能力的机器人，允许在创建群时将外部企业用户和内部用户同时添加到群组中，这样创建的群为外部群。详情参见机器人支持外部群和外部用户单聊。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/im/v1/chats
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可im:chat 获取与更新群组信息 im:chat:create 创建群
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

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

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
set_bot_managerboolean否如果在请求体的 ==owner_id== 字段指定了某个用户为群主，可以选择是否同时设置创建此群的机器人为管理员，此标志位用于标记是否设置创建群的机器人为管理员。
示例值：false
默认值：false
uuidstring否由开发者生成的唯一字符串序列，用于创建群组请求去重；持有相同 uuid + owner_id（若有） 的请求 10 小时内只可成功创建 1 个群聊。不传值表示不进行请求去重，每一次请求成功后都会创建一个群聊。
示例值：b13g2t38-1jd2-458b-8djf-dtbca5104204
数据校验规则：
- 最大长度：50 字符

请求体 ​

名称类型必填描述
avatarstring否群头像对应的 Image Key
- 可通过上传图片获取（注意：上传图片的 ==image_type== 需要指定为 ==avatar==） - 不传值则使用系统默认头像
示例值："default-avatar_44ae0ca3-e140-494b-956f-78091e348435"
namestring否群名称
注意： - 建议群名称不超过 60 字符 - 公开群名称的长度不得少于 2 个字符 - 私有群若未填写群名称，群名称默认设置为 (无主题)
示例值："测试群名称"
descriptionstring否群描述，建议不超过 100 字符
默认值：空
示例值："测试群描述"
i18n_namesi18n_names否群国际化名称
注意： - 建议不超过 60 字符 - 不设置国际化名称，则默认展示 name 参数对应的名称
  └ zh_cnstring否中文名
示例值："群聊"
  └ en_usstring否英文名
示例值："group chat"
  └ ja_jpstring否日文名
示例值："グループチャット"
owner_idstring否创建群时指定的群主，不填时指定建群的机器人为群主。群主 ID 类型在查询参数 ==user_id_type== 中指定；推荐使用 OpenID，获取方式可参考文档如何获取 Open ID？
注意：开启对外共享能力的机器人在创建外部群时，机器人不能为群主，必须指定某一用户作为群主。此外，添加外部用户进群时，外部用户必须和群主已成为飞书好友。
示例值："ou_7d8a6e6df7621556ce0d21922b676706ccs"
user_id_liststring\[\]否创建群时邀请的群成员，不填则不邀请成员。ID 类型在查询参数 ==user_id_type== 中指定；推荐使用 OpenID，获取方式可参考文档如何获取 Open ID？
注意： - 最多同时邀请 50 个用户 - 为便于在客户端查看效果，建议调试接口时加入开发者自身 ID - 如果需要邀请外部用户，则外部用户必须和群主已成为飞书好友 - 如何获取外部用户的 open_id，参考获取外部用户的 open_id
示例值：["ou_7d8a6e6df7621556ce0d21922b676706ccs"]
数据校验规则：
- 最大长度：50
bot_id_liststring\[\]否创建群时邀请的群机器人，不填则不邀请机器人。可参考如何获取应用的 App ID？来获取应用的 App ID 注意： - 操作此接口的机器人会自动入群，无需重复填写 - 拉机器人入群请使用 app_id - 最多同时邀请 5 个机器人，且邀请后群组中机器人数量不能超过 15 个
示例值：["cli_a10fbf7e94b8d01d"]
数据校验规则：
- 最大长度：5
group_message_typestring否群消息形式
示例值："chat"
可选值有：
- chat: 对话消息 - thread: 话题消息
默认值：chat
chat_modestring否群模式
可选值有： - group：群组
示例值："group"
默认值：group
chat_typestring否群类型
可选值有： - private：私有群 - public：公开群
示例值："private"
默认值：private
join_message_visibilitystring否成员入群提示消息的可见性
可选值有： - only_owner：仅群主和管理员可见 - all_members：所有成员可见 - not_anyone：任何人均不可见
示例值："all_members"
默认值：all_members
leave_message_visibilitystring否成员退群提示消息的可见性
可选值有： - only_owner：仅群主和管理员可见 - all_members：所有成员可见 - not_anyone：任何人均不可见
示例值："all_members"
默认值：all_members
membership_approvalstring否加群是否需要审批
可选值有： - no_approval_required：无需审批 - approval_required：需要审批
示例值："no_approval_required"
默认值：no_approval_required
restricted_mode_settingrestricted_mode_setting否保密模式设置
注意：保密模式适用于企业旗舰版。适用版本与功能介绍参见会话保密模式。
  └ statusboolean否保密模式是否开启
可选值有：
- true：开启。设置为 ture 时，screenshot_has_permission_setting、download_has_permission_setting、message_has_permission_setting 不能全为 all_members。 - false：不开启。设置为 false 时，screenshot_has_permission_setting、download_has_permission_setting、message_has_permission_setting 不能存在 not_anyone。
默认值：false
示例值：false
  └ screenshot_has_permission_settingstring否允许截屏录屏
默认值：all_members
示例值："all_members"
可选值有：
- all_members: 所有成员允许截屏录屏 - not_anyone: 所有成员禁止截屏录屏
  └ download_has_permission_settingstring否允许下载消息中图片、视频和文件
默认值：all_members
示例值："all_members"
可选值有：
- all_members: 所有成员允许下载资源 - not_anyone: 所有成员禁止下载资源
  └ message_has_permission_settingstring否允许复制和转发消息
默认值：all_members
示例值："all_members"
可选值有：
- all_members: 所有成员允许复制和转发消息 - not_anyone: 所有成员禁止复制和转发消息
urgent_settingstring否谁可以加急
默认值：all_members
示例值："all_members"
可选值有：
- only_owner: 仅群主和管理员 - all_members: 所有成员
video_conference_settingstring否谁可以发起视频会议
默认值：all_members
示例值："all_members"
可选值有：
- only_owner: 仅群主和管理员 - all_members: 所有成员
edit_permissionstring否谁可以编辑群信息
默认值：all_members
示例值："all_members"
可选值有：
- only_owner: 仅群主和管理员 - all_members: 所有成员
hide_member_count_settingstring否隐藏群成员人数设置
默认值：all_members
示例值："all_members"
可选值有：
- all_members: 所有群成员可见 - only_owner: 仅群主群管理员可见

请求体示例 ​

json
{
    "avatar": "default-avatar_44ae0ca3-e140-494b-956f-78091e348435",
    "name": "测试群名称",
    "description": "测试群描述",
    "i18n_names": {
        "zh_cn": "群聊",
        "en_us": "group chat",
        "ja_jp": "グループチャット"
    },
    "owner_id": "ou_7d8a6e6df7621556ce0d21922b676706ccs",
    "user_id_list": [
        "ou_7d8a6e6df7621556ce0d21922b676706ccs"
    ],
    "bot_id_list": [
        "cli_a10fbf7e94b8d01d"
    ],
    "group_message_type": "chat",
    "chat_mode": "group",
    "chat_type": "private",
    "join_message_visibility": "all_members",
    "leave_message_visibility": "all_members",
    "membership_approval": "no_approval_required",
    "restricted_mode_setting": {
        "status": false,
        "screenshot_has_permission_setting": "all_members",
        "download_has_permission_setting": "all_members",
        "message_has_permission_setting": "all_members"
    },
    "urgent_setting": "all_members",
    "video_conference_setting": "all_members",
    "edit_permission": "all_members",
    "hide_member_count_setting": "all_members"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ chat_idstring群 ID。建议保存该 ID，后续向群发送消息、更新群信息以及将用户或机器人拉入群聊等群组相关的操作均需使用该 ID。
  └ avatarstring群头像 URL
  └ namestring群名称
  └ descriptionstring群描述
  └ i18n_namesi18n_names群国际化名称
    └ zh_cnstring中文名
    └ en_usstring英文名
    └ ja_jpstring日文名
  └ owner_idstring群主 ID，ID 类型与查询参数中的 ==user_id_type== 对应；不同 ID 的说明参见 用户相关的 ID 概念。
注意：当群主是机器人时，该字段不返回
  └ owner_id_typestring群主 ID 类型，与查询参数中的 ==user_id_type== 取值相同。
注意：当群主是机器人时，该字段不返回
  └ urgent_settingstring谁可以加急
可选值有：
- only_owner: 仅群主和管理员 - all_members: 所有成员
  └ video_conference_settingstring谁可以发起视频会议
可选值有：
- only_owner: 仅群主和管理员 - all_members: 所有成员
  └ add_member_permissionstring谁可以邀请用户或机器人入群
可选值有： - only_owner：仅群主和管理员 - all_members：所有成员
  └ share_card_permissionstring群分享权限
可选值有： - allowed：允许 - not_allowed：不允许
  └ at_all_permissionstring谁可以 at 所有人
可选值有： - only_owner：仅群主和管理员 - all_members：所有成员
  └ edit_permissionstring群编辑权限
可选值有： - only_owner：仅群主和管理员 - all_members：所有成员
  └ group_message_typestring群消息形式
可选值有： - chat：对话消息 - thread：话题消息
  └ chat_modestring群模式
可选值有： - group：群组
  └ chat_typestring群类型
可选值有： - private：私有群 - public：公开群
  └ chat_tagstring群标签，如有多个，则按照下列顺序返回第一个
可选值有： - inner：内部群 - tenant：公司群 - department：部门群 - edu：教育群 - meeting：会议群 - customer_service：客服群
  └ externalboolean是否是外部群
  └ tenant_keystring租户在飞书上的唯一标识，用来换取对应的 tenant_access_token，也可以用作租户在应用里面的唯一标识
  └ join_message_visibilitystring入群消息可见性
可选值有： - only_owner：仅群主和管理员可见 - all_members：所有成员可见 - not_anyone：任何人均不可见
  └ leave_message_visibilitystring出群消息可见性
可选值有： - only_owner：仅群主和管理员可见 - all_members：所有成员可见 - not_anyone：任何人均不可见
  └ membership_approvalstring加群审批
可选值有： - no_approval_required：无需审批 - approval_required：需要审批
  └ moderation_permissionstring发言权限
可选值有： - only_owner：仅群主和管理员 - all_members：所有成员 - moderator_list：指定群成员
  └ restricted_mode_settingrestricted_mode_setting保密模式设置
注意：仅企业旗舰版支持设置保密模式。保密模式的适用版本与功能介绍，参见会话保密模式。
    └ statusboolean保密模式是否开启
    └ screenshot_has_permission_settingstring允许截屏录屏
可选值有：
- all_members: 所有成员允许截屏录屏 - not_anyone: 所有成员禁止截屏录屏
    └ download_has_permission_settingstring允许下载消息中图片、视频和文件
可选值有：
- all_members: 所有成员允许下载资源 - not_anyone: 所有成员禁止下载资源
    └ message_has_permission_settingstring允许复制和转发消息
可选值有：
- all_members: 所有成员允许复制和转发消息 - not_anyone: 所有成员禁止复制和转发消息
  └ hide_member_count_settingstring隐藏群成员人数设置
可选值有：
- all_members: 所有群成员可见 - only_owner: 仅群主群管理员可见

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "chat_id": "oc_a0553eda9014c201e6969b478895c230",
        "avatar": "https://p3-lark-file.byteimg.com/img/lark-avatar-staging/default-avatar_44ae0ca3-e140-494b-956f-78091e348435~100x100.jpg",
        "name": "测试群名称",
        "description": "测试群描述",
        "i18n_names": {
            "zh_cn": "群聊",
            "en_us": "group chat",
            "ja_jp": "グループチャット"
        },
        "owner_id": "ou_7d8a6e6df7621556ce0d21922b676706ccs",
        "owner_id_type": "open_id",
        "urgent_setting": "all_members",
        "video_conference_setting": "all_members",
        "add_member_permission": "all members",
        "share_card_permission": "allowed",
        "at_all_permission": "all members",
        "edit_permission": "all members",
        "group_message_type": "chat",
        "chat_mode": "group",
        "chat_type": "private",
        "chat_tag": "inner",
        "external": false,
        "tenant_key": "736588c9260f175e",
        "join_message_visibility": "all_members",
        "leave_message_visibility": "all_members",
        "membership_approval": "no_approval_required",
        "moderation_permission": "all_members",
        "restricted_mode_setting": {
            "status": false,
            "screenshot_has_permission_setting": "all_members",
            "download_has_permission_setting": "all_members",
            "message_has_permission_setting": "all_members"
        },
        "hide_member_count_setting": "all_members"
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
400232001Your request contains an invalid request parameter.参数错误。请参考 API 文档参数描述，排查请求时参数是否填写有误。
400232004Such an app does NOT exist.作为操作者的 app_id 不存在，请联系技术支持。
400232019The request has been rate limited.触发群限流，请控制请求的速度，详情参见频控策略。
400232020Name can NOT be less than two characters for public chats.公开群名称太短，不得少于 2 个字符。
400232021Bot can NOT be found.未找到机器人。
400232022User has already resigned.邀请的用户已离职，无法邀请。请检查邀请群成员参数 user_id_list，去掉已离职的用户。
400232023Chat information review failed while updating the chat.群组相关信息审核没有通过，请检查群名称或群描述中是否存在敏感内容。
400232025Bot ability is not activated.应用未启用机器人能力。你需要登录开发者后台，在应用详情页的 应用能力 > 添加应用能力 页面内，添加 机器人 能力，并发布应用使配置生效。具体操作参见机器人能力。
400232030Your request specifies a user_id which is invalid.请检查user_id是否正确。
400232032The operator who will create the chat and the designated chat owner must be in the same tenant.指定的群主需要与本接口的操作者在同一个租户中。
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.应用在本租户下未安装或未启用。需要先安装应用，再使用应用调用接口。
400232037The operator or invited bots does NOT have the authority to manage chat labels without the scope.操作者或受邀的机器人没有权限管理群Label，请检查权限配置。
400232042Public group chat's name should not be empty.创建公开群时需要指定群名称。
400232043Your request contains unavailable ids.传入的 ID 列表中有无效的 ID，请检查 ID 列表，包括 bot_id_list 和 user_id_list。
400232057The operator tenant doesn't have the permission to use restricted mode.操作者所属的租户没有权限使用保密模式，请联系租户管理员。保密模式的适用版本与功能介绍，参见会话保密模式。
400232068The group is being created, please wait a moment.群组正在创建中，请稍等。
400232069current chat type unsupported to set public.不支持群类型为公开（public）的外部群。
400232091Due to the security control requirements of this tenant, this tenant does not allow public group.租户管理员设置不允许创建公开群。详情参考管理员管控公开群权限。
400232095The operator does NOT have the authority to manage ocic type tag without the scope.没有权限操作ocic类型的群。
400232078The operator tenant doesn't have the permission to use hide_member_count_setting.操作者所属租户无权使用隐藏群成员数量配置。
400232079Chat type not supported by hide_member_count_setting.群类型不支持设置隐藏群成员数量。

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

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

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