---
title: "Create a new session"
method: POST
path: "/api/messaging/sessions"
tags: ["messaging"]
---

# Create a new session

`POST /api/messaging/sessions`

## Request

- Base URL: `http://localhost:3000`
- URL: `http://localhost:3000/api/messaging/sessions`
- Auth: none declared

Creates a new chat session for a user with a specific agent. Sessions provide a simplified way to interact
with agents without the complexity of managing servers, channels, or participants.

**Key Benefits:**
- No channel management required - just provide agent and user IDs
- Automatic infrastructure handling - no need to create servers or channels
- Persistent conversation state maintained across messages
- Ideal for building chat interfaces, personal assistants, and direct user-to-agent interactions

Sessions maintain conversation state and context across multiple messages, providing a persistent chat experience
similar to modern AI assistants.

## Request body

- object
  - `agentId` string, uuid, required: ID of the agent to start a session with
  - `userId` string, uuid, required: ID of the user creating the session
  - `metadata` object: Additional metadata for the session
    - `platform` string: Platform the session is created from
    - `username` string: Username of the user
    - `discriminator` string: User discriminator (e.g., Discord discriminator)
    - `avatar` string: URL to user's avatar
  - `timeoutConfig` object: Optional timeout configuration for the session
    - `timeoutMinutes` integer: Inactivity timeout in minutes (5-1440). Default 30
    - `autoRenew` boolean: Whether to automatically renew on activity. Default true
    - `maxDurationMinutes` integer: Maximum total session duration in minutes. Default 720 (12 hours)
    - `warningThresholdMinutes` integer: Minutes before expiration to trigger warning. Default 5

## Response `201`

Session created successfully

- object
  - `sessionId` string: Unique identifier for the created session
  - `agentId` string, uuid
  - `userId` string, uuid
  - `createdAt` string, date-time
  - `metadata` object
  - `expiresAt` string, date-time: When the session will expire
  - `timeoutConfig` object: Active timeout configuration for the session
    - `timeoutMinutes` integer
    - `autoRenew` boolean
    - `maxDurationMinutes` integer
    - `warningThresholdMinutes` integer

## Other responses

- `400`: Invalid request parameters
- `404`: Agent not found
- `500`: Internal server error

---

[API](https://skmtc.dev/elizaos/apis/eliza-os-api.md) - [All operations](https://skmtc.dev/elizaos/apis/eliza-os-api/llms.txt) - [OpenAPI document](https://skmtc.dev/elizaos/apis/eliza-os-api/revisions/d606a12682bb?raw)