快速开始

私聊开放接口已实现，可在测试空间联调。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 回调联调；同步外部工具仍可能真实执行。

快速开始 ​

1. 准备测试空间 ​

2. 配置回调和角色 ​

3. 签名自检 ​