Connect to an Agent

Send your first message to an AlonChat agent from your server

Connect to an Agent#

Use the Chat API to put an AlonChat agent inside your app, website backend, internal tool, or automation. Your integration sends a customer message and receives the same agent's reply.

What You Need#

An AlonChat agent that has been trained and tested.
The Agent ID from the agent's Deploy → API page.
A project API key with the chat permission from Project Settings → API Keys.

API, MCP, and CLI access are available on every paid plan. Active trials may access gated features during the trial, subject to trial limits.

API keys are server-side credentials. Never put one in browser code, a mobile app bundle, or a public repository.

Send Your First Message#

bash

curl -X POST https://alonchat.com/api/v1/chat/YOUR_AGENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-message-001" \
  -d '{
    "message": "What time do you close?"
  }'

The response contains the agent's reply and a conversation ID:

json

{
  "response": "We are open until 6 PM today.",
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "credits_used": 5,
  "credits_remaining": 995
}

Continue the Conversation#

Send the returned conversation_id with the next customer message:

bash

curl -X POST https://alonchat.com/api/v1/chat/YOUR_AGENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: second-message-001" \
  -d '{
    "message": "Are you open on Sundays?",
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

A billable chat request must include an idempotency key, either in the JSON body as idempotency_key or in the Idempotency-Key header. The key is 1–255 characters. Omitting it returns 400 with IDEMPOTENCY_KEY_REQUIRED.

Use a new key for each new message. Reuse the same key only when retrying that exact request. An identical completed request is replayed, including its original reply, and is not run again. Using the same key for a different message returns 409.

Choose an Integration#

Integration	Best for
REST Chat API	Any server language or platform
TypeScript SDK	Node.js and TypeScript applications
AlonChat CLI	Testing, scripts, and terminal automation
MCP	Connecting Codex and other MCP-compatible AI clients
Agent workbench	Evidence-backed agent improvement with owner review

Customer chat uses one hosted runtime. SDK, CLI, and MCP calls other than chat use the same project operation catalog as the API and dashboard. They are connectors, not a second agent or a separate business API. Training, tools, procedures, permissions, credits, and conversation behavior stay owned by the agent in AlonChat.

The Chat API can also return Workflow buttons and media in presentation. Render only what the response includes. Custom widget layouts are not reproduced on this API; test those in the embedded web widget. See the Chat API.

Production Checklist#

Store the API key in your hosting provider's secret store.
Keep the Agent ID in configuration rather than hard-coding it across the app.
Save conversation_id with the customer's session when you need multi-turn context.
Send an idempotency key for safe retries.
Handle 401, 402, 403, 409, and 429 responses explicitly.
Monitor credit usage and rotate a key immediately if it may have leaked.