个人资料

关系能力

内容能力

搜索能力

私信群聊

群聊管理

粉丝群管理

群消息管理

发送群消息

群消息 Webhook

经营工具

生活服务开放能力

工具能力

服务市场开放能力

小程序推广计划

发送群消息

我的收藏

该接口用于发送群消息。

•

该接口涉及的 scope 在用户点击授权、开发者获取到 code 并调用 /oauth/access_token/ 接口时，返回的 scope 参数中将不再包含该 scope；授权(authorize)，取消授权(unauthorize) Webhook 事件中 scope 参数同样不会包含该 scope。

•

开发者仍可以使用该 access_token 调用本接口。授权用户可以在设置-账号与安全-授权管理-经营授权中查看 / 取消已授权的 im 能力。抖音开放平台将于近期补齐 access_token 返回 im 相关 scope 的能力。

接口说明

•

若要发送用户公开视频，还需 Scope：video.list.bind（需要申请权限、需要用户授权）

•

若要发送留资卡片，还需 Scope: im.message_card（需要申请权限、需要用户授权）

•

若要发送小程序引导卡片，还需 Scope im.microapp_card （需要申请权限、无需用户授权）

•

若要发送图片相关消息，还需 Scope: tool.image.upload （需要申请权限、无需用户授权）

使用限制

•

该能力需要用户进行 web 扫码授权，当前仅支持一个用户授权一个应用，详见授权概述。

•

当前开放用户范围：认证企业号及其员工号和小程序品牌号及其员工号；后续将基于抖音经营者实际诉求逐步拓展开放用户范围。

•

支持发送和回复群消息，回复群消息需订阅群消息 webhook 事件。

•

支持通过互动经营工作台-获取群 ID 生成的 groupID 来发送群消息。

基本信息

名称	描述
HTTP URL	https://open.douyin.com/im/send/msg/group/
HTTP Method	POST
Scope	im.group_message
权限要求	新能力上线能力实验室后，经营者可在“控制台-能力管理-能力实验室”中申请。后期能力若转为正式开放能力，可在“控制台-能力管理-互动权限”中申请

请求头

名称	类型	必填	描述
content-type	string	true	固定值 "application/json"
access-token	string	true	调用 /oauth/access_token/ 生成的 token，此 token 需要用户授权。示例：act.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdy1ydjt

请求参数

Query

名称	类型	必填	描述	示例
open_id	string	true	调用/oauth/access_token/ 获取，用户唯一标识	ba253642-0590-40bc-9bdf-9a1334b94059

Body

名称	类型	是否必填	描述	示例
group_id	string	false	群 id： •场景一：来源于群消息 webhook 事件，对应 content 中的 conversation_short_id 字段 •场景二：来源于查询群信息接口，对应返回值中的 group_id 字段	@ajqacsn7hgejkghkkgdjcg==
content	struct	true	消息体，见下方 content 构造 •文本 content •图片 content •视频 content •留资卡片 content •小程序引导卡片 content	{"msg_type":1,"text":{"text":"文本消息"}}
group_token	string	false	来源于互动经营工作台-群列表-获取群 ID	CgYIASAHKAESTgpMo53Tjr2h2hEe/`kx1Kg0U9qePBfm7YzHYl8umLGTZDcm6aq2XLgMSkBH`/2NpruP

content 构造

文本 Content（长度限制为 150 字）

"content": {
    "msg_type": 1,
    "text": {
        "text": "你好"
    }
}

图片 Content

图片 media_id 获取参见图片上传接口返回 image_id 字段。

"content": {
    "msg_type": 2,
    "image": {
        "media_id": "@sssssssss"
    }
},}

视频 Content

只能发送用户自己公开视频，视频 item_id 获取参见查询授权账号视频列表。

"content": {
    "msg_type": 3,
    "video": {
        "item_id": "@ssssss=="
    }
}

留资卡片 Content

留资卡片 card_id 获取参见创建/更新留资卡片。

"content": {
    "msg_type": 8,
    "retain_consult_card": {
      "card_id": "@9VwNxuKKBZ03MXG7M8ooWM771FjUAMW/BqhMlDebEmyyzJD7cZENrR868oDbX9xx"
    }
 }

小程序引导卡片 content

小程序 card_template_id 获取参见创建/更新小程序引导卡片模板。

必传 app_id ＋ query ＋ path：发消息接口直接传入，无需提前生成。

"content": {
    "msg_type": 10,
    "applet_card": {
      "card_template_id": "@9VwNxuKKBZ03MXG7M8ooWM771FjUAMW/BqhMlDebEmyyzJD7cZENrR868oDbX9xx",
       "path":"api/apiPage/apiPage"
       "query":"{\"key1\":\"val1\",\"key2\":\"val2\"}"
       "app_id":"tt3ergjdge84gdwksb"
    }
 }

参数说明：

名称	类型	是否必填	描述	示例
path	string	true	通过 URL Link 进入的小程序页面路径，必须是已经发布的小程序存在的页面，不可携带 query。path 为空时会跳转小程序主页。	api/apiPage/apiPage
query	string	true	通过 URL Link 进入小程序时的 query（json 形式），若无请填{}。最大 1024 个字符，只支持数字，大小写英文以及部分特殊字符：`{}!#$&'()*+,/:;=?@-._~%``。	{\"id\":\"hebbch\"}
app_id	string	true	小程序 ID	tt3ergjdge84gdwksb

方案：仅传 schema ＋ app_id：schema 生成方式如下：

通过接口生成 Generate，通过 expire_time 参数控制过期时间，链接过期后需重新生成。

在小程序界面点击右上角 ... ＞分享＞复制链接，链接有效时间为 45 天，链接过期后需重新生成。

"content": {
    "msg_type": 10,
    "applet_card": {
      "card_template_id": "@9VwNxuKKBZ03MXG7M8ooWM771FjUAMW/BqhMlDebEmyyzJD7cZENrR868oDbX9xx",
      "schema":"https://z.douyin.com/ijBoQwF"
      "app_id":"tt3ergjdge84gdwksb"
    }
 }

请求示例

curl -X POST 'https://open.douyin.com/send/msg/group/?open_id=aa-aa-aa' \
-H 'Content-Type:application/json' \
-H 'access-token:act.1d1021d2aee3d41fee2d2add43456badMFZnrhFhfWotu3Ec' \
--data '{
    "content": {
        "msg_type": 2,
        "image": {
               "media_id": "@aaaa"
        }
    },
    "group_id": "@7aaaa==",
}'

响应参数

名称		类型	描述	示例
extra		struct
	description	string	错误码描述	""
	error_code	int	错误码	0
	log_id	string	请求的唯一标识	202008121419360101980821035705926A
	now	int	毫秒级时间戳	1597213176393
	sub_description	string	子错误码描述	""
	sub_error_code	int	子错误码	0
data		struct
	error_code	int	错误码	0
	description	string	错误码描述	""
msg_id		string	消息 id	@c29bfc000+MNgg0RPc0VHKefj/yWEJ8hjV==

响应示例

正常示例

{
  "extra": {
    "description": "",
    "sub_error_code": 0,
    "sub_description": "",
    "now": 1648797449,
    "logid": "021648797449846fd1b1111000700600000000000000086dfb920",
    "error_code": 0
  },
  "data": {
    "error_code": 0,
    "description": ""
  }
  "msg_id":"@c29bfc000+MNggFhRkwGuX1ntuc0RPc0VHKefj/yWEJ8uhd=="
}

异常示例

{
  "extra": {
    "sub_description": "",
    "sub_error_code": 0,
    "description": "参数不合法",
    "error_code": 2100005,
    "logid": "202203271807199888808121990491456D",
    "now": 1648375639
  },
  "data": {
    "error_code": 2100005,
    "description": "参数不合法"
  }
}

错误码

HTTP 状态码	错误码	错误码描述	排查建议
200	28001005	系统内部错误，请重试	请求重试，若依然无解请向平台提交反馈
200	28001003	access_token 无效	重新请求生成 access_token
200	28001008	access_token 过期，请刷新或重新授权	重新请求生成 access_token
200	28001016	当前应用已被封禁或下线	clientKey 被封禁或者下线

发送群消息在线调试

接口说明

使用限制

基本信息

请求头

请求参数

Query

Body

content 构造

文本 Content（长度限制为 150 字）

图片 Content

视频 Content

留资卡片 Content

小程序引导卡片 content

参数说明：

请求示例

响应参数

响应示例

正常示例

异常示例

错误码

发送群消息