Reconnect to session

Event session:reconnect

The session:reconnect event allows you to re-establish a connection to an existing session

, because the client was disconnected, or because you want to share the same session across multiple clients. This is particularly useful for maintaining conversation continuity when network issues occur or when the client needs to reconnect after a temporary disconnection.

Use cases

• Recovering from network interruptions
• Re-establishing connection after client-side issues
• Maintaining session state across page refreshes
• Handling temporary disconnections gracefully
• Preserving conversation history and context
• Sharing the same session across multiple clients

Payload example

{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "timestamp": 1635789600000
}

Payload fields

Field	Type	Required	Description
session_id	String	Yes	The unique identifier of the session to reconnect to. This ID is obtained from the initial session:created event.
timestamp	Integer	Yes	Unix timestamp in milliseconds representing when the reconnection was initiated.

Server responses

Success: session:reconnected

On successful reconnection, the server responds with a session:reconnected event. This event includes the same payload structure as the session:created event, containing all session details:

{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "inactivity_timeout_seconds": 600,
  "is_service_desk": false,
  "is_conversation": true,
  "is_handover": false,
  "assignee_agent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "assignee_brain_id": "550e8400-e29b-41d4-a716-446655440000",
  "keep_alive": 120,
  "status": "active",
  "assignee_collection_id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  "source": {
    "integration_id": "d9e7c112-8f11-4c80-9318-b3f98b9728d6",
    "channel": "web",
    "opt_out": false,
    "is_test": false,
    "account_id": "6fa459ea-ee8a-3ca4-894e-db77e160355e",
    "brain_id": "550e8400-e29b-41d4-a716-446655440000",
    "brain_parent_id": "329a91d4-dbfd-4dfc-8c76-ccd5d30e476b",
    "brain_version": 3,
    "desk_id": "1b1cb6bb-9c1e-4afe-b139-ca06fa2fff4f",
    "session_timeout": 3600,
    "account_slug": "acme-corp",
    "department_id": "5f8cc8eb-6ef4-4a77-b8a0-51eb3f11e1b4"
  },
  "context": {
    "user": {
      "display_name": "John Doe",
      "phone": "***",
      "email": "john.doe@example.com"
    }
  }
}

note

For a detailed explanation of all fields in the response, see the session:created documentation.

Error: session:reconnect:error

If the reconnection fails, the server responds with an error event:

{
  "error_code": "invalid_session",
  "description": "The provided session ID is invalid or the session has expired"
}

Retrieve chat history

Once a client has reconnected to a session, it can retrieve the chat history by calling the session:history:sync event. This event will request the chat history from the server and return a session:history:synced event containing the chat history.

session:history:sync payload

{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "timestamp": 1635789600000
}

session:history:synced payload

[
  [
    "message:send", // First element in the array is the event type
    {
      "session_id": "123e4567-e89b-12d3-a456-426614174000",
      "input": {
        "text": "Hello from Client A"
      },
      "timestamp": 1635789600000
    } // Second element in the array is the payload
  ]
]

important

Not all the events are included in the chat history. Only the events that are relevant to the conversation content are included, such as message:send, message:received, message:brain_received, conversation:member_joing, conversation:member_left, etc.

Session expiration and reconnection

note

For detailed information about session states, transitions, timeout mechanisms, and expiration behavior, see the Session lifecycle

documentation.

When attempting to reconnect to a session, it's important to understand the following:

1. Session Timeout: Sessions have a configurable timeout period. If the session has expired, reconnection will fail.
2. Keep Alive: Closed sessions remain accessible for a configurable period before final expiration.
3. Session State: The session must be in a valid state (active or closed but not expired) for reconnection to succeed.

Multi-client session handling

The session:reconnect event can be used to handle a single session from multiple clients simultaneously. This is useful for scenarios where you want to maintain the same conversation across different devices or browser tabs.

When multiple clients are connected to the same session:

1. Each client must use the same session_id to reconnect
2. All clients will receive the same session context and state
3. When any client sends a message using message:send, the server will:
   • Process the message normally
   • Send a message:send:sync event to all other connected clients
   • The original sender will not receive the sync event

This behavior ensures that all clients stay in sync with the conversation state.

Example: Multi-client message exchange

// Client A implementation
const socketA = io(URL, socketOptions);

// Reconnect to existing session
socketA.emit("session:reconnect", {
  session_id: "123e4567-e89b-12d3-a456-426614174000",
  timestamp: Date.now(),
});

// Send a message
socketA.emit("message:send", {
  input: { text: "Hello from Client A" },
  session_id: "123e4567-e89b-12d3-a456-426614174000",
  timestamp: Date.now(),
});

// Client B implementation
const socketB = io(URL, socketOptions);

// Reconnect to the same session
socketB.emit("session:reconnect", {
  session_id: "123e4567-e89b-12d3-a456-426614174000",
  timestamp: Date.now(),
});

// Listen for sync events from other clients
socketB.on("message:send:sync", (data) => {
  console.log("Received sync from other client:", data);
});

Sync event payload structure

The message:send:sync event payload follows the same structure as either message:received (for human agent responses) or message:brain_received (for AI Agent responses):

// For AI responses (message:brain_received)
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "output": {
    "responses": [
      {
        "type": "text",
        "text": "Response from AI"
      }
    ]
  },
  "timestamp": 1635789600000,
  "brain_language": "en",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

// For human agent responses (message:received)
{
  "session_id": "123e4567-e89b-12d3-a456-426614174000",
  "from": {
    "agent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "agent_name": "John Doe",
    "team_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "to": {
    "user_id": "user123"
  },
  "body": {
    "text": "Response from agent"
  },
  "timestamp": 1635789600000
}

note

The message:send:sync event is only sent to other clients connected to the same session. The client that sent the original message will not receive this sync event.

note

For detailed payload structures and field descriptions, see the Message Exchange

documentation.

tip

When implementing multi-client support, consider:

• Handling message synchronization across all connected clients
• Managing UI state to reflect the current active client
• Implementing proper cleanup when clients disconnect

Example usage

// Initialize socket connection
const socket = io(URL, socketOptions);

// Reconnect payload
const reconnectPayload = {
  session_id: "123e4567-e89b-12d3-a456-426614174000",
  timestamp: Date.now(),
};

// Send reconnect event
socket.emit("session:reconnect", reconnectPayload);

// Handle success response
socket.on("session:reconnected", (data) => {
  console.log("Successfully reconnected to session:", data.session_id);
  // Session is now active and ready for message exchange
});

// Handle error response
socket.on("session:reconnect:error", (error) => {
  console.error("Error reconnecting to session:", error.description);
  // Handle the error appropriately (e.g., create a new session)
});

// After successful reconnection, you may want to sync the message history
socket.emit("session:history:sync", {
  session_id: "123e4567-e89b-12d3-a456-426614174000",
  timestamp: Date.now(),
});

Best practices

1. Error Handling

   • Implement proper error handling for reconnection failures
   • Consider creating a new session if reconnection fails
   • Log reconnection attempts and failures for debugging

2. Session Management

   • Store session IDs securely for future reconnection attempts
   • Implement session validation before attempting reconnection
   • Handle session expiration gracefully

3. Message Synchronization

   • After successful reconnection, sync message history
   • Ensure message continuity across reconnections
   • Handle any missed messages appropriately

4. Network Considerations

   • Implement exponential backoff for reconnection attempts
   • Handle network interruptions gracefully
   • Consider implementing offline message queuing

tip

To maintain session continuity, consider implementing automatic reconnection logic in your WebSocket client implementation. This can help handle temporary network issues without user intervention.