Create session

Event session:create

The session:create event is used to initialize a new conversation session after establishing a WebSocket connection. This event registers a new conversation context and prepares the system to receive and process messages.

{
  "context": {
    "user": {
      "display_name": "John Doe",
      "phone": "+1234567890"
    }
  },
  "identity_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "timestamp": 1635789600000,
  "is_test": false,
  "opt_out": false
}

Payload fields

Field	Type	Required	Description
context	Object	No	A context object containing information about the user and conversation environment. This context will be available throughout the session's lifecycle.
identity_token	String	No	JWT token for identity verification. Used for secure authentication when required by the integration.
timestamp	Integer	Yes	Unix timestamp in milliseconds representing when the session creation was initiated.
is_test	Boolean	No	Flag indicating if this is a test session. Defaults to false if not provided.
opt_out	Boolean	No	Flag indicating if the user has opted out of data collection. Defaults to false if not provided.

Server responses

Success: session:created

On successful session creation, the server responds with a session:created event containing the created 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": "+1234567890"
    }
  }
}

Response fields

Field	Description
session_id	Unique identifier for the created session, used in all subsequent interactions.
inactivity_timeout_seconds	Time in seconds before the session expires due to inactivity.
is_service_desk	Indicates if this session is connected to a service desk.
is_conversation	Indicates if this session is a conversation type.
is_handover	Indicates if this session is configured for human handover.
assignee_agent_id	ID of the human agent assigned to this session (if any).
assignee_brain_id	ID of the AI Agent assigned to this session.
keep_alive	Interval in seconds for keep-alive messages.
status	Current status of the session (e.g., "active").
assignee_collection_id	ID of the collection assigned to this session.
source	Object containing metadata about the integration and account.
context	Copy of the initial context provided.

warning

Moveo controls certain fields in the context object. As these are likely to be sensitive, the server will obfuscate these fields in the response showing them as ***.

Error responses

If session creation fails, the server responds with one of the following error events:

Error event	Description
session:create:error	General error during session creation.
session:create:error:invalid_identity_token	The provided identity token is invalid or expired.
session:create:error:invalid_private_key	The private key used for verification is invalid.
session:create:error:invalid_aes_claims	The AES claims in the token are invalid.
session:create:error:failed_aes_descryption	AES decryption of the token failed.

Error responses include the following payload:

{
  "error_code": "invalid_token",
  "description": "The provided identity token is invalid or has expired"
}

Session lifecycle

After successful creation, the session enters the active state and remains available until explicitly closed or until it expires. The session:created response contains important timeout values (inactivity_timeout_seconds, keep_alive, and source.session_timeout in the payload object) that govern the session's lifespan.

note

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

documentation.

Example usage

The following example demonstrates how to create a session using the WebSocket API:

// Initialize socket connection (see connection.md for details)
const socket = io(URL, socketOptions);

// Connection event handling
socket.on("connect", () => {
  console.log("Connected to WebSocket API");

  // Create session payload
  const sessionCreatePayload = {
    context: {
      user: {
        display_name: "Jane Smith",
        email: "jane.smith@example.com",
      },
    },
    timestamp: Date.now(),
    is_test: false,
    opt_out: false,
  };

  // Send session:create event
  socket.emit("session:create", sessionCreatePayload);
});

// Handle success response
socket.on("session:created", (data) => {
  console.log("Session created:", data.session_id);
  // Store session_id for future interactions
  const sessionId = data.session_id;

  // Now you can start sending messages with this session_id
});

// Handle specific error responses
socket.on("session:create:error", (error) => {
  console.error("General error creating session:", error.description);
});

socket.on("session:create:error:invalid_identity_token", (error) => {
  console.error("Invalid identity token:", error.description);
});

// Handle other potential errors
socket.on("session:create:error:invalid_private_key", handleAuthError);
socket.on("session:create:error:invalid_aes_claims", handleAuthError);
socket.on("session:create:error:failed_aes_descryption", handleAuthError);

function handleAuthError(error) {
  console.error("Authentication error:", error.description);
  // Implement retry logic or user notification
}

tip

To prevent premature session expiration, send regular session:activity events during periods of user inactivity. See Client events for implementation details.