Send a message

POST /api/developer/chat/messages

Sends one message into an existing session and returns the agent's reply. Create the session first with Create a chat session.

Request

Field	Type	Required	Description
agentId	string	Yes	The agent to talk to.
sessionId	string	Yes	The session returned when you created the conversation.
message	string	Yes	What the user said.
variableValues	object	No	Values for the agent's variables. See below.

curl --request POST "https://api.chatley.ai/api/developer/chat/messages" \
  --header "Authorization: Bearer $CHATLEY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agentId": "YOUR_AGENT_ID",
    "sessionId": "YOUR_SESSION_ID",
    "message": "What appointment times are available?"
  }'

Agent variables

If your agent's instructions reference variables, pass their values with the message:

{
  "agentId": "YOUR_AGENT_ID",
  "sessionId": "YOUR_SESSION_ID",
  "message": "Hello",
  "variableValues": {
    "customerName": "Jane Doe",
    "planTier": "Pro"
  }
}

This is how you hand the agent what your application already knows — the signed-in customer's name, their plan, an order number — so it does not have to ask.

Response

200 OK

{
  "success": true,
  "data": {
    "chatId": "chat-id",
    "sessionId": "YOUR_SESSION_ID",
    "response": "We have Tuesday at 10am or Thursday at 2pm. Which suits you?",
    "isSession": true,
    "createdAt": "2026-07-03T12:34:56.000Z",
    "updatedAt": "2026-07-03T12:34:57.000Z"
  }
}

Field	Type	Description
response	string	The agent's reply. This is the field to show your user.
chatId	string	Identifies this single exchange.
sessionId	string	The session the message belongs to, echoed back.
isSession	boolean	Always true for this endpoint.
createdAt / updatedAt	string	ISO 8601 timestamps for the exchange.

The response also carries the conversation so far and the cost of the exchange, which is useful if you want to render the full transcript rather than track it yourself. Read response for the reply and treat the rest as additive — build against the fields documented above.

Errors

Status	error	What to do
400	Agent ID, message, and session ID are required	All three fields must be present and non-empty.
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.
401 / 403	see Authentication	Fix the API key or its type.
500	Internal server error	Retry. If it persists, contact support.

As with sessions, a failure from the underlying chat service comes back as Chat provider error carrying that service's status code — retry 429 and 5xx with backoff.

Holding a conversation

POST /chat/sessions   → sessionId
POST /chat/messages   → reply    (same sessionId)
POST /chat/messages   → reply    (same sessionId)

Send each user turn as its own request with the same sessionId. The agent already has the earlier turns — do not replay the transcript in message.