Create a chat session

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.

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

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

Field	Type	Description
sessionId	string	Pass this to Send a message 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	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.