Send a message to the agent and wait for the reply

curl --request POST \
  --url https://api.chattler.ai/v1/agents/{agent_id}/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "external_user_id": "<string>",
  "message": "<string>"
}
'

import requests

url = "https://api.chattler.ai/v1/agents/{agent_id}/chat"

payload = {
    "external_user_id": "<string>",
    "message": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({external_user_id: '<string>', message: '<string>'})
};

fetch('https://api.chattler.ai/v1/agents/{agent_id}/chat', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "request_id": "<string>",
  "conversation_id": "<string>",
  "message": {
    "id": "<string>",
    "content": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "role": "assistant"
  },
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123,
    "charged_usd": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

Chat

Send a message to the agent and wait for the reply

Run one turn of conversation on the agent through the ordinary Chattler runtime: the agent’s system prompt, knowledge base, tools, and dialog history all apply, and the reply is paid for from the owner’s balance exactly like any other channel. The conversation is identified by the API key and external_user_id: every message from the same external user through the same key lands in the same conversation, and another key never sees it.

Authentication

Authorization: Bearer cht_live_<key_id>.<secret>; the key must have the full permission.

Headers

Idempotency-Key (required): any client-chosen value of 1-255 characters, unique per logical request. Retrying with the same value and the same body returns the original result without a second reply or charge.

Path Parameters

agent_id: The agent the key is bound to

Request Body

external_user_id: stable id of the end user on your side, 1-255 characters
message: the user’s text; must not be empty. Attachments are not accepted in this release, and unknown fields are rejected.

Example Request

curl -X POST "/v1/agents/{agent_id}/chat" \
  -H "Authorization: Bearer cht_live_{key_id}.{secret}" \
  -H "Idempotency-Key: 7f20a5f0-5dde-48cf-94aa-38acbbd218e0" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id": "customer-123", "message": "I want to know the price"}'

Response

request_id: UUID of this request; also returned as X-Request-ID
conversation_id: the conversation the exchange was stored in
message: the persisted assistant reply: id, role (assistant), content, created_at
usage: prompt_tokens, completion_tokens, total_tokens, and charged_usd (decimal string) as metered and charged for this request

A replayed request returns the original request_id, message, and usage.

Errors

Envelope: {"error": {"code": "...", "message": "...", "request_id": "..."}}.

invalid_api_key (401), agent_mismatch (403)
permission_denied (403): the key is read-only
agent_not_found (404) / agent_disabled (403): the agent no longer exists or is switched off
validation_error (422): missing Idempotency-Key, empty message, or unknown body fields
idempotency_conflict (409): the same Idempotency-Key was used with a different body
idempotency_in_progress (409, Retry-After): the original request is still running
conversation_busy (409, Retry-After): another message for this external user is being answered
insufficient_balance (402): the owner’s balance cannot cover the reply; nothing was charged
rate_limit_exceeded (429), api_rate_limit_unavailable (503), service_unavailable (503), internal_error (500)

POST

agents

{agent_id}

chat

Send a message to the agent and wait for the reply

curl --request POST \
  --url https://api.chattler.ai/v1/agents/{agent_id}/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "external_user_id": "<string>",
  "message": "<string>"
}
'

import requests

url = "https://api.chattler.ai/v1/agents/{agent_id}/chat"

payload = {
    "external_user_id": "<string>",
    "message": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({external_user_id: '<string>', message: '<string>'})
};

fetch('https://api.chattler.ai/v1/agents/{agent_id}/chat', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "request_id": "<string>",
  "conversation_id": "<string>",
  "message": {
    "id": "<string>",
    "content": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "role": "assistant"
  },
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123,
    "charged_usd": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Agent API key: Authorization: Bearer cht_live_<key_id>.

Headers

Idempotency-Key

string

required

Client-chosen value, 1-255 characters, unique per logical request; a retry with the same value and body returns the stored result

Required string length: 1 - 255

Path Parameters

agent_id

string

required

Body

application/json

Text-only chat input; attachments are outside this release, so any extra field is a validation error rather than silently ignored.

external_user_id

string

required

Stable id of the end user on the caller's side

Required string length: 1 - 255

message

string

required

Minimum string length: 1

Response

The persisted assistant reply with its usage

request_id

string

required

conversation_id

string

required

message

ApiChatMessage · object

required

Show child attributes

usage

ApiChatUsage · object

required

Show child attributes

API Reference

Chat

Conversations

Send a message to the agent and wait for the reply

Authentication

Headers

Path Parameters

Request Body

Example Request

Response

Errors

Authorizations

Headers

Path Parameters

Body

Response