WebSocket Reference
The Uchara platform exposes two WebSocket endpoints for realtime chat: one for visitors (the embedded widget) and one for agents (the dashboard). Both are upgraded from the same base URL and use JSON text frames.
Connection
Section titled “Connection”WebSocket endpoints are served from the API base URL with the ws/wss scheme:
wss://api.uchara.com/ws/visitorwss://api.uchara.com/ws/agentVisitor route
Section titled “Visitor route”GET /ws/visitor?token=<visitor_jwt>&conv=<conversation_id>token— the visitor JWT returned byPOST /v1/widget/session(required).conv— the conversation id to subscribe to. When omitted, the connection is placed in a temporary room until a conversation is created.
The visitor token is sent as a query parameter, which the backend requires. Query strings can be logged by proxies, so treat the token as sensitive.
Visitor → server messages
Section titled “Visitor → server messages”| Type | Payload | Description |
|---|---|---|
ping | — | Keepalive. The server replies with pong. |
typing | {"conversation_id": "..."} | Start a typing indicator. |
typing.stop | {"conversation_id": "..."} | Stop a typing indicator. |
presence.heartbeat | — | Keep the visitor marked online. |
Agent route
Section titled “Agent route”GET /ws/agent?token=<agent_jwt>&room=<room_id>token— a valid agent JWT (required). Inactive (deactivated) members are rejected.room— the room to subscribe to. Defaults toinbox(the shared agent inbox). Passroom=<conversation_id>to subscribe to a specific per-conversation room.
Agent → server messages
Section titled “Agent → server messages”| Type | Payload | Description |
|---|---|---|
ping | — | Keepalive. The server replies with pong. |
typing | {"conversation_id": "..."} | Start a typing indicator (only for conversations assigned to the agent). |
typing.stop | {"conversation_id": "..."} | Stop a typing indicator. |
presence.heartbeat | — | Keep the agent marked online. |
Events are broadcast to rooms. The inbox room receives workspace-wide events
(new conversations, new messages, presence, typing). Visitors subscribe to their
conversation’s room; agents can subscribe by passing room=<conversation_id>.
Keepalive
Section titled “Keepalive”The server sends WebSocket ping frames periodically. Clients should reply with
pong frames (or send {"type":"ping"} application messages) to keep the
connection alive. The server closes connections that do not respond within the
pong wait window.