发送群消息

更新时间 2024-07-24 02:58:49

我的收藏

该接口用于发送群消息

使用限制

•

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

•

支持发送和回复群消息，回复群消息需订阅群消息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 字）

JSON复制
"content": {
    "msg_type": 1,
    "text": {
        "text": "你好"
    }
}

图片 Content

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

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

视频 Content

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

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

留资卡片 Content

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

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

小程序引导卡片 content

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

•

方案一：必传 app_id + query + path：发消息接口直接传入，无需提前生成

JSON复制
"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天，链接过期后需重新生成

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

请求示例

js复制
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==

响应示例

正常示例

json复制
{
  "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=="
}

异常示例

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