个人资料

关系能力

内容能力

互动评论

私信群聊

私信管理

群聊管理

意向用户管理

经营工具

企业号开放能力（内测结束暂不开放）

生活服务开放能力

工具能力

服务市场开放能力

小程序推广计划

联合授权

发送私信消息

我的收藏

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

注意：

该接口涉及 scope 在用户点击授权，开发者获取到 code 调用 /oauth/access_token/ 接口时，返回的 scope 参数中将不再包含该 scope；授权(authorize), 取消授权(unauthorize) Webhook 事件中 scope 参数同样不会包含该 scope，开发者仍可以使用该 access_token 调用本接口。

授权用户可以在设置-账号与安全-授权管理-经营授权中查看 / 取消已授权的 im 能力。抖音开放平台将于近期补齐 access_token 返回 im 相关 scope 的能力。

使用限制

•

该能力需要用户进行 web 扫码授权，当前仅支持一个用户授权一个应用，详见授权概述。

•

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

使用场景

场景一：回复私信消息

•

调用本接口时 scene 字段可选传入 im_reply_msg

•

需要开发者订阅“接收私信消息事件”，从 webhook 解析出 msg_id 字段，时效为 24 小时。

•

仅支持消息回复，在用户未发送下一条消息前，24 小时 内可向用户发送 6 条消息。

•

最新规则以抖音 app 内发送消息为准

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

•

调用本接口时 scene 字段需传入 im_enter_direct_msg

•

需要开发者订阅 “接收用户进入私信会话页事件”，从 webhook 解析出 conversation_short_id 字段

•

开发者需要在接收用户进入私信会话页事件 webhook 30 秒内，调用本接口发送消息

•

对于每条接收用户进入会话页 webhook，开发者最多可以调用 3 次本接口，发送 3 条消息；单日最多回复 3 条 webhook （单日总计可向同一用户发送 1 - 9 条消息）

•

两次回复 webhook 的时间间隔需在 1 小时以上

•

最新规则以抖音 app 内发送消息为准

场景三：B2B场景私信触达

•

调用本接口时 scene 字段需传入 im_b2b_direct_message

•

需要接受方身份为认证企业号及其员工号和小程序品牌号及员工号，且授权过 im.direct_message 私信管理能力

•

调用本接口时 content_list 字段必传且最多支持传入 3 条消息，其中必有 1 条小程序卡片消息

•

调用本接口时返回值 msg_list 字段表示发送成功的消息 ID 列表

•

每对发送方与接收方每日最多互动 1000 条消息

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

•

调用本接口时 scene 字段需传入 im_authorize_message

•

有关移动网站应用发送主动私信的流程，详见小程序主动私信能力概述

•

需要发送方身份为认证企业号及其员工号和小程序品牌号及员工号

•

消息接收方需要通过主动授权私信 button 组件授权给消息发送方；消息接收方成功授权消息发送方后，消息发送方每自然日可调用1次本接口进行主动私信持续触达场景的消息发送，且限制每自然日最多触达5000个消息接收方，超过将被系统拦截

•

调用本接口时 content_list 字段必传，且最多支持传入 3 条消息。

•

调用本接口时返回值 msg_list 字段表示发送成功的消息 ID 列表

接口说明

•

若要发送用户公开视频，还需 Scope: video.list.bind 需要申请权限需要用户授权

•

若要发送留资卡片，还需 Scope: im.message_card 需要申请权限需要用户授权

•

若要发送小程序引导卡片，还需 Scope: im.microapp_card 需要申请权限无需用户授权

•

若要发送图片相关消息，还需 Scope: tool.image.upload 需要申请权限无需用户授权

基本信息

名称	描述
HTTP URL	https://open.douyin.com/im/send/msg/
HTTP Method	POST
Scope	im.direct_message
权限要求	新能力上线能力实验室后，经营者可在“控制台-能力管理-能力实验室”中申请。后期能力若转为正式开放能力，可在“控制台-能力管理-互动管理”中申请。

请求头

名称	类型	是否必填	描述
Content-Type	string	true	固定值 "application/json"
access-token	string	true	调用 /oauth/access_token/ 生成的 token，此 token 需要经营者授权示例： `act.1d1021d2aee3d41fee2d2adfwdf56badMFZnrhFhfWotu3Ecuiuka27L56lr`

请求参数

Query

名称	类型	是否必填	描述	示例
open_id	string	true	调用/oauth/access_token/ 获取，用户唯一标志	ba253642-0590-40bc-9bdf-9a1334b94059

Body

名称	类型	是否必填	描述	示例
msg_id	string	false	消息id，场景一、场景二必传 •场景一：来源于接收私信消息事件，对应 webhook 的 content 中 server_message_id 字段（有效期为24小时） •场景二:来源于接收用户进入私信会话页事件，对应 webhook 的 content 中 server_message_id 字段（有效期为24小时）	@9VxXwOOLDZg4JyKuOM0+Qc79fadf12foPP+BPpJ3qw2uLFARa/H760zdRmYqig357zEBqu7zZ/C7rfG4tqP82908PQ==
conversation_id	string	false	会话 id，场景一、场景二必传 •场景一：来源于接收私信消息事件，对应webhook 的 content 里的 conversation_short_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 •问题引导卡 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 •问题引导卡 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

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

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

群聊邀请卡片 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
        }
    }
}

问题引导卡 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

请求示例

场景一回复消息示例

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

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

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

场景三 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"
}'

场景四主动私信持续触达示例

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 为空
200	28001038	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.retain_consult_card 为空 •content.retain_consult_card.card_id 为空 •card_id 不合法
200	28004018	用户未授权 im.message_card scope 权限	引导用户授权 im.message_card scope
200	28029025	不存在该消息卡片	检查消息卡片是否存在
群聊邀请卡片
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	•优惠券信息不存在 •优惠券状态不可用	检查优惠券信息 & 状态
主动私信授权卡片
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不合法
200	28001038	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生成失败	检查传参是否正确

发送私信消息在线调试

使用限制

使用场景

场景一：回复私信消息

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

场景三：B2B场景私信触达

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

接口说明

基本信息

请求头

请求参数

Query

Body

content 构造

文本 content

图片 content

视频 content

留资卡片 content

群聊邀请卡片 content

小程序引导卡片 content

小程序券 content

主动私信授权卡片 content

问题引导卡 content

请求示例

响应参数

响应示例

正常示例

异常示例

错误码

发送私信消息