Websocket client events

This page lists all supported events emitted by the client over a Websocket connection and the expected server responses.

Event `session:create`

Create a new session. This event initializes a new conversation session with the server, including optional context and authentication information.

Field	Type	Description
context	ContextObject	Optional context information
identity_token	string	Optional authentication token
timestamp	integer	Required timestamp of the request
is_test	boolean	Optional flag indicating if this is a test session
opt_out	boolean	Optional flag for opting out of data collection

Example payload:

{
  "context": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "language": "en",
    "browser": "Chrome",
    "os": "Windows"
  },
  "identity_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "timestamp": 1678901234,
  "is_test": false,
  "opt_out": false
}

Server responses

On success session:created
On failure
- session:create:error
- session:create:error:invalid_identity_token
- session:create:error:invalid_private_key
- session:create:error:invalid_aes_claims
- session:create:error:failed_aes_descryption

Event `session:context:update`

Used after initial form submission or reconnection. This event updates the session context with new information.

Field	Type	Description
session_id	string	Required session identifier
context	ContextObject	Required context information
timestamp	integer	Required timestamp of the update

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "context": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "language": "en",
    "department": "support",
    "priority": "high"
  },
  "timestamp": 1678901234
}

Server responses

On success session:context:updated
On failure session:context:update:error

Event `session:reconnect`

Reconnect using a previously stored session ID. This event attempts to restore a previous session.

Field	Type	Description
session_id	string	Required session identifier
timestamp	integer	Required timestamp of reconnect

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1678901234
}

Server responses

On success session:reconnected
On failure session:reconnect:error

Event `session:overview`

Check for available live agents and estimated wait times. This event retrieves information about current service availability.

Field	Type	Description
session_id	string	Required session identifier

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

Server responses

On success session:overview
On failure session:overview:error

Event `session:close`

Sent when the user ends the session. This event gracefully terminates the current session.

Field	Type	Description
session_id	string	Required session identifier

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

Server responses

On success: no response expected.
On failure session:status:error

Event `session:rating`

Submit a session rating. This event allows users to provide feedback about their session experience.

Field	Type	Description
session_id	string	Required session identifier
timestamp	integer	Required timestamp of the rating
rating	integer	Required rating value (0–10)
feedback	string	Optional feedback text (max 280 characters)

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1678901234,
  "rating": 9,
  "feedback": "The agent was very helpful and resolved my issue quickly."
}

Server responses

On success session:rated
On failure session:rating:error

Event `session:activity`

Indicates active user interaction. This event keeps the session alive by showing user activity.

Field	Type	Description
session_id	string	Required session identifier
timestamp	integer	Required timestamp of activity

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1678901234
}

Server responses

On success: no response.
On failure session:activity:error

Event `session:history:sync`

Used after reconnecting to retrieve past messages. This event synchronizes the conversation history.

Field	Type	Description
session_id	string	Required session identifier
timestamp	integer	Required timestamp of sync

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1678901234
}

Server responses

On success session:history:synced
On failure session:history:sync:error

Event `conversation:reopen`

Reopen a resolved live agent conversation. This event reactivates a previously closed conversation.

Field	Type	Description
session_id	string	Required session identifier

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

Server responses

On success: no response.
On failure session:status:error

Event `message:send`

Send a message (text or media). This event allows users to send messages and attachments to the conversation.

Field	Type	Description
input	object	Message content and attachments
session_id	string	Required session identifier
context	ContextObject	Optional context information
timestamp	integer	Required timestamp of the message

Example payload:

{
  "input": {
    "text": "Hello, I need help with my account",
    "type": "text",
    "attachments": [
      {
        "type": "image",
        "mime_type": "image/jpeg",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "url": "https://example.com/image.jpg",
        "title": "Account Screenshot",
        "filename": "screenshot.jpg"
      }
    ]
  },
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "context": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "language": "en"
  },
  "timestamp": 1678901234
}

Server responses

On success: the server will not respond to the connection that sent the event. It will respond to other open connections for this session with: Type message:send:sync and payload the same as the one received in the message:send event.
On failure message:send:error

Event `message:read`

Mark a message as read. This event indicates that a message has been viewed by the user.

Field	Type	Description
session_id	string	Required session identifier
timestamp	integer	Required timestamp of read

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1678901234
}

Server responses

On success: no response.
On failure message:read:error

Event `message:delivered`

Confirm message delivery. This event acknowledges that a message has been received by the client.

Field	Type	Description
session_id	string	Required session identifier
timestamp	integer	Required timestamp of delivery

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1678901234
}

Server responses

On success: no response.
On failure message:delivered:error

Event `message:compose`

Indicate whether the user is typing. This event shows typing indicators to other participants.

Field	Type	Description
session_id	string	Required session identifier
action	string	Required: "start" or "stop"
timestamp	integer	Required timestamp of the typing event

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "action": "start",
  "timestamp": 1678901234
}

Server responses

On success: no response.
On failure message:compose:error

Event `message:rating`

Rate a specific AI message. This event allows users to provide feedback on individual AI responses.

Field	Type	Description
session_id	string	Required session identifier
timestamp	integer	Required timestamp of the rating
request_id	string	Required ID of the rated message
value	integer	Required rating value (-1, 0, or 1)

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1678901234,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "value": 1
}

Server responses

On success message:rated
On failure message:rating:error

Event `file:upload_url:create`

Request a signed upload URL for a file. This event initiates the file upload process.

Field	Type	Description
session_id	string	Required session identifier
file_type	string	Required type of file
file_id	string	Required unique file identifier
original_name	string	Required original filename

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "file_type": "image",
  "file_id": "550e8400-e29b-41d4-a716-446655440000",
  "original_name": "example.jpg"
}

Server responses

On success file:upload_url:created
On failure file:upload_url:create:error

Event `file:download_url:create`

Request a signed download URL for a file. This event initiates the file download process.

Field	Type	Description
session_id	string	Required session identifier
file_id	string	Required unique file identifier
file_name	string	Required name of the file
original_name	string	Required original filename

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "file_id": "550e8400-e29b-41d4-a716-446655440000",
  "file_name": "example.jpg",
  "original_name": "example.jpg"
}

Server responses

On success file:download_url:created
On failure file:download_url:create:error

Event session:create​

Server responses​

Event session:context:update​

Server responses​

Event session:reconnect​

Server responses​

Event session:overview​

Server responses​

Event session:close​

Server responses​

Event session:rating​

Server responses​

Event session:activity​

Server responses​

Event session:history:sync​

Server responses​

Event conversation:reopen​

Server responses​

Event message:send​

Server responses​

Event message:read​

Server responses​

Event message:delivered​

Server responses​

Event message:compose​

Server responses​

Event message:rating​

Server responses​

Event file:upload_url:create​

Server responses​

Event file:download_url:create​

Server responses​

Event `session:create`

Server responses

Event `session:context:update`

Server responses

Event `session:reconnect`

Server responses

Event `session:overview`

Server responses

Event `session:close`

Server responses

Event `session:rating`

Server responses

Event `session:activity`

Server responses

Event `session:history:sync`

Server responses

Event `conversation:reopen`

Server responses

Event `message:send`

Server responses

Event `message:read`

Server responses

Event `message:delivered`

Server responses

Event `message:compose`

Server responses

Event `message:rating`

Server responses

Event `file:upload_url:create`

Server responses

Event `file:download_url:create`

Server responses