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 the knowledge sources used in responses

API access is available on Business and Enterprise plans. Active trials may access gated features during the trial, subject to trial limits.

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 managed in Project Settings > API Keys. You can optionally restrict a key to one agent. 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 - Knowledge 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