私聊 API

已实现，先在测试空间联调。服务域名由平台提供；以下接口均使用 POST、Content-Type: application/json 及请求签名。

接入顺序

1. 在控制台发布并启用角色的私聊配置，绑定 personaUid；由平台确认当前空间的私聊场景、模型及 AI 任务已配置。
2. 配置并验证消息回调。
3. 同步用户，再推送消息或业务事件。
4. 收到的是受理结果；角色回复由回调另行送达。

平台按「角色＋用户」自动创建或复用处于 OPEN 状态的会话，不需要创建会话的 API。首次业务事件也可以创建会话，但事件必须先在控制台定义并启用。

角色与用户标识

字段	说明
personaUid	接入方角色账号 UID，在当前空间唯一，可在控制台绑定
personaId	OmniChat 角色 ID，以字符串发送；可代替 personaUid，两者同传须指向同一角色
userId	接入方用户 ID，须先同步；最长 128 字符，不得以 test: 开头
eventId	接入方生成的输入 ID，最长 80 字符；重试保持不变

凭证决定空间，请求不能跨空间指定角色或用户。建议全部 ID 都使用字符串，避免大整数精度损失。

推送消息

POST /api/open/v1/chat/events

{
  "eventId": "evt-001",
  "type": "message",
  "personaUid": "anchor-001",
  "userId": "u-1001",
  "text": "你好"
}

文本最长 4000 字，目前不接受图片、视频等用户输入。短时间内连续输入可能合并为一次回复。

成功响应：

{
  "code": "OK",
  "message": "success",
  "data": {
    "accepted": true,
    "conversationId": "1234567890",
    "behavior": "respond"
  }
}

accepted 不代表 AI 已完成回复或动作已完成。一次输入可能没有回复，也可能产生多条消息。

推送业务事件

同一接口，type 改为 event：

{
  "eventId": "evt-002",
  "type": "event",
  "personaUid": "anchor-001",
  "userId": "u-1001",
  "code": "vip_upgraded",
  "parameters": { "level": "金卡" }
}

先在控制台「事件与工具」定义 vip_upgraded、参数 level 及含义。平台校验参数，再按事件说明交给 AI 处理。这个标识是示例，并非预置事件。

响应格式与消息相同。behavior 为 respond 时会安排回复，record 时只记录为后续对话的事实。

去重与重试

去重范围为当前空间内的「会话＋输入类型＋eventId」。同一 ID 用在不同会话，或分别用作消息与业务事件，会被视为不同输入。建议接入方生成全局唯一 ID。

同一范围内，相同输入重试不会重复处理；换了内容则返回 409。业务事件比较事件标识和参数。重试保留 eventId，但须重新生成签名时间戳及 nonce；Idempotency-Key 不能代替这个字段。角色或事件配置变更后，重试仍可能在去重前被可用性校验拒绝。

用户未同步返回 404；角色未发布私聊、已暂停，或会话禁止交互时返回 409。错误响应见鉴权与签名。

暂停／恢复交互

POST /api/open/v1/chat/control

{ "personaUid": "anchor-001", "userId": "u-1001", "paused": true }

{
  "code": "OK",
  "message": "success",
  "data": { "conversationId": "1234567890", "paused": true }
}

paused 必填，false 恢复。暂停会拒绝新输入、取消尚未发出的回复；已送出的外部操作不能撤回。接口也会按角色和用户找到或创建会话，要求用户已同步、角色私聊可用。角色整体停用在控制台操作。