个人资料

关系能力

内容能力

搜索能力

私信群聊

群聊管理

粉丝群管理

群消息管理

发送群消息

群消息 Webhook

经营工具

生活服务开放能力

工具能力

服务市场开放能力

小程序推广计划

联合授权

发送群消息

我的收藏

该接口用于发送群消息。

•

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

•

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

使用限制

•

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

•

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

•

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

•

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

接口说明

•

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

•

若要发送文字链接/图片链接/电话拨打/留资卡片，还需 Scope: im.message_card 需要申请权限需要用户授权

•

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

•

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

基本信息

名称	描述
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

参数说明：

请求示例

响应参数

响应示例

正常示例

异常示例

错误码

发送群消息