主动发送私信

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"

}' \

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

请求参数

Query 参数

open_id

string

必需

通过/oauth/access_token/获取，主动发消息用户唯一标志，与用户主动授权( im_authorize )webhook中from_user_id相等

示例值:

aa-aa-aa

Header 参数

Content-Type

string

必需

示例值:

application/json

access-token

string

必需

调用/oauth/access_token/生成的token
act.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ（与移动应用获取方式一致）

示例值:

act.1d1021d2aee3d41fee2d2add43456badMFZnrhFhfWotu3Ec

Body 参数application/json

content

object

可选

服务私信场景必传，该参数后续将逐步下线，推荐使用 content_list 传参消息体，见下方 content 构造文本 content 图片 content 视频 content 小程序引导卡片 content 群邀请卡片 content 小程序券 content 服务私信卡片 content

msg_type

integer

必需

image

object

必需

to_user_id

string

必需

消息的接收方openid，来自用户主动授权( im_authorize )webhook中to_user_id字段

示例

application/json

Body

err_msg

string

错误信息

必需

err_no

integer

错误码

必需

data

object

响应内容

必需

msg_id

string

消息id

必需

log_id

string

日志id

必需

主动发送私信

使用限制#

接口说明#

content 构造#

文本 content#

图片 content#

视频 content#

群聊邀请卡片 content#

小程序引导卡片 content#

小程序券 content#

服务私信授权卡片 content#

请求示例#

请求参数

返回响应

使用限制

接口说明

content 构造

文本 content

图片 content

视频 content

群聊邀请卡片 content

小程序引导卡片 content

小程序券 content

服务私信授权卡片 content

请求示例