Overview & Authentication

What the API does

The Chatonio API lets your own systems work with your support data programmatically. Over a versioned REST API you can list conversations, read and send messages, change a conversation’s status, create and update contacts, start outbound conversations, apply tags, and assign operators. With webhooks you can have Chatonio notify your server the moment something happens — for example, when a customer sends a new message.

Base URL & versioning

All API requests go to the versioned base URL:

https://chatonio.com/api/v1/

The current version is v1. New fields may be added to responses over time — write your integration to ignore unknown fields.

Authentication

The API is authenticated with a per-project API key sent as a bearer token:

Authorization: Bearer csk_live_your_key_here

To create a key, open your project’s Developer settings (Project settings → Developer), click Create key, and copy the value. The full key is shown once — store it securely; you cannot see it again. Revoke a key any time from the same page.

Treat API keys like passwords. Never commit them to source control or expose them in a browser / mobile app — the API key grants full access to your project’s conversations.

Scopes

Every key carries scopes that decide what it may do. Three of them form a ladder — each level includes the ones below it — and one is granted separately:

read — read conversations, messages, contacts and tags.
write — everything in read, plus sending messages, changing status, priority and AI mode, creating and updating contacts, starting conversations, and applying tags.
admin — everything in write, plus assigning and unassigning operators and managing webhook subscriptions.
pii — not part of the ladder, granted on its own: it adds the visitor’s IP address and user agent to the conversation detail. Country, browser and operating system are returned without it.

Creating an API key, with the four permission scopes

On the Developer page this list is labelled Permissions. New keys are created with read and write, and you can change a key’s scopes at any time from that page; narrowing a key takes effect on its next request, so you do not have to rotate it.

A call outside a key’s scopes returns 403 with insufficient_scope: <scope> required.

Keys created before scopes existed carry full access and keep working unchanged. Give them explicit scopes when convenient.

Plan requirement

The API and webhooks are available on the Advanced, Pro and Ultimate plans. If your plan doesn’t include it, requests return 403 with developer_api_not_available.

Quick start

List your most recently updated conversations:

curl https://chatonio.com/api/v1/conversations/ \
  -H "Authorization: Bearer csk_live_your_key_here"

Interactive reference

An auto-generated, always-current reference (OpenAPI / Swagger) lives at https://chatonio.com/api/v1/docs. It lists every endpoint, parameter, and response schema.