Chatonn logoChatonn
Back to Documentation
Platform API

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.

Base URL

https://api.chatonn.com/api/v1

Auth

X-API-Key: chatonn_...

Envelope

{ success, statusCode, data }

Section 01

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.
Section 02

Create an API key

Generate keys from the dashboard with your user login. API Access is the only place a key is ever revealed.

  1. 1Open Dashboard → API Access and click Create API Key.
  2. 2Name it for the integration and environment, e.g. acme-prod-crm.
  3. 3Tick the read scopes you need first, then add write scopes only for features you really change.
  4. 4Copy the key from the dialog - it is shown once - and store it as CHATONN_API_KEY on your server.
  5. 5Send X-API-Key on every request, and revoke the key when the integration retires.

Tip

No scopes selected? The key gets the default surface: chat:read, chat:write, tickets:read, tickets:write. Add knowledge, FAQs, analytics and the rest by creating a new key with those scopes.
Section 03

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

Never ship a key to a browser or mobile app you distribute. If your frontend needs data, call ChatONN from your backend and proxy the result. A key in a bundle is a public key.
Section 04

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...ScopesMain 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 sessions
chat:writeSend messages, run live handoffs, delete conversations, submit feedback
tickets:readList tickets, read one ticket, ticket statistics
tickets:writeReply to tickets and change their status
knowledge:readList knowledge sources and indexing stats
knowledge:writeUpload, index and delete knowledge sources
faq:readList FAQs and categories
faq:writeCreate, edit and delete FAQs and categories
analytics:readDashboard overview, conversation, feedback and traffic analytics
widget:readRead widget configurations
widget:writeCreate, update, delete and set default widget configs
settings:readRead bot, AI, website and general settings
settings:writeUpdate bot, AI and website settings, test AI providers
team:readList team members and assignable roles
team:writeInvite, update and remove team members
permissions:readRead the role permission matrix
permissions:writeChange role permissions and custom roles
billing:readRead plan, subscription, usage and limits

Important

Analytics is plan-gated. On a plan without the analytics dashboard the API returns 403 with an upgrade message even when analytics:read is present.
Section 05

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.

chat:readchat:write
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.

tickets:readtickets:write
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.

knowledge:readknowledge:write
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.

analytics:read
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.

faq:readfaq:write
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 }),
});
Section 06

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.

MethodPathScope
POST/chatchat:write
POST/chat/streamSSEchat: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/feedbackchat:write

Live handoff

Human-agent live chat. Agent-only routes are shown.

MethodPathScope
GET/direct-chat/admin/sessionschat:read
POST/direct-chat/admin/readchat:write
POST/direct-chat/admin/assignchat:write
POST/direct-chat/admin/closechat:write
WS/direct-chat/ws/{session_id}?api_key=chat:write

Tickets

Tenant and agent routes. Widget routes need a visitor token.

MethodPathScope
GET/tickets/admin/all?status=&category=&limit=tickets:read
GET/tickets/admin/statstickets:read
GET/tickets/admin/{ticket_pk}tickets:read
POST/tickets/admin/{ticket_pk}/replytickets:write
PUT/tickets/admin/{ticket_pk}/status?status=tickets:write

Knowledge base

Uploads return immediately; poll /knowledge for index status.

MethodPathScope
GET/knowledgeknowledge:read
GET/knowledge/statsknowledge:read
POST/knowledge/uploadmultipartknowledge:write
POST/knowledge/index-fileknowledge:write
POST/knowledge/index-directoryknowledge:write
POST/knowledge/import-sitemapknowledge:write
DELETE/admin/knowledge/{source_id}knowledge:write

FAQs

Canned answers used before the AI model.

MethodPathScope
GET/faqsfaq:read
GET/faqs/{faq_id}faq:read
GET/faqs/categoriesfaq:read
POST/faqsfaq: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.

MethodPathScope
GET/admin/overviewanalytics:read
GET/admin/analytics/overviewanalytics:read
GET/admin/analytics/conversationsanalytics:read
GET/admin/analytics/feedbackanalytics: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.

MethodPathScope
GET/admin/widget-configswidget:read
POST/admin/widget-configswidget: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-defaultwidget:write

Settings

AI provider secrets are write-only; responses return them masked.

MethodPathScope
GET/admin/bot-settingssettings:read
PUT/admin/bot-settingssettings:write
GET/admin/websitesettings:read
PUT/admin/websitesettings:write
GET/admin/ai-settingssettings:read
PUT/admin/ai-settingssettings:write
POST/admin/ai-settings/testsettings:write
GET/admin/ai-providerssettings:read
GET/admin/settingssettings:read
PUT/admin/settingssettings:write

Team and permissions

Changes are attributed to “API key: <name>” in the audit log.

MethodPathScope
GET/admin/usersteam:read
PUT/admin/users/{user_id}team:write
DELETE/admin/users/{user_id}team:write
POST/admin/inviteteam:write
GET/admin/team/rolesteam:read
GET/admin/permissions/rolespermissions:read
PUT/admin/permissions/roles/{role}permissions:write

Billing

Read-only. Checkout and plan changes need a user session.

MethodPathScope
GET/billing/subscriptionbilling:read
GET/billing/usagebilling:read
GET/billing/limitsbilling:read
GET/billing/planspublic
Section 07

Errors and limits

Scope failures are explicit, which makes them easy to catch during development. Read the status code first, then detail, then message.

StatusMeaningWhat to do
400Bad request or invalid status valueFix the payload
401Missing, invalid or revoked key; inactive tenantCheck the key and tenant status
403Missing scope, plan gate, or route needs a user sessionAdd the scope, upgrade, or use a JWT
404Resource not found in this tenantCheck the id
422Validation error or unknown scopeFix the payload/scopes
429Rate limit exceededBack off using Retry-After
500Server errorRetry 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

A rate-limited request returns 429 with a 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:

Create or revoke API keys
Account security and audit logs
GDPR export and account deletion
Billing checkout, plan changes, customer portal
Database Connect (it can run SQL)
Leads administration and super-admin routes
Section 08

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

  1. 1Create a new key with exactly the same scopes.
  2. 2Deploy it to the integration and confirm traffic is using it.
  3. 3Watch last_used_at on the old key drop to zero.
  4. 4Revoke the old key from API Access.

Important

Keys are shown once and there is no reveal endpoint. If a key leaks, revoke it immediately, then create a replacement - do not try to rotate it in place.

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.