主动消息接口

为一位外部用户生成主动消息。

http

POST /open/v1/outbound-message

请求字段

字段	类型	必填	说明
`messageId`	string	是	1—64 个字符；仅允许字母、数字、点、下划线、冒号和连字符
`scenario`	string	是	主动消息场景
`externalUserId`	string	是	外部用户稳定标识，最长 128 个字符
`externalUserName`	string	否	用户昵称，最长 64 个字符
`externalUserMaskedId`	string	否	脱敏业务标识，最长 64 个字符
`conversationKey`	string	否	会话键，默认 `default`，最长 128 个字符
`language`	string	否	`zh-CN`、`zh-TW` 或 `en-US`；默认 `zh-CN`
`tone`	string	否	`friendly`、`warm`、`professional` 或 `concise`；默认值由场景决定
`responseLength`	string	否	`short`、`medium` 或 `long`；中文默认 `short`，英文默认 `medium`
`context`	object	否	本次触达所需上下文
`context.facts`	array	视场景	最多 5 条可信事实；`reminder` 至少 1 条
`context.facts[].content`	string	是	单条事实 1—200 个字符，总计不超过 1000 个字符；只能传已核实数据

context.facts 不接受用户提示词、角色指令或代码块。涉及时间的事实应在内容中写明明确日期，避免生成含糊或过期的提醒。

回复长度

`responseLength`	适合的输出
`short`	一句简洁消息，只表达一个明确目的，适合欢迎和召回
`medium`	一到两句自然消息，补充必要上下文，让用户容易回复
`long`	两到三句较完整消息，但仍保持适合私聊发送

长度档位控制内容详略，是生成偏好，不是精确字符数合同。生成内容略长于偏好时，不会仅因长度而失败。

场景规则

`scenario`	用途	前置条件	默认 `tone`
`welcome`	首次欢迎或新用户引导	不要求历史记录	`friendly`
`follow_up`	继续跟进已有话题	必须存在历史记录	`friendly`
`reengagement`	召回较久未互动的用户	必须存在历史记录	`warm`
`reminder`	根据明确事实生成提醒	`context.facts` 至少一条	`concise`
`recommendation`	根据兴趣或事实生成推荐	需要历史记录或事实	`friendly`
`check_in`	低打扰的关怀或回访	不要求历史记录	`warm`

请求示例

json

{
  "messageId": "out_20260722_001",
  "scenario": "reminder",
  "externalUserId": "customer_10086",
  "conversationKey": "after_sales",
  "language": "zh-CN",
  "tone": "concise",
  "responseLength": "short",
  "context": {
    "facts": [
      { "content": "订单 A1024 已于今天发出" }
    ]
  }
}

成功响应

字段	类型	说明
`code`	number	`0` 表示请求处理成功
`message`	string	结果说明
`requestId`	string	服务端请求标识
`messageId`	string	原请求标识
`status`	string	`generated` 或 `skipped`
`replyType`	string	生成成功时的回复类型
`replyText`	string	生成成功时的回复内容
`skipCode`	number	跳过时的原因码
`skipReason`	string	跳过时的说明

业务应尊重 skipped 结果，不要把跳过改造成无条件发送。

generated 只表示灵谐已经生成内容，不表示外部用户已经收到消息。调用方仍需负责实际发送，并自行记录投递结果。

主动消息接口 ​

请求字段 ​

回复长度 ​

场景规则 ​

请求示例 ​

成功响应 ​