Chat API

Integrate AlonChat conversations into your applications via the REST API

Chat API#

Send messages and receive AI responses programmatically through the AlonChat Chat API.

Overview#

The Chat API allows you to:

• Send messages to your AI agent
• Receive streaming or complete responses
• Maintain conversation context
• Access RAG sources used in responses

Quick Start#

1. Get Your API Key#

1. Go to Project Settings → API Keys and create a key (optionally restrict it to one agent).
2. Open your agent's Deploy → API page for its endpoint and Agent ID.
3. Send the key as a Bearer token from your server.

2. Make Your First Request#

curl -X POST https://alonchat.com/api/v1/chat/{agentId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, what are your business hours?"
  }'

3. Handle the Response#

{
  "response": "We're open Monday-Saturday, 9AM to 6PM. Closed on Sundays and holidays!",
  "conversation_id": "conv_abc123",
  "confidence": 0.95,
  "sources": [
    {
      "type": "qa",
      "title": "Business Hours",
      "relevance": 0.98
    }
  ]
}

Authentication#

All requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are created per agent from the Deploy > API section of your dashboard. Keys use the ak_ prefix. See the Authentication guide for details on creating and managing keys.

Security: API keys should only be used server-side. Never expose them in frontend code or mobile apps.

Endpoints#

Send Message#

POST /api/v1/chat/{agentId}

Send a message and receive an AI response.

Request Body#

Example Request#

const response = await fetch(
  `https://alonchat.com/api/v1/chat/${agentId}`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: "What products do you offer?",
      conversation_id: "conv_abc123"
    })
  }
);

const data = await response.json();
console.log(data.response);

Response#

{
  "response": "We offer three main products...",
  "conversation_id": "conv_abc123",
  "message_id": "msg_xyz789",
  "confidence": 0.87,
  "sources": [
    {
      "type": "docs",
      "title": "Product Catalog",
      "relevance": 0.92
    }
  ],
  "credits_used": 5
}

Streaming Responses#

For real-time responses, enable streaming:

const response = await fetch(
  `https://alonchat.com/api/v1/chat/${agentId}`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: "Tell me about your services",
      stream: true
    })
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  process.stdout.write(chunk);
}

Streaming events:

• text - Response text chunks
• sources - RAG sources used
• done - Stream complete

Rate Limits#

Rate limits vary by plan. The API includes rate limit headers in every response so you can track your usage:

• X-RateLimit-Limit — Maximum requests per window
• X-RateLimit-Remaining — Requests remaining in the current window
• X-RateLimit-Reset — When the current window resets (Unix timestamp)

When you exceed the limit, the API returns 429 Too Many Requests. Use exponential backoff when retrying.

Error Handling#

HTTP Status Codes#

Error Response Format#

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 60 seconds.",
    "retry_after": 60
  }
}

SDKs#

Official SDKs coming soon:

• JavaScript/TypeScript
• Python
• PHP

For now, use standard HTTP libraries.

Webhooks#

Receive real-time notifications for events:

{
  "event": "message.sent",
  "data": {
    "conversation_id": "conv_abc123",
    "message": "..."
  }
}

See Webhooks Documentation for details.

Best Practices#

1. Store conversation_id - Maintain context across messages
2. Handle errors gracefully - Retry with exponential backoff
3. Use streaming for UX - Better perceived performance
4. Cache when appropriate - Reduce redundant API calls
5. Monitor usage - Track credits consumed

Related Pages#

• Authentication
• Webhooks
• Web Widget