想在抖音私信里给用户发一张小程序引导卡片或券卡片，很多人第一反应是去找「卡片怎么做」。其实在开放平台的发送私信消息接口里，卡片只是消息体的一种，真正先要定的是这条消息属于哪一种发送场景。场景不同，必须带的字段、能发的条数和前置条件都不一样。下面按2026年11月13日（北京时间）核读的抖音开放平台文档，把这件事讲清楚。

卡片是消息体的一种，场景是另一层

抖音开放平台「线索能力开放」页在「发送组件消息」部分列出了发送私信消息接口的请求结构：接口地址为 https://open.douyin.com/im/send/msg/ ，对应的权限 scope 是 im.direct_message。请求体里，content 是消息体，文档列出的可选构造包括文本、图片、视频、留资卡片、群邀请卡片、小程序引导卡片、小程序券、主动私信卡片、问题引导卡和线索组件。

与 content 并列的，还有一个必填字段 scene，即私信场景。文档写了四种：

- 场景一：默认场景，可选传入 im_reply_msg

- 场景二：用户主动进入私信会话页，必传 im_enter_direct_msg

- 场景三：B2B 场景私信触达，必传 im_b2b_direct_message

- 场景四：主动私信持续触达，必传 im_authorize_message

所以「发一张卡片」需要回答两个问题：发什么（content 里放哪种卡片），以及在什么前提下发（scene 选哪一种）。前一个是素材问题，后一个决定这条消息能不能发出去。

场景一、二：跟着用户的动作走，要带消息 ID 和会话 ID

场景一和场景二都由用户先行动触发。按文档，这两种场景下 msg_id、conversation_id 和 content 都是必传：

- msg_id 来源于 Webhook 事件 content 中的 server_message_id。场景一对应「接收私信消息」事件，场景二对应「接收用户进入私信会话页」事件，文档在两处都注明有效期为24小时。

- conversation_id 来源于同一事件 content 里的 conversation_short_id，文档注明长期有效。

这里的读法是：会话 ID 可以长期保存，但用于这两个场景的消息 ID 有24小时有效期。如果打算「用户来问之后再找时间补发一张卡片」，要先确认手上的消息 ID 是否还在有效期内。文档没有在该处展开超过有效期后的完整发送规则，本文不替它补写结论。

小程序文档「接入 IM 消息收发能力」给了一个场景二的例子：用户进入经营者的私信会话页时，开发者会收到 im_enter_direct_msg 事件，从中取出会话 ID 和消息 ID，再调用发送私信消息接口下发问候内容，例子里构造的是一张主动私信授权卡片，scene 填 im_enter_direct_msg。

场景三、四：一次最多三条，主动触达有前提

场景三和场景四不是对某一条用户消息的回复，所以用的是 content_list 而不是单条 content。文档写明：场景三、场景四必传 content_list，最多支持三条消息；场景三必须包含一条小程序卡片消息。

场景四对应主动私信持续触达。同一篇小程序教程写的是：用户点击主动私信授权卡片并向经营者授权后，经营者每天可以向该用户主动触达一次；教程示例构造了一张小程序引导卡片，发送时不需要填写 msg_id 和 conversation_id，scene 填 im_authorize_message。换句话说，没有用户授权，就谈不上用这个场景发卡片。

教程示例里的小程序引导卡片，字段包括卡片模板 ID、小程序 app_id、页面 path 和 query。卡片模板要先通过「创建/更新小程序引导卡片模板」接口准备好，小程序私信、群聊能力概述页把这类接口归在 im.microapp_card 权限下。

别漏了 channel 字段和能力前提

请求体里还有一个容易忽略的 channel 字段。文档写明调用发送消息接口时必须传入，取值为：1 表示人工回复，2 表示智能客服回复（官方或第三方智能客服），3 表示自动消息，即欢迎语、关键词自动回复等规则配置类消息。同一张卡片，是人工发、智能客服发还是规则自动发，要如实标注。

能力前提也分两条线。小程序这边，教程和能力概述页写明要在开发者后台「设置 - 关联设置 - 抖音号管理」为小程序经营者申请小程序发送私信能力，并在开发配置里配置 Webhook 回调地址、订阅相关事件。线索能力开放页面向的是网站应用，页上写明私聊消息能力需要用户授权、当前一个用户只能授权一个应用、开放范围为线索投广商家，并注明「私信能力已不支持新增准入」。本文按页面原文转述，不推断哪些账号仍能新开通，以控制台实际显示为准。

发卡片前的核对顺序

- 这条消息是回复用户私信、回应用户进入会话、B2B 触达，还是对已授权用户的主动触达

- 场景一、二：是否拿到了对应事件里的消息 ID 和会话 ID，消息 ID 是否仍在24小时有效期内

- 场景三、四：是否用 content_list，条数是否不超过三条，场景三是否包含小程序卡片

- 场景四：用户是否已经完成主动私信授权

- 卡片本身：小程序引导卡片模板是否已创建，app_id、path、query 是否对应正确页面

- channel：这次发送属于人工、智能客服还是自动消息

- 账号与应用：是否已申请发送私信能力、配置 Webhook，网站应用是否属于文档写明的开放范围

把场景放在卡片前面判断，能少走很多弯路：卡片做得再好，场景不匹配、字段不全或缺少授权，消息依然发不出去。以上为本轮核读的公开文档表述，未登录开发者后台实测发送，具体以控制台权限和接口实际返回为准。

参考资料

[1] 抖音开放平台：线索能力开放 https://developer.open-douyin.com/docs/resource/zh-CN/dop/ability/enterprise-account-open-ability/leads-b2c-im-ability/clue-component-open，页内能力更新说明最近一条为 v1.0.5（2026.6），访问日期2026-11-13（北京时间）。引用范围：发送私信消息接口地址与 im.direct_message 权限；msg_id、conversation_id 的来源与有效期；content 可选消息类型；scene 四种场景；content_list 最多三条及场景三须含小程序卡片；channel 取值；网站应用私聊消息能力的授权、开放范围与「已不支持新增准入」说明。

[2] 抖音开放平台：接入 IM 消息收发能力 https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/open-capabilities/management/im-messaging-access，页上未见独立编辑日期，访问日期2026-11-13（北京时间）。引用范围：小程序发送私信能力与 Webhook 前置条件；进私问候场景使用 im_enter_direct_msg 并携带消息 ID、会话 ID；主动私信持续触达在用户授权后每天可触达一次、使用 im_authorize_message 且无需填写 msg_id 与 conversation_id；小程序引导卡片字段示例。

[3] 抖音开放平台：小程序私信、群聊能力概述 https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/open-capabilities/management/private-domain/private-and-group-message，页上未见独立编辑日期，访问日期2026-11-13（北京时间）。引用范围：发送私信能力对应 im.direct_message 及申请位置；小程序引导卡片模板接口对应 im.microapp_card。