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#

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

API access is available on Business and Enterprise plans. 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"
  }'

Use a new idempotency key for each new message. Reuse the same key only when retrying that exact request.

Choose an Integration#

IntegrationBest for
REST Chat APIAny server language or platform
TypeScript SDKNode.js and TypeScript applications
AlonChat CLITesting, scripts, and terminal automation
MCPConnecting Codex and other MCP-compatible AI clients
Agent workbenchEvidence-backed agent improvement with owner review

All four use the same AlonChat Chat API runtime. Training, tools, procedures, permissions, credits, and conversation behavior stay owned by the agent in AlonChat.

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.

Next Steps#