快速開始

私聊開放接口已實作，可在測試空間聯調。API 域名及空間開通由平台提供；所有業務請求使用服務端 AppKey／AppSecret 簽章。

1. 準備測試空間

在控制台選擇應用與測試空間，建立憑證。確認已開通私聊，並由平台配置模型和 AI 任務。測試／正式各自配置，不能共用憑證或資料。詳見應用與工作空間。

2. 配置回呼和角色

• 配置、驗證並啟用 MESSAGE 訊息回呼。
• 在控制台建立、發布角色並綁定 personaUid，或用角色 API。
• 如需同步角色變更，另開通 PERSONA 通知回呼。
• 如需同步查詢或動作，再配置業務工具及其回呼。

3. 簽章自檢

使用驗證與簽章中的示例呼叫 /api/open/v1/auth/check。使用平台提供的 HTTPS 域名，請勿把密鑰放進前端程式。

4. 同步使用者並傳送訊息

下載 open-api.mjs，在同一目錄建立下面的 Node.js 腳本，設定 OMNICHAT_BASE_URL、OMNICHAT_APP_KEY、OMNICHAT_APP_SECRET 及已發布角色的 OMNICHAT_PERSONA_UID 環境變數後執行：

import { openPost } from './open-api.mjs'
import { randomUUID } from 'node:crypto'
if (!process.env.OMNICHAT_PERSONA_UID) throw new Error('缺少角色 UID')
await openPost('/api/open/v1/users/sync', {
  userId: 'integration-user-001', nickname: '測試使用者', status: 'ACTIVE'
})
const eventId = randomUUID()
// 網路重試時保留這個 eventId；openPost 每次會重新簽章。
console.log(await openPost('/api/open/v1/chat/events', {
  eventId, type: 'message', personaUid: process.env.OMNICHAT_PERSONA_UID,
  userId: 'integration-user-001', text: '你好'
}))

完整使用者同步會覆蓋省略欄位，請僅用專門的測試使用者執行這個示例。受理結果不含 AI 回覆，請到接入方訊息回呼端確認收到文字。

5. 驗證再上線

• 重送同一 eventId，確認不重複處理。
• 用同一回呼事件 ID 重送到自己的接收器，確認不重複展示／執行。
• 驗證暫停、錯誤、工具 EXECUTE／NOTIFY 以及通知重試。
• 正式空間獨立建立憑證、角色、任務和回呼，再切換到正式憑證。

控制台互動測試使用平台收件箱，不能替代這次 API 回呼聯調；同步外部工具仍可能真實執行。