Integration Guide
Run support from your own product. Create a scoped key, call the REST API, and read or write conversations, live handoffs, tickets, knowledge, FAQs, analytics, widgets, settings, team and billing state.
https://api.chatonn.com/api/v1
X-API-Key: chatonn_...
{ success, statusCode, data }
How it works
A Platform API key is a server-to-server credential for exactly one tenant. Store it on your backend and you can drive ChatONN from your own product - conversations, live handoffs, tickets, knowledge, FAQs, analytics, widgets, bot settings, team and billing state - without opening the ChatONN dashboard.
Create one scoped key
Name the integration and tick only the resources it touches. The raw key is shown once and stored hashed.
Call the REST API
Send X-API-Key with every request. Tenant isolation and scope checks are enforced server-side.
Rotate and revoke
Keep one key per environment, watch last_used_at, and revoke anything no longer in service.
- Tenant isolation- a key only ever sees its own tenant's data. An id from another tenant returns 404, not 403.
- Scope checks - each endpoint declares the scope it needs. A valid key without that scope gets an explicit 403.
- Keys cannot manage keys - creating, listing and revoking keys always needs a user session, so a leaked key cannot escalate itself.
Create an API key
Generate keys from the dashboard with your user login. API Access is the only place a key is ever revealed.
- 1Open Dashboard → API Access and click Create API Key.
- 2Name it for the integration and environment, e.g. acme-prod-crm.
- 3Tick the read scopes you need first, then add write scopes only for features you really change.
- 4Copy the key from the dialog - it is shown once - and store it as CHATONN_API_KEY on your server.
- 5Send X-API-Key on every request, and revoke the key when the integration retires.
Tip
chat:read, chat:write, tickets:read, tickets:write. Add knowledge, FAQs, analytics and the rest by creating a new key with those scopes.Authenticate
One header, one base URL, one response envelope. A single small client covers the whole API.
Base URL
https://api.chatonn.com/api/v1
Auth header
X-API-Key: chatonn_...
export CHATONN_API="https://api.chatonn.com/api/v1"
export CHATONN_API_KEY="chatonn_xxx"
curl -s "$CHATONN_API/knowledge" \
-H "X-API-Key: $CHATONN_API_KEY"Success: { success: true, statusCode, data }
Errors: { detail } or { success: false, statusCode, message }
Conventions: most resources use integer ids (/faqs/12, /tickets/admin/12); tickets also expose a human reference in ticket_id. Conversations and live-chat sessions use UUID strings. All times are ISO-8601 UTC and filters are query parameters.
Official TypeScript SDK
@chatonn/sdk is a typed client for this API with no runtime dependencies. It unwraps the response envelope, retries transient failures with Retry-After, applies timeouts, and turns /chat/streaminto an async generator. Types are generated from this API's OpenAPI document, so the surface stays in sync.
client.chat
ask, stream, conversations, feedback
client.tickets
list, get, stats, reply, setStatus
client.knowledge
upload, importSitemap, waitForIndex
client.faqs
list, create, update, remove, categories
client.analytics
overview, funnel, visits, referrers…
client.widgets
configs, setDefault
client.settings
bot, ai, website, general
client.team
list, invite, update, roles
client.permissions
roles, matrix
client.billing
subscription, usage, limits
client.live
sessions, markRead, close, WebSocket
client.http
request, stream, buildUrl
Every failure throws one ChatonnError carrying status and the missing scope, so a 403 tells you exactly which scope to grant. Endpoints without a helper are still reachable through client.http.request().
Important
Pick your scopes
Start from the job you want your dashboard to do, then grant only those scopes. The write action always includes read for the same resource; resource:* grants both and * grants everything.
Which scopes do I need?
| I want to... | Scopes | Main endpoints |
|---|---|---|
| Build my own support inbox | tickets:readtickets:write | /tickets/admin/* |
| Show transcript history in my app | chat:read | /chat/conversations* |
| Send chat messages from my app or CRM | chat:write | /chat, /chat/stream |
| Answer live-chat handoffs | chat:readchat:write | /direct-chat/admin/* |
| Train the bot from my CMS or docs | knowledge:readknowledge:write | /knowledge*, /admin/knowledge/{id} |
| Manage canned answers | faq:readfaq:write | /faqs* |
| Build my own analytics screen | analytics:read | /admin/overview, /admin/analytics/* |
| Provision and manage widgets | widget:readwidget:write | /admin/widget-configs* |
| Configure the bot, AI provider and website | settings:readsettings:write | /admin/bot-settings, /admin/ai-settings, /admin/website |
| Manage users and agents | team:readteam:write | /admin/users, /admin/invite |
| Manage the role permission matrix | permissions:readpermissions:write | /admin/permissions/* |
| Show plan, usage and limits | billing:read | /billing/subscription, /billing/usage |
| Read-only reporting bot | chat:readtickets:readanalytics:read | reads only |
| Full first-party control panel | full access | everything below |
Scope reference
Unknown scopes are rejected at key creation with a 422. A missing scope at request time returns 403 with API key missing required scope: <scope>.
chat:readList conversations, read transcripts and live-chat sessionschat:writeSend messages, run live handoffs, delete conversations, submit feedbacktickets:readList tickets, read one ticket, ticket statisticstickets:writeReply to tickets and change their statusknowledge:readList knowledge sources and indexing statsknowledge:writeUpload, index and delete knowledge sourcesfaq:readList FAQs and categoriesfaq:writeCreate, edit and delete FAQs and categoriesanalytics:readDashboard overview, conversation, feedback and traffic analyticswidget:readRead widget configurationswidget:writeCreate, update, delete and set default widget configssettings:readRead bot, AI, website and general settingssettings:writeUpdate bot, AI and website settings, test AI providersteam:readList team members and assignable rolesteam:writeInvite, update and remove team memberspermissions:readRead the role permission matrixpermissions:writeChange role permissions and custom rolesbilling:readRead plan, subscription, usage and limitsImportant
analytics:read is present.Common integrations
Copy a recipe into your codebase and replace the environment variables with your own. Each one lists the exact scopes the key needs.
Add an AI assistant to your product
Send a message, keep the conversation id per thread, and stream tokens when you want a live-typing answer.
curl -s -X POST "$CHATONN_API/chat" \
-H "X-API-Key: $CHATONN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "How do I reset my password?",
"conversation_id": "b0b0b4d4-..."
}'Mirror the ticket inbox
List the queue, reply as an agent and change status. Poll every 30–60 seconds, not per browser tab.
type Ticket = {
id: number;
ticket_id: string;
subject: string;
status: "open" | "in_progress" | "resolved" | "closed";
priority: string;
created_at: string;
};
export async function openTickets(): Promise<Ticket[]> {
const data = await chatonn<{ tickets: Ticket[] }>(
"/tickets/admin/all?status=open&limit=50",
);
return data.tickets;
}
export function reply(ticketPk: number, message: string) {
return chatonn(`/tickets/admin/${ticketPk}/reply`, {
method: "POST",
body: JSON.stringify({ message }),
});
}
export function resolve(ticketPk: number) {
return chatonn(
`/tickets/admin/${ticketPk}/status?status=resolved`,
{ method: "PUT" },
);
}Push content from your CMS into the bot
Upload a document and wait for indexing, or crawl a sitemap. Indexing is asynchronous: poll the source until status is indexed.
import time
def sync_article(slug: str, title: str, markdown: str) -> int:
files = {"file": (f"{slug}.md", markdown, "text/markdown")}
created = call(
"POST",
"/knowledge/upload",
files=files,
data={"name": title},
)
source_id = created["id"]
for _ in range(30):
time.sleep(2)
sources = call("GET", "/knowledge")["sources"]
current = next((s for s in sources if s["id"] == source_id), None)
if current and current["status"] == "indexed":
return source_id
if current and current["status"] == "failed":
raise RuntimeError(current["error"])
raise TimeoutError(f"Indexing timed out for {source_id}")
# Or crawl a whole documentation site at once:
call(
"POST",
"/knowledge/import-sitemap",
json={
"sitemap_url": "https://docs.example.com/sitemap.xml",
"max_pages": 50,
},
)Pull analytics into your BI tool
Aggregate once per hour and store the result. Analytics endpoints are expensive and require a Pro plan or higher.
def weekly_report():
days = 7
return {
"overview": call("GET", f"/admin/analytics/overview?days={days}"),
"feedback": call("GET", f"/admin/analytics/feedback?days={days}"),
"tickets": call("GET", "/tickets/admin/stats"),
"usage": call("GET", "/billing/usage"),
}Manage FAQs from your admin screen
FAQ changes take effect immediately. Use is_active=false instead of deleting to keep history.
const { faqs } = await chatonn<{ faqs: Faq[] }>("/faqs");
await chatonn("/faqs", {
method: "POST",
body: JSON.stringify({
question: "Do you offer refunds?",
answer: "Yes, within 14 days of purchase.",
category: "billing",
tags: ["refund"],
}),
});
await chatonn(`/faqs/${faqId}`, {
method: "PUT",
body: JSON.stringify({ is_active: false }),
});Endpoint reference
All paths are relative to https://api.chatonn.com/api/v1. Full request and response schemas are in the live OpenAPI spec.
Chat
Ask the bot, stream answers and read transcripts.
| Method | Path | Scope |
|---|---|---|
| POST | /chat | chat:write |
| POST | /chat/streamSSE | chat:write |
| GET | /chat/conversations?limit=&user_id= | chat:read |
| GET | /chat/conversations/{conversation_id} | chat:read |
| DELETE | /chat/conversations/{conversation_id} | chat:write |
| POST | /chat/feedback | chat:write |
Live handoff
Human-agent live chat. Agent-only routes are shown.
| Method | Path | Scope |
|---|---|---|
| GET | /direct-chat/admin/sessions | chat:read |
| POST | /direct-chat/admin/read | chat:write |
| POST | /direct-chat/admin/assign | chat:write |
| POST | /direct-chat/admin/close | chat:write |
| WS | /direct-chat/ws/{session_id}?api_key= | chat:write |
Tickets
Tenant and agent routes. Widget routes need a visitor token.
| Method | Path | Scope |
|---|---|---|
| GET | /tickets/admin/all?status=&category=&limit= | tickets:read |
| GET | /tickets/admin/stats | tickets:read |
| GET | /tickets/admin/{ticket_pk} | tickets:read |
| POST | /tickets/admin/{ticket_pk}/reply | tickets:write |
| PUT | /tickets/admin/{ticket_pk}/status?status= | tickets:write |
Knowledge base
Uploads return immediately; poll /knowledge for index status.
| Method | Path | Scope |
|---|---|---|
| GET | /knowledge | knowledge:read |
| GET | /knowledge/stats | knowledge:read |
| POST | /knowledge/uploadmultipart | knowledge:write |
| POST | /knowledge/index-file | knowledge:write |
| POST | /knowledge/index-directory | knowledge:write |
| POST | /knowledge/import-sitemap | knowledge:write |
| DELETE | /admin/knowledge/{source_id} | knowledge:write |
FAQs
Canned answers used before the AI model.
| Method | Path | Scope |
|---|---|---|
| GET | /faqs | faq:read |
| GET | /faqs/{faq_id} | faq:read |
| GET | /faqs/categories | faq:read |
| POST | /faqs | faq:write |
| PUT | /faqs/{faq_id} | faq:write |
| DELETE | /faqs/{faq_id} | faq:write |
| DELETE | /faqs/categories/{category} | faq:write |
Analytics
All accept ?days=1..365. Requires a Pro plan or higher.
| Method | Path | Scope |
|---|---|---|
| GET | /admin/overview | analytics:read |
| GET | /admin/analytics/overview | analytics:read |
| GET | /admin/analytics/conversations | analytics:read |
| GET | /admin/analytics/feedback | analytics:read |
| GET | /admin/analytics/visits?page=&page_size= | analytics:read |
| GET | /admin/analytics/{sessions,events,funnel,heatmap} | analytics:read |
| GET | /admin/analytics/{performance,referrers,identities,form-fields} | analytics:read |
Widgets
Multiple named widgets; the legacy single config is /admin/widget-config.
| Method | Path | Scope |
|---|---|---|
| GET | /admin/widget-configs | widget:read |
| POST | /admin/widget-configs | widget:write |
| GET | /admin/widget-configs/{widget_id} | widget:read |
| PUT | /admin/widget-configs/{widget_id} | widget:write |
| DELETE | /admin/widget-configs/{widget_id} | widget:write |
| POST | /admin/widget-configs/{widget_id}/set-default | widget:write |
Settings
AI provider secrets are write-only; responses return them masked.
| Method | Path | Scope |
|---|---|---|
| GET | /admin/bot-settings | settings:read |
| PUT | /admin/bot-settings | settings:write |
| GET | /admin/website | settings:read |
| PUT | /admin/website | settings:write |
| GET | /admin/ai-settings | settings:read |
| PUT | /admin/ai-settings | settings:write |
| POST | /admin/ai-settings/test | settings:write |
| GET | /admin/ai-providers | settings:read |
| GET | /admin/settings | settings:read |
| PUT | /admin/settings | settings:write |
Team and permissions
Changes are attributed to “API key: <name>” in the audit log.
| Method | Path | Scope |
|---|---|---|
| GET | /admin/users | team:read |
| PUT | /admin/users/{user_id} | team:write |
| DELETE | /admin/users/{user_id} | team:write |
| POST | /admin/invite | team:write |
| GET | /admin/team/roles | team:read |
| GET | /admin/permissions/roles | permissions:read |
| PUT | /admin/permissions/roles/{role} | permissions:write |
Billing
Read-only. Checkout and plan changes need a user session.
| Method | Path | Scope |
|---|---|---|
| GET | /billing/subscription | billing:read |
| GET | /billing/usage | billing:read |
| GET | /billing/limits | billing:read |
| GET | /billing/plans | public |
Errors and limits
Scope failures are explicit, which makes them easy to catch during development. Read the status code first, then detail, then message.
| Status | Meaning | What to do |
|---|---|---|
| 400 | Bad request or invalid status value | Fix the payload |
| 401 | Missing, invalid or revoked key; inactive tenant | Check the key and tenant status |
| 403 | Missing scope, plan gate, or route needs a user session | Add the scope, upgrade, or use a JWT |
| 404 | Resource not found in this tenant | Check the id |
| 422 | Validation error or unknown scope | Fix the payload/scopes |
| 429 | Rate limit exceeded | Back off using Retry-After |
| 500 | Server error | Retry reads with backoff |
600 requests / minute per key
Configured with API_KEY_RATE_LIMIT_PER_MINUTE (0 disables it).
200 requests / minute per IP
Global guard. Cache lists and analytics on your side instead of polling per page view.
Tip
Retry-After header in seconds. Honour it with exponential backoff instead of retrying immediately.What API keys cannot do
These routes need a real user session (JWT) and are never reachable with a key:
Go live safely
A platform key is a production credential. Treat it like a database password and rotate it on a schedule.
- Store the key in a secret manager or server environment variable — never in frontend code or a git repository.
- One key per integration and environment, for example acme-prod-crm and acme-staging-crm.
- Grant the smallest scope set; start read-only and add writes per feature.
- Rotate by creating a new key, deploying it, then revoking the old one.
- Revoke keys that stop appearing in last_used_at.
- Never log the X-API-Key header; redact it in proxies and error trackers.
Rotating a key without downtime
- 1Create a new key with exactly the same scopes.
- 2Deploy it to the integration and confirm traffic is using it.
- 3Watch last_used_at on the old key drop to zero.
- 4Revoke the old key from API Access.
Important
Need the full reference?
The same guide ships inside the dashboard under API Access → Integration Guide, and as docs/PLATFORM_API.md in the repository. Generate typed clients directly from the OpenAPI spec.