基础能力

触达与营销

订阅消息

分发

搜索能力

私信和群聊

私信管理

群聊管理

群消息管理

群消息 Webhook

发送群消息

撤回群消息

粉丝群管理

经营工具

私域经营常见问题

挂载

支付

运营

生活服务

垂直行业

其它

发送群消息

我的收藏

该接口用于发送群消息

使用限制

•

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

•

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

•

群成员可以撤回自己的消息；管理员只能撤回自己和普通成员的消息；群主能撤回所有人的消息

•

非管理员或非群主撤回消息有2分钟限制

接口说明

•

若要发送用户公开视频，还需 Scope: ma.item.data 需要申请权限需要用户授权

•

用户登陆互动经营工作台后，可通过互动工作经营台-群列表-获取群ID 获取 group_token 字段

基本信息

名称	描述
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	通过 BusinessToken 进行调用示例：`bus_act.1d1021d2aee3d41fee2d2adfwdf56badMFZnrhFhfWotu3Ecuiuka27L56lr`

请求参数

Query

名称	类型	必填	描述	示例
open_id	string	true	经营者唯一标识，可以通过： •小程序登录获取 •通过控制台-能力-私信和群聊-群聊管理授权用户详情页中获取 •其他OpenID获取方式获取	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/kx1Kg0U9qeP

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

发送群消息在线调试

使用限制

接口说明

基本信息

请求头

请求参数

Query

Body

content 构造

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

图片 Content

视频 Content

留资卡片 Content

小程序引导卡片 content

参数说明：

请求示例

响应参数

响应示例

正常示例

异常示例

错误码

发送群消息