Quick start

Private-chat APIs are implemented and available for integration in a test workspace. Obtain the API host and workspace access from the platform. All business calls use server-side AppKey/AppSecret signing.

1. Prepare a test workspace

Select your application and test workspace in the console and create credentials. Confirm private chat is authorized and the platform has configured models and AI tasks. Test and production use separate credentials and data. See applications and workspaces.

2. Configure callbacks and a character

• Configure, verify, and enable a MESSAGE message callback.
• Create and publish a character and bind its personaUid in the console, or use the character API.
• To synchronize character changes, also configure a PERSONA notification callback.
• Add business tools and their callback configuration when synchronous queries or actions are needed.

3. Check authentication

Call /api/open/v1/auth/check using the signing example. Use the provided HTTPS host and keep secrets out of frontend code.

4. Sync a user and send a message

Download open-api.mjs. Save the following Node.js script beside it. Set OMNICHAT_BASE_URL, OMNICHAT_APP_KEY, OMNICHAT_APP_SECRET, and the published character's OMNICHAT_PERSONA_UID in your environment, then run it:

import { openPost } from './open-api.mjs'
import { randomUUID } from 'node:crypto'
if (!process.env.OMNICHAT_PERSONA_UID) throw new Error('Missing character UID')
await openPost('/api/open/v1/users/sync', {
  userId: 'integration-user-001', nickname: 'Test user', status: 'ACTIVE'
})
const eventId = randomUUID()
// Preserve this eventId for network retries; openPost signs every request anew.
console.log(await openPost('/api/open/v1/chat/events', {
  eventId, type: 'message', personaUid: process.env.OMNICHAT_PERSONA_UID,
  userId: 'integration-user-001', text: 'Hello'
}))

Full synchronization overwrites omitted user fields; only run this example with a dedicated test user. The intake response does not contain the AI reply. Confirm text delivery at your callback receiver.

5. Verify before production

• Resend the same eventId and verify deduplication.
• Replay an identical callback event ID to your receiver and verify it does not display or execute twice.
• Verify pause behavior, errors, tool EXECUTE/NOTIFY modes, and notification retries.
• Independently configure credentials, characters, tasks, and callbacks in production before switching credentials.

The console test inbox does not replace this API callback test. Synchronous external tools may still perform real operations during console tests.