私聊 API
已實作，先在測試空間聯調。服務域名由平台提供；以下接口均使用 POST、Content-Type: application/json 及請求簽章。
接入順序
- 在控制台發布並啟用角色的私聊配置，綁定
personaUid；由平台確認當前空間的私聊場景、模型及 AI 任務已配置。 - 配置並驗證訊息回呼。
- 同步使用者，再推送訊息或業務事件。
- 收到的是受理結果；角色回覆由回呼另行送達。
平台按「角色＋使用者」自動建立或復用開放會話，不需要建立會話的 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 恢復。暫停會拒絕新輸入、取消尚未發出的回覆；已送出的外部操作不能撤回。接口也會按角色和使用者找到或建立會話，要求使用者已同步、角色私聊可用。角色整體停用在控制台操作。