Private chat API
Implemented and ready for integration in your test workspace. Obtain the API host from the platform. All business endpoints use POST, Content-Type: application/json, and request signing.
Integration sequence
- Publish and enable a character's private-chat configuration and bind its
personaUid. Have the platform confirm scene access, models, and AI task configuration in the workspace. - Configure and verify a message callback.
- Sync the user, then send a message or business event.
- The immediate response acknowledges intake; character replies arrive separately through the callback.
The platform creates or reuses a conversation for the character–user pair. There is no conversation-creation API to call. A first business event can also create a conversation, but its definition must already exist and be enabled in the console.
Identifiers
| Field | Meaning |
|---|---|
personaUid | Your character account UID, unique within the workspace; bind it in the console |
personaId | OmniChat character ID as a string; an alternative to personaUid. If both are supplied, they must identify the same character |
userId | Your previously synced user ID; at most 128 characters, excluding the test: prefix |
eventId | Your input ID, at most 80 characters; preserve it on retries |
Credentials determine the workspace. Requests cannot select characters or users from another workspace. Keep IDs as strings to avoid integer precision loss.
Send a message
POST /api/open/v1/chat/events
{"eventId":"evt-001","type":"message","personaUid":"anchor-001","userId":"u-1001","text":"Hello"}Text is limited to 4,000 characters. Image and video inputs are not supported. Consecutive inputs received close together may be combined into one reply run.
Success response:
{"code":"OK","message":"success","data":{"accepted":true,"conversationId":"1234567890","behavior":"respond"}}Acceptance does not mean that AI generation or an action has completed. One input may produce zero, one, or multiple messages.
Send a business event
Use the same endpoint with type: "event":
{"eventId":"evt-002","type":"event","personaUid":"anchor-001","userId":"u-1001","code":"vip_upgraded","parameters":{"level":"Gold"}}First define and enable vip_upgraded, its level parameter, and its meaning in Events and tools. This is an example identifier, not a predefined event. The platform validates parameters and supplies the configured description to the AI.
The response uses the same envelope. behavior: "respond" schedules a response; record only records a fact for subsequent conversation.
Deduplication and retries
The deduplication scope is workspace, conversation, input type, and eventId. The same ID in different conversations, or used once for a message and once for a business event, represents different inputs. We recommend globally unique IDs.
Identical retries in that scope do not repeat processing; different content returns 409. Business events compare the event code and parameters. Keep eventId on retries but generate a fresh signing timestamp and nonce. An Idempotency-Key header is not a substitute. If character or event availability changes, validation may reject a retry before deduplication.
An unsynced user returns 404. Unpublished or paused characters, unavailable private chat, and paused conversations return 409. See errors and rate limits.
Pause or resume
POST /api/open/v1/chat/control
{"personaUid":"anchor-001","userId":"u-1001","paused":true}{"code":"OK","message":"success","data":{"conversationId":"1234567890","paused":true}}paused is required; use false to resume. Pausing rejects new input and cancels unsent replies. External operations already sent cannot be undone. This endpoint also finds or creates the pair's conversation and requires a synced user and an available private-chat character. Pause an entire character in the console.