Websocket server events
This page lists all WebSocket events emitted by the server and their payload structures.
Event session:created
Response to a successful session creation. This event is sent when a new session is established between the client and server, containing all the necessary configuration and context information for the session.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| inactivity_timeout_seconds | integer | Time in seconds before session expires due to inactivity |
| is_service_desk | boolean | Whether this is a service desk session |
| is_conversation | boolean | Whether this is a conversation session |
| is_handover | boolean | Whether this is a handover session |
| assignee_agent_id | string | ID of the assigned agent |
| assignee_brain_id | string | ID of the assigned brain |
| keep_alive | integer | Keep-alive interval in seconds |
| status | string | Current status of the session |
| assignee_collection_id | string | ID of the assigned collection |
| source | object | Source information object |
| context | ContextObject | Session context information |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"inactivity_timeout_seconds": 300,
"is_service_desk": true,
"is_conversation": true,
"is_handover": false,
"assignee_agent_id": "550e8400-e29b-41d4-a716-446655440000",
"assignee_brain_id": "550e8400-e29b-41d4-a716-446655440000",
"keep_alive": 30,
"status": "active",
"assignee_collection_id": "550e8400-e29b-41d4-a716-446655440000",
"source": {
"integration_id": "550e8400-e29b-41d4-a716-446655440000",
"channel": "web",
"opt_out": false,
"is_test": false,
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"brain_id": "550e8400-e29b-41d4-a716-446655440000",
"brain_parent_id": "550e8400-e29b-41d4-a716-446655440000",
"brain_version": 1,
"desk_id": "550e8400-e29b-41d4-a716-446655440000",
"session_timeout": 3600,
"account_slug": "example-account",
"department_id": "550e8400-e29b-41d4-a716-446655440000"
},
"context": {
"user_id": "550e8400-e29b-41d4-a716-446655440000",
"language": "en"
}
}
Event session:leader
Identifies the leader connection for a session (used in sticky sessions). This event is used in load-balanced environments to designate which connection is responsible for maintaining the session state.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| leader_id | string | ID of the leader connection |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"leader_id": "550e8400-e29b-41d4-a716-446655440000"
}
Event session:closed
Emitted when a session has been closed successfully. This event confirms that the session has been properly terminated and cleaned up on the server side.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| timestamp | integer | Optional timestamp of when the session was closed |
| status | string | Always "closed" |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": 1678901234,
"status": "closed"
}
Event session:expired
Indicates that a session has expired and cannot be reconnected. This event is sent when a session has been inactive for too long and has been automatically terminated by the server.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| timestamp | integer | Optional timestamp of when the session expired |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": 1678901234
}
Event conversation:member_join
Emitted when an AI Agent or human agent joins the conversation. This event notifies all participants that a new member has entered the conversation.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| author_id | string | ID of the joining member |
| desk_id | string | ID of the desk |
| author_name | string | Name of the joining member |
| timestamp | integer | Optional timestamp of when the member joined |
| author_type | string | Either "brain" or "agent" |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"author_id": "550e8400-e29b-41d4-a716-446655440000",
"desk_id": "550e8400-e29b-41d4-a716-446655440000",
"author_name": "John Doe",
"timestamp": 1678901234,
"author_type": "agent"
}
Event conversation:member_leave
Emitted when an AI Agent or human agent leaves the conversation. This event notifies all participants that a member has exited the conversation.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| author_id | string | ID of the leaving member |
| desk_id | string | ID of the desk |
| author_name | string | Name of the leaving member |
| timestamp | integer | Optional timestamp of when the member left |
| author_type | string | Either "brain" or "agent" |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"author_id": "550e8400-e29b-41d4-a716-446655440000",
"desk_id": "550e8400-e29b-41d4-a716-446655440000",
"author_name": "John Doe",
"timestamp": 1678901234,
"author_type": "agent"
}
Event conversation:closed
Emitted when a conversation is resolved. This event indicates that the conversation has been marked as completed and no further messages should be expected.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| keep_alive | integer | Optional keep-alive interval in seconds |
| timestamp | integer | Optional timestamp of when the conversation was closed |
| agent_id | string | Optional ID of the agent who closed the conversation |
| agent_name | string | Optional name of the agent who closed the conversation |
| status | string | Always "closed" |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"keep_alive": 30,
"timestamp": 1678901234,
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "John Doe",
"status": "closed"
}
Event conversation:reopened
Emitted when a previously closed conversation is reopened by the user. This event indicates that a resolved conversation has been reactivated and can receive new messages.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| keep_alive | integer | Optional keep-alive interval in seconds |
| timestamp | integer | Optional timestamp of when the conversation was reopened |
| agent_id | string | Optional ID of the agent who reopened the conversation |
| agent_name | string | Optional name of the agent who reopened the conversation |
| status | string | Always "reopen" |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"keep_alive": 30,
"timestamp": 1678901234,
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "John Doe",
"status": "reopen"
}
Event message:brain_received
A response generated by the AI Agent. This event contains the AI's response to a user's message, including any structured data or media that should be displayed to the user.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| context | ContextObject | Optional context information |
| output | OutputObject | Response output object |
| timestamp | integer | Timestamp of when the message was received |
| brain_language | string | Language of the brain response |
| request_id | string | ID of the request that generated this response |
OutputObject structure
| Field | Type | Description |
|---|---|---|
| responses | array | Array of response objects |
| debug | object | Optional debug information |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"context": {
"user_id": "550e8400-e29b-41d4-a716-446655440000",
"language": "en"
},
"output": {
"responses": [
{
"type": "text",
"text": "Hello! How can I help you today?",
"show_typing": true,
"duration": 2000
}
],
"debug": {
"collection": {
"collection_id": "550e8400-e29b-41d4-a716-446655440000",
"request_code": 200,
"response_code": 200,
"external_urls": [
{
"external_url": "https://example.com",
"name": "Example Documentation",
"document_id": "550e8400-e29b-41d4-a716-446655440000",
"datasource_id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
}
},
"timestamp": 1678901234,
"brain_language": "en",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
Event message:received
A message sent by a human agent. This event contains a message from a human agent, including any attachments or media that should be displayed to the user.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| from | object | Information about the sender |
| to | object | Information about the recipient |
| body | object | Message content |
| timestamp | integer | Optional timestamp of when the message was received |
| context | ContextObject | Optional context information |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"from": {
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"team_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "John Doe",
"agent_avatar": "https://example.com/avatar.jpg"
},
"to": {
"user_id": "550e8400-e29b-41d4-a716-446655440000"
},
"body": {
"text": "Hello! How can I assist you today?",
"attachments": [
{
"type": "image",
"mime_type": "image/jpeg",
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/image.jpg",
"title": "Example Image",
"filename": "example.jpg"
}
]
},
"timestamp": 1678901234,
"context": {
"user_id": "550e8400-e29b-41d4-a716-446655440000",
"language": "en"
}
}
Event message:compose
Indicates a typing event from the AI Agent or human agent. This event is used to show typing indicators in the UI, indicating that a message is being composed.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| author_id | string | ID of the author |
| desk_id | string | Optional ID of the desk |
| author_name | string | Optional name of the author |
| timestamp | integer | Optional timestamp of the typing event |
| author_type | string | Either "brain", "agent", or "visitor" |
| action | string | Either "start" or "stop" |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"author_id": "550e8400-e29b-41d4-a716-446655440000",
"desk_id": "550e8400-e29b-41d4-a716-446655440000",
"author_name": "John Doe",
"timestamp": 1678901234,
"author_type": "agent",
"action": "start"
}
Event message:delivered
A message was successfully delivered. This event confirms that a message has been successfully received by the server and will be processed.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| author_type | string | Either "brain", "agent", or "visitor" |
| timestamp | integer | Timestamp of when the message was delivered |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"author_type": "agent",
"timestamp": 1678901234
}
Event message:read
A message was marked as read. This event indicates that a message has been viewed by the recipient.
| Field | Type | Description |
|---|---|---|
| session_id | string | Unique identifier for the session |
| author_type | string | Either "brain", "agent", or "visitor" |
| timestamp | integer | Timestamp of when the message was read |
Example payload:
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"author_type": "agent",
"timestamp": 1678901234
}