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

# Create a new session

`POST /api/messaging/sessions`

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.net/elizaos/apis/eliza-os-api.md) · [All operations](https://skmtc.net/elizaos/apis/eliza-os-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elizaos/eliza-os-api/versions/f43280bfdb0c/schema)