---
title: Create a chat session
description: POST /api/developer/chat/sessions — start a conversation with one of your agents.
---

```text
POST /api/developer/chat/sessions
```

A session is the conversation. Create one before sending any message, then reuse
its `sessionId` for every message in that conversation so the agent keeps the
earlier turns in context.

## Request

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agentId` | string | Yes | The agent to talk to. Copy it from the agent page URL in Chatley. |

```bash
curl --request POST "https://api.chatley.ai/api/developer/chat/sessions" \
  --header "Authorization: Bearer $CHATLEY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"agentId":"YOUR_AGENT_ID"}'
```

## Response

`200 OK`

```json
{
  "success": true,
  "data": {
    "sessionId": "session-id",
    "agentId": "YOUR_AGENT_ID"
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `sessionId` | string | Pass this to [Send a message](./chat-messages.md) for every turn of the conversation. |
| `agentId` | string | The agent the session belongs to, echoed back. |

## Errors

| Status | `error` | What to do |
| --- | --- | --- |
| 400 | `Agent ID is required` | Include `agentId` in the JSON body. |
| 400 | `Agent does not have chat enabled` | Open the agent in Chatley and turn chat on. |
| 404 | `Agent not found` | The ID does not match an agent on your account. Check you copied the whole ID. |
| 401 / 403 | see [Authentication](./authentication.md#error-responses) | Fix the API key or its type. |
| 500 | `Internal server error` | Retry. If it persists, contact support. |

A failure from the underlying chat service is returned as
`Chat provider error` with that service's status code, so a `429` or `503` you
receive should be retried with backoff rather than treated as a bad request.

## One session per conversation

Treat a `sessionId` as belonging to a single conversation. Start a new session
when a new visitor arrives, or when a conversation has clearly ended — reusing
one across unrelated conversations means the agent answers with the earlier
context still in mind.

If a session stops accepting messages, create a new one and carry over whatever
context matters through [variables](./chat-messages.md#agent-variables).