Developer API

The Chatley Developer API lets your own application hold a conversation with one of your agents. You create a session, send messages to it, and read the agent's replies back as JSON.

It is the inbound half of Chatley's integration surface: your application calls Chatley. For the outbound half — Chatley calling you when a lead arrives — see Webhooks.

Base URL

https://api.chatley.ai

Every request and response body is JSON.

What you can do today

Endpoint	Purpose
POST /api/developer/chat/sessions	Start a conversation with an agent
POST /api/developer/chat/messages	Send a message and get the agent's reply

A session holds the conversation context. Create one, keep its sessionId, and send every message in that conversation with the same ID so the agent remembers what was said earlier.

Before you start

You need two things:

1. An API key. Create one in Integrations & API Keys → API Keys. See Authentication.
2. An agent ID. Open the agent in Chatley and copy the ID from the agent page URL.

A complete example

Create a session:

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"}'

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

Then send a message into it:

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?"
  }'

{
  "success": true,
  "data": {
    "chatId": "chat-id",
    "sessionId": "YOUR_SESSION_ID",
    "response": "We have Tuesday at 10am or Thursday at 2pm. Which suits you?"
  }
}

Response shape

Every endpoint answers with the same envelope, so you can branch on one field:

{ "success": true, "data": { } }

{ "success": false, "error": "Agent not found" }

A failed request always carries a non-2xx status code as well as "success": false. Authentication failures add a machine-readable code — see Authentication.

note

The agent must have chat enabled. If it does not, requests come back with 400 — Agent does not have chat enabled; open the agent in Chatley and turn chat on before calling the API.