核心概念

请求与响应约定

• 请求正文统一使用 UTF-8 编码的 JSON，并设置 Content-Type: application/json。
• 未在接口文档中声明的 JSON 字段会被拒绝，并返回 40001，不会被静默忽略。
• 只有 HTTP 状态为 2xx 且响应中的 code 为 0，才表示本次业务请求已被成功处理。
• 每次响应都包含 requestId。记录调用日志或反馈问题时请保留它，但不要记录 API Key。

外部用户

externalUserId 是调用方提供的稳定用户标识，必填且最长 128 个字符。它不要求是灵谐账号，但同一个人应始终使用同一个值。

可选字段：

• externalUserName：便于后台识别的昵称，最长 64 个字符。
• externalUserMaskedId：脱敏后的业务标识，最长 64 个字符。

会话

一段上下文由 externalUserId + conversationKey 共同确定。conversationKey 为空时使用 default，最长 128 个字符。

如果同一用户同时有“售前咨询”和“售后服务”，应使用两个稳定的 conversationKey，避免上下文混合。不要为每条消息生成新的会话键。

消息幂等

messageId 是调用方生成的请求唯一标识。相同消息重试必须复用原值；新消息必须使用新值。系统用它避免因网络重试产生重复回复。

主动消息场景

主动消息必须说明触发目的：welcome、follow_up、reengagement、reminder、recommendation 或 check_in。系统会结合用户历史、事实和场景决定生成回复或跳过。

时间字段

批量任务响应中的 createdAt、updatedAt、completedAt、finishedAt 均为 Unix 毫秒时间戳。