该接口用于向目标用户发送私信。

使用限制

    需要申请权限在开发者后台-设置-关联设置-抖音号管理为小程序经营者申请小程序发送私信能力,当前仅支持一个用户授权一个应用;

使用场景

场景一:回复私信消息

    调用本接口时 scene 字段可选传入 im_reply_msg。
    仅支持消息回复,在用户未发送下一条消息前,24 小时内可向用户发送 6 条消息。
    最新规则以抖音 app 内发送消息为准。

场景二:用户主动进入私信会话页

    调用本接口时 scene 字段需传入 im_enter_direct_msg。
    开发者需要在接收用户进入私信会话页事件 webhook 30 秒内,调用本接口发送消息。
    对于每条接收用户进入会话页 webhook,开发者最多可以调用 3 次本接口,发送 3 条消息;单日最多回复 3 条 webhook (单日总计可向同一用户发送 1 - 9 条消息)。
    两次回复 webhook 的时间间隔需在 1 小时以上。
    最新规则以抖音 app 内发送消息为准

场景三:B2B 场景私信触达

    调用本接口时 scene 字段需传入 im_b2b_direct_message
    调用本接口时 content_list 字段必传且最多支持传入 3 条消息,其中必有 1 条小程序卡片消息。
    调用本接口时返回值 msg_list 字段表示发送成功的消息 ID 列表。
    每对发送方与接收方每日最多互动 1000 条消息。

场景四:主动私信持续触达

    调用本接口时 scene 字段需传入 im_authorize_message
    消息接收方需要通过主动授权私信 button 组件授权给消息发送方;消息接收方成功授权消息发送方后,消息发送方每自然日可调用 1 次 本接口进行主动私信持续触达场景的消息发送,且限制每自然日最多触达 5000 个 消息接收方,超过将被系统拦截。
    调用本接口时 content_list 字段必传,且最多支持传入 3 条消息。
    调用本接口时返回值 msg_list 字段表示发送成功的消息 ID 列表。

接口说明

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

基本信息

名称
描述
HTTP URL
HTTP Method
POST
Scope
im.direct_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

名称
类型
是否必填
描述
示例
msg_id
string
false
消息 id,场景一、场景二必传
    场景一:来源于接收私信消息事件,对应 webhook 的 content 中 server_message_id 字段(有效期为 24 小时)
@9VxXwOOLDZg4JyKuOM0+Qc79fadf12foPP+BPpJ3qw2uLFARa/H760zdRmYqig357zEBqu7zZ/C7rfG4tqP82908PQ==
conversation_id
string
false
会话 id,场景一、场景二必传
    场景一:来源于接收私信消息事件,对应 webhook 的 content 里的 conversation_short_id 字段(长期有效)
@9fdVxXwOOLDZg4JyKuOM0+Qc7912foPP+BPpJ3qw2uLFARa/H760zdRmYqig357zEBqu7zZ/C7rfG4tqP82908PQ==
to_user_id
string
true
消息的接收方 open_id
0da22181-d833-447f1241
content
struct
false
消息体,场景一、场景二必传,见下方 content 构造
    文本 content
    图片 content
    视频 content
    小程序引导卡片 content
    群邀请卡片 content
    小程序券 content
    主动私信卡片 content
    问题引导卡 content
{"msg_type":1,"text":{"text":"文本消息"}}
scene
string
true
私信场景
    场景一:默认场景,可选传入 im_reply_msg
    场景二:用户主动进入私信会话页,必传 im_enter_direct_msg
    场景三:: B2B 场 景私信触达,必传 im_b2b_direct_message
    场景四:主动私信持续触达,必传 im_authorize_message
im_enter_direct_msg
content_list
[]struct
false
场景三,场景四必传,最多支持三条消息
场景三必须包含一条小程序卡片消息
见下方 content 构造
    文本 content
    图片 content
    视频 content
    小程序引导卡片 content
    群邀请卡片 content
    小程序券 content
    主动私信卡片 content
    问题引导卡 content
[{
"msg_type": 1,
"text": {
"text": "文本消息1"
}
}, {
"msg_type": 10,
"applet_card": {
"card_template_id": "@9VwNxuKKBZ03MXG7M8ooWM771FjUAMW/BqhMlDebEmyyzJD7cZENrR868oDbX9xx",
"path": "api/apiPage/apiPage",
"query": "{\"key1\":\"val1\",\"key2\":\"val2\"}",
"app_id": "tt3ergjdge84gdwksb"
}
}, {
"msg_type": 2,
"image": {
"media_id": "@sssssssss"
}
}]

content 构造

文本 content

    text 长度限制为 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 即群聊I D,获取方式如下
    群聊 WebHook,对应 content 字段中的 conversation_short_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 生成方式如下。
    1.通过接口生成 Generate,通过 expire_time 参数控制过期时间,链接过期后需重新生成。
    2.在小程序界面点击右上角 ... >>分享 >>复制链接,链接有效时间为 45 天,链接过期后需重新生成。
"content": { "msg_type": 10, "applet_card": { "card_template_id": "@9VwNxuKKBZ03MXG7M8ooWM771FjUAMW/BqhMlDebEmyyzJD7cZENrR868oDbX9xx", "schema":"https://z.douyin.com/ijBoQwF" "app_id":"tt3ergjdge84gdwksb" } }

小程序券 content

"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 } } }

问题引导卡 content

    发消息,用户点击问题文案后会自动发送点击的问题文案
{ "msg_type": 204, "question_guide_msg_card": { "title": "问题引导卡-发消息-卡片标题", // 卡片标题 "question_list": [ // 最长 6 个 { "text": "1. 问题文案,最长14问题" // 问题文案,最长 14 字 }, { "text": "2. 问题文案,最长14问题" }, ] } }
    发链接,用户点击问题文案后会自动跳转到对应小程序中
{ "msg_type": 205, "question_guide_jump_card": { "title": "问题引导卡-发链接-卡片标题", // 卡片标题 "question_list": [ // 最长 6 个 { "text": "1. 问题文案,最长14问题", // 问题文案,最长 14 字 "jump_type": 1, // 固定值,仅支持跳转小程序 "schema_data":{ "app_id":"ttddf8ab***", // 小程序 appid "path":"api/apiPage/apiPage" // 不能以“/”开头 "query":"{\"key1\":\"val1\",\"key2\":\"val2\"}" } } ] } }
参数说明:
名称
类型
是否必填
描述
示例
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

请求示例

    1.场景一 回复消息示例。
curl -X POST 'https://open.douyin.com/im/send/msg/?open_id=aa-aa-aa' \ -H 'Content-Type:application/json' \ -H 'access-token:act.1d1021d2aee3d41fee2d2add43456badMFZnrhFhfWotu3Ec' \ --data '{ "scene" : "im_reply_msg", "content": { "msg_type": 2, "image": { "media_id": "@aaaa" } }, "msg_id": "@7aaaa==", "conversation_id": "@aaaa==", "to_user_id": "bb-bb-xx" }'
    2.场景二 用户主动进入私信会话页示例。
curl -X POST 'https://open.douyin.com/im/send/msg/?open_id=aa-aa-aa' \ -H 'Content-Type:application/json' \ -H 'access-token:act.1d1021d2aee3d41fee2d2add43456badMFZnrhFhfWotu3Ec' \ --data '{ "scene" : "im_enter_direct_msg", "content": { "msg_type": 1, "text": { "text": "欢迎" } }, "msg_id": "@7aaaa==", "conversation_id": "@aaaa==", "to_user_id": "bb-bb-xx" }'
    3.场景三 B2B 场景私信触达示例。
curl -X POST 'https://open.douyin.com/im/send/msg/?open_id=aa-aa-aa' \ -H 'Content-Type:application/json' \ -H 'access-token:act.1d1021d2aee3d41fee2d2add43456badMFZnrhFhfWotu3Ec' \ --data '{ "scene":"im_b2b_direct_message", "content_list":[ { "applet_card":{ "card_template_id":"@9VxQh6rGTNAjPS/4do48Es771GLpBsO5AK5KkjGdFGpaQUakf09lOuYJDKoF9QSP", "schema":"https://z.douyin.com/hnSQEOG", "app_id":"tt5daf2b12c2857910" }, "msg_type":10 }, { "applet_card":{ "card_template_id":"@9VxQh6rGTNAjPS/4do48Es771GLpBsO5AK5KkjGdFGpaQUakf09lOuYJDKoF9QSP", "schema":"https://z.douyin.com/hnSQEOG", "app_id":"tt5daf2c2857910" }, "msg_type":10 }, { "image":{ "media_id":"@9VxQh6rGTNAjPS/4do48Es6+iib0bqafYog16knsa1AUPKajyHDpflwXvjjBhww4VWWR2GxZKdMJ2NaCTC2xAnvcjeJ4mT1hatJT3UhT8k9qcZbBcecPleqnAvnmmDe2" }, "msg_type":2 } ], "conversation_id":"@9VxQh6rGTNAj0zdRm5v+Zqh7dBO7Y2oEDg==", "to_user_id":"28940f5a-d8-6a8e647431be" }'
    4.场景四 主动私信持续触达示例。
curl -X POST 'https://open.douyin.com/im/send/msg/?open_id=aa-aa-aa' -H 'access-token:act.1d1021d2aee3d41fee2d2add43456badMFZnrhFhfWotu3E' \ -H 'Content-Type:application/json' \ --data '{ "scene":"im_authorize_message", "content_list":[ { "msg_type":9, "group_invitation":{ "group_token":"CgYIASAHKAESTgpMgbhOkXolmVuBxzgHTSv1djIZC+suQHLhxDl+KpBfhJnVQlPzhdRl3xJtwT73Er0zs9e21Oqnh0QvdITcb8mwQgCJ65UHHaub6RtyXRoA" } }, { "msg_type":1, "text":{ "text":"文字消息" } }, { "msg_type":12, "auth_private_message_card":{ "app_info":{ "app_id":"tt506e94401" }, "to_user_info":{ "open_id":"28940f5a-8a74-6a8e647431be", "app_id":"tt506e94401" } } } ], "to_user_id":"3db2ef37-cb3d-bddc6d4e288" }'

响应参数

注意:
新版错误码和响应参数中的 all_send_success、send_msg_status_list 字段逐步放量中,使用过程中出现问题请根据错误码进行排查或及时向平台提交反馈。
名称
类型
描述
示例
extra
struct
description
string
错误码描述
系统内部错误,请重试
error_code
int
错误码
28001005
logid
string
标识请求的唯一ID
02172526999995100000000000000000000ffff0a7aab6399e422
now
int
毫秒级时间戳
1725270001
sub_description
string
子错误码描述
""
sub_error_code
int
子错误码
0
data
struct
error_code
int
错误码
28001005
description
string
错误描述
系统内部错误,请重试
msg_id
string
消息ID,传入content时返回
@9VwDhOCRTcMhM22uc8ptWc790WXgNP+KOpB2qAimKVIVavb/60zdRmYqig357zEB5L4sjFowF986nh70WlYnGg==
msg_list
[]string
消息ID列表,传入content_list时返回
["@9VwDhOCRTcMhM22uc8ptWc790WXgNP+KOpB2qAimKVIVavb/60zdRmYqig357zEB5L4sjFowF986nh70WlYnGg==", @9VwDhOCRTcMhM22uc8ptWc790WXgNP+KOp1wqg2jK1ASaff160zdRmYqig357zEBmnH4hJS/JdX9RB/mz/xohg=="]
all_send_success
bool
所有消息是否发送成功,传入content_list时返回
true
send_msg_status_list
[]struct
所有消息发送状态,传入content_list时返回,顺序与content_list保持一致
error_code
错误码
28029029
description
错误描述
图片信息获取失败

响应示例

正常示例

{ "extra": { "description": "", "sub_error_code": 0, "sub_description": "", "now": 1648797449, "logid": "021648797449846fd1b1111000700600000000000000086dfb920", "error_code": 0 }, "data": { "error_code": 0, "description": "" }, "msg_id": "@c29bfc000+MNggFhRkwGuX1ntuc0RPc0VHKefj/yWEJ8DtjU==" }

异常示例

{ "all_send_success": false, "extra": { "error_code": 28029030, "description": "全部消息发送失败,单条消息发送情况参见send_msg_status_list字段", "sub_error_code": 28029030, "sub_description": "全部消息发送失败,单条消息发送情况参见send_msg_status_list字段", "logid": "02172527001221200000000000000000000ffff0a70750423ef80", "now": 1725270012 }, "send_msg_status_list": [{ "description": "text 不允许传入http超链接", "error_code": 28001038 }, { "description": "图片信息获取失败", "error_code": 28029029 }, { "description": "path 格式错误, 不应以 / 开头", "error_code": 28001007 } ], "data": { "error_code": 28029030, "description": "全部消息发送失败,单条消息发送情况参见send_msg_status_list字段" } }

错误码

HTTP 状态码
错误码
描述
排查建议
200
2100005
参数不合法
根据子错误描述检查请求参数是否填写正常,部分子错误描述如下:
    open_id must have a value
    to_user_id should be string
    to_user_id must have a value
    ......
200
2190001
quota已用完
当前接口所属 scope 免费额度已用完,免费额度每日 8 点刷新,若需提额请向平台提交反馈
200
2190002
access_token无效
刷新或重新授权access-token
200
2190008
access_token过期,请刷新或重新授权
刷新或重新授权access-token
200
2190015
请求参数access_token openid不匹配
检查access-token和open_id参数是否填写正常以及是否匹配
200
28001005
系统内部错误,请重试
请求重试,若依然报错请向平台提交反馈
200
28001038
    content 不合法
    conversation_id参数不合法,conversation_id为空
    conversion_id参数不合法,conversion_id无效
    conversation_id参数不合法,conversation_id无效
    msg_id参数不合法,msg_id为空
    msg_id参数不合法,msg_id无效
    参数错误,缺失消息发送用户
    参数错误,缺失发送消息应用
    主动私信场景最多发送三条消息
    conversation_id与消息发送、接收用户不匹配
    B2B场景最多发送三条消息
    消息中必须包含小程序类卡片
    ... 详见报错描述
根据错误信息检查请求参数是否填写正常
200
28029006
用户未授权应用发送主动私信
引导用户向应用进行主动私信的授权
200
28003070
    超出频控限制次数,老版本主动私信授权场景一天能发送三条消息
    超出频控限制次数,用户进私场景下,对于每条接收用户进入会话页webhook,开发者最多可以调用3次本接口,发送3条消息,单日最多回复3条webhook
    超出频控限制次数,B2B场景每对发送方与接收方每日最多互动1000条消息
    超出频控限制次数,新版本主动私信场景一天能调用接口发一次,一次发三条消息
根据错误信息检查请求频率是否正常
200
28029003
发送用户非小程序品牌号、员工号、授信合作号
200
28003017
今日已发送过老版本主动私信,禁止发送新版本主动私信
避免同时使用新老版本主动私信,逐步将老版本主动私信迁移至新版本
200
28029002
发送消息额度到达上限,上限值:5000
主动私信持续触达场景限制每自然日最多触达5000个消息接收方
200
28003095
线上(互动经营工作台)已有生效消息策略,请先联系用户停用后再发送
停用互动经营工作台后再使用 OpenAPI 发送消息
200
28003080
    消息id与当前场景不匹配
    消息已过期
传入正确的 msg_id 或在收到进私事件后 30s 内调用发送私信接口
200
28022028
两次使用时间必须大于1小时
用户主动进入私信会话页场景两次回复 webhook 的时间间隔需在 1 小时以上
200
28003059
该用户没有开放平台经营者身份
200
28003081
上条消息已经超过24小时,无法回复
回复私信消息时效为 24 小时
200
28003082
消息对象不匹配
消息发送方和接收方与开发者传入的 open_id 和 to_user_id 不匹配
200
28029004
接口发送消息能力已被封禁,请稍后再试
该能力被封禁,联系平台处理
200
28003101
当前用户已被封禁
该能力被封禁,联系平台处理
200
28003018
请求频率过高
降低请求频率重试
200
28029032
系统内部错误,请重试
请求重试,若依然无解请向平台提交反馈
200
28029030
全部消息发送失败,单条消息发送情况参见send_msg_status_list字段
根据send_msg_status_list字段排查单条消息的发送情况,send_msg_status_list字段的顺序与开发者传入的content顺序对应
200
28029031
部分消息发送失败,单条消息发送情况参见send_msg_status_list字段
根据send_msg_status_list字段排查单条消息的发送情况,send_msg_status_list字段的顺序与开发者传入的content顺序对应
文本
200
28001038
    content.text 为空
    content.text.text 为空
    text 长度超过1000
    text 不允许传入http超链接
图片
200
28001038
    content.image 为空
    content.image.media_id 为空
media_id 不合法
media_id 解密失败,请传入正确加密后的media_id
视频
200
28001038
    content.video 为空
    content.video.item_id 为空
item_id 不合法
    item_id 解密失败,请传入正确加密后的 item_id
    获取当前 item_id 关联的视频详细信息失败,请检查视频状态
用户只能分享自己的视频
视频发布者 uid 要与 OpenID 相同
群聊邀请卡片
200
28001038
    content.group_invitation为空
    group_id 与 group_token 都为空
    group_token 无效
    group_token 解析出的user_id 与 open_id 不匹配
小程序引导卡片
200
28001038
card_template_id 不合法
200
28004025
消息卡片模板不存在
检查消息模板卡片是否已创建
200
28029034
该消息模板卡片审核中
200
28029035
该消息模板卡片审核不通过
200
28029026
跳转小程序卡片app_id为空
检查入参 app_id 与 根据模板 id 获取到的app_id是否都为空
200
28029027
跳转小程序卡片app_id不匹配
检查入参 app_id 与 根据模板 id 获取到的app_id 是否匹配
    方案一:传 app_id + query + path
200
28001007
path 格式错误, 不应以 / 开头
    方案二:传 schema + app_id
200
28001038
跳转链接校验失败,请确认跳转路径为有效链接
200
28001007
    跳转链接不合法
    app_id 不合法
    app_id参数不合法,app_id 不合法
    检查跳转链接是否合法
    检查跳转链接解析出的 app_id 与传入的 app_id 是否匹配
小程序券
200
28001038
    content.applet_coupon为空
    content.applet_coupon.activity_id为空
    优惠券信息不存在
    优惠券状态不可用
检查优惠券信息 & 状态
主动私信授权卡片
200
28001038
    content.auth_private_message_card为空
    app_info不合法
    to_user_info不合法
    app_info.app_id 与 to_user_info.app_id 不匹配
    to_user_info.open_id不合法
open_id 非小程序员工号/品牌号/授信合作号
检查用户是否有对应小程序合法 BC 关系
问题引导卡-发消息
200
28001038
    content.question_guide_msg_card为空
    参数错误,问题列表长度大于 6
    参数错误,text 长度大于 14
问题引导卡-发链接
200
28001038
    content.question_guide_jump_card为空
    问题列表长度大于 6
    JumpType 不为 1
    text 长度大于 14
    小程序schema生成失败
检查传参是否正确