主动发送私信

scope: im.authorize_message.admin 需要用户授权 (通过tt.showDouyinOpenAuth)

使用限制

该接口支持两种场景：

发送主动私信（持续触达）【推荐接入】

该场景下，需传入 content_list 参数

普通用户只能主动授权给 1 个服务账号，若普通用户再次向其他服务账号授权服务私信，历史授权记录将被置为无效

授权后长期有效，服务账号可以持续向普通用户发送消息，每天可以调用本接口发送 1 次

最多支持传入 3 条消息，其中必须包含 1 条小程序卡片、小程序券或服务私信授权卡片

若当天发送过服务私信消息，则无法再次发送持续触达消息

旧版小程序主动私信【即将下线，不推荐】

该场景下，需传入 content 参数

普通用户每天可以主动授权给服务账号2次；

每授权一次最多可以发送3条消息；

如果只授权一次，且一直没有调用该接口，则有30天的有效期。

该场景后续将下线，已接入该场景的开发者请尽快迁移至服务私信持续触达场景

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

接口说明

小程序通过平台试运营期后默认获得该能力。注：关于小程序试运营期介绍详情请查看小程序试运营说明。

支持发送文本、图片、视频和小程序卡片

视频需要通过 video.list.bind 单独请求授权，视频只能发布自己公开视频

权限要求
小程序通过平台试运营期后默认获得该能力。注：关于小程序试运营期介绍详情请查看小程序试运营说明。
需要用户授权

content 构造

文本 content

长度限制为 1000 字

不可包含外部 url 链接

"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

方案一：传入 group_id

group_id 即群聊ID，获取方式如下

群聊 WebHook，对应 content 字段中的 conversation_short_id 字段

创建粉丝群，对应返回值中的 group_id

查询群信息，对应返回值中的 group_id

方案二：传入 group_token

group_token 获取方式需要在互动经营工作台群列表界面，在导入粉丝群后点击 "获取群 ID" 获取

"content": {

"msg_type": 9,

"group_invitation": {

"group_id": "@9VwNxuKKBZ03MXG7M8ooWM771FjUAMW/BqhMlDebEmyyzJD7cZENrR868oDbX9xx",

"group_token" : "CgYIASAHKAESTgpMgRzGa429biTLOZKpUpkLgNKB4wTP/iTeFBfgrhQazpSF62U1ImdoTHa5SK4nS0yvdUrF4bpxdMxovADSfnf3HuilL4fS1l8Q8UZO4hoA"

}

小程序引导卡片 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"

}

小程序券 content

coupon_id 获取方式详见查询券模板

activity_id 获取方式详见查询授权用户发放的活动信息

"content" : {

"msg_type" : 11,

"applet_coupon" : {

"activity_id" : 123222, // 必传，活动 ID

"coupon_meta_id" : 123015333, // 必传，券 ID

}

服务私信授权卡片 content

"content" : {

"msg_type" : 12,

"auth_private_message_card" : {

"app_info" : {

"app_id" : "tt_dadaf12314", // 必传，授权小程序

}

"to_user_info" : {

"open_id" : "ad134dafdaf", // 必传，授权 B 端用户 OpenID

"app_id" : "tt_dadfadfa", // 必传，授权 B 端用户 OpenID 对应 AppID

}

请求示例

1、服务私信场景

curl -X POST 'https://open.douyin.com/im/authorize/send/msg/?open_id=aa-aa-aa' \

-H 'Content-Type:application/json' \

-H 'access-token:act.1d1021d2aee3d41fee2d2add43456badMFZnrhFhfWotu3Ec' \

--data '{

"content": {

"msg_type": 2,

"image": {

"media_id": "@aaaa"

}

"to_user_id": "bb-bb-xx"

2、服务私信持续触达场景

curl -X POST 'https://open.douyin.com/im/authorize/send/msg/?open_id=aa-aa-aa'

-H 'Content-Type:application/json' \

-H 'access-token:act.1d1021d2aee3d41fee2d2add43456badMFZnrhFhfWotu3E' \

--data '{

"content_list":[

{

"msg_type":9,

"group_invitation":{

"group_token":"CgYIASAgCJ65UHHaub6RtyXRoA"

}

{

"msg_type":10,

"applet_card":{

"card_template_id":"@4F8C16DLO/yAA61JkTKeF2ltKgvvhATKtvrScVZhhxZ/",

"schema":"https://z.douyin.com/lktwYRo",

"app_id":"ttfa394401"

}

{

"msg_type":12,

"auth_private_message_card":{

"app_info":{

"app_id":"ttfa394401"

"to_user_info":{

"open_id":"_000xzRQpcogh_pSqhCts9e7W5Of",

"app_id":"ttfa394401"

}

"to_user_id":"_000ynv23O0h8bE93sezQfzLOPsV"

}' \

Bearer Token

在 Header 添加参数

Authorization

，其值为在 Bearer 之后拼接 Token

示例：

Authorization: Bearer ********************

curl --location --request POST 'http://dev-cn.your-api-server.com/im/authorize/send/msg/?open_id=aa-aa-aa' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "content": { "msg_type": 2, "image": { "media_id": "@aaaa" } }, "to_user_id": "bb-bb-xx" }'

主动发送私信

使用限制

接口说明

content 构造

文本 content

图片 content

视频 content

群聊邀请卡片 content

小程序引导卡片 content

小程序券 content

服务私信授权卡片 content

请求示例

请求参数

返回响应

主动发送私信

使用限制#

接口说明#

content 构造#

文本 content#

图片 content#

视频 content#

群聊邀请卡片 content#

小程序引导卡片 content#

小程序券 content#

服务私信授权卡片 content#

请求示例#

请求参数

返回响应

使用限制

接口说明

content 构造

文本 content

图片 content

视频 content

群聊邀请卡片 content

小程序引导卡片 content

小程序券 content

服务私信授权卡片 content

请求示例