WebSocket server events

This page lists every WebSocket event that the server emits, with its payload structure.

Event `session:created`

Response to a successful session creation. The server sends this event when it establishes a new session with the client. The event contains the configuration and the context information of the session.

Field	Type	Description
`session_id`	string	Unique identifier for the session
`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 AI agent
`assignee_collection_id`	string	ID of the assigned knowledge base
`source`	object	Source information object. It includes `keep_alive` and `brain_inactivity_timeout` in seconds.
`context`	ContextObject	Session context information

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "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",
  "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,
    "brain_inactivity_timeout": 300,
    "keep_alive": 30,
    "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 (for sticky sessions). Load-balanced environments use this event to designate the connection that maintains 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`

The server emits this event when a session closes successfully. The event confirms that the server ended the session and cleaned up its state.

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 expired and that the client cannot reconnect to it. The server sends this event when it ends a session that stayed inactive for too long.

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 `conversation:member_join`

The server emits this event when an AI agent or a human agent joins the conversation. The event notifies all participants that a new member 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`

The server emits this event when an AI agent or a human agent leaves the conversation. The event notifies all participants that a member left 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`

The server emits this event when a conversation is resolved. The event indicates that the conversation is complete. Do not expect more 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 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`

The server emits this event when the user reopens a closed conversation. The event indicates that the resolved conversation is active again 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 `open`

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": "open"
}

Event `message:brain_received`

A response from the AI agent. This event contains the AI agent's response to a user message, with any structured data or media to display 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 AI agent 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 from a human agent. This event contains the message, with any attachments or media to display 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 a human agent. Use this event to show a typing indicator in the UI while the author composes a message.

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 reached the server. This event confirms that the server received the message and processes it.

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 is marked as read. This event indicates that the recipient viewed the message.

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
}

Event session:created​

Event session:leader​

Event session:closed​

Event session:expired​

Event conversation:member_join​

Event conversation:member_leave​

Event conversation:closed​

Event conversation:reopened​

Event message:brain_received​

OutputObject structure​

Event message:received​

Event message:compose​

Event message:delivered​

Event message:read​

Event `session:created`

Event `session:leader`

Event `session:closed`

Event `session:expired`

Event `conversation:member_join`

Event `conversation:member_leave`

Event `conversation:closed`

Event `conversation:reopened`

Event `message:brain_received`

`OutputObject` structure

Event `message:received`

Event `message:compose`

Event `message:delivered`

Event `message:read`