Обзор и аутентификация

Что умеет API

API Chatonio позволяет вашим системам работать с данными поддержки программно. Через версионированный REST API можно получать список диалогов, читать и отправлять сообщения, менять статус диалога, создавать и изменять контакты, начинать исходящие диалоги, проставлять теги и назначать операторов. С помощью вебхуков Chatonio уведомляет ваш сервер в момент события — например, когда клиент присылает новое сообщение.

Базовый URL и версии

Все запросы отправляются на версионированный базовый URL:

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

Текущая версия — v1. Со временем в ответы могут добавляться новые поля — пишите интеграцию так, чтобы неизвестные поля игнорировались.

Аутентификация

API использует API-ключ проекта, передаваемый как bearer-токен:

Authorization: Bearer csk_live_your_key_here

Чтобы создать ключ, откройте настройки Developer вашего проекта (Настройки проекта → Developer), нажмите Создать ключ и скопируйте значение. Полный ключ показывается один раз — сохраните его надёжно, увидеть снова его нельзя. Ключ можно отозвать в любой момент на этой же странице.

Обращайтесь с API-ключами как с паролями. Никогда не коммитьте их в репозиторий и не раскрывайте в браузере / мобильном приложении — ключ даёт полный доступ к диалогам проекта.

Права доступа

У каждого ключа есть права доступа, которые определяют, что им можно делать. Три из них образуют лестницу — каждый уровень включает предыдущие, — а одно выдаётся отдельно:

read — чтение диалогов, сообщений, контактов и тегов.
write — всё из read, плюс отправка сообщений, изменение статуса, приоритета и режима ИИ, создание и изменение контактов, создание диалогов и проставление тегов.
admin — всё из write, плюс назначение и снятие операторов и управление подписками на вебхуки.
pii — не входит в лестницу и выдаётся отдельно: добавляет IP-адрес и user agent посетителя в детали диалога. Страна, браузер и операционная система возвращаются и без него.

Создание API-ключа с четырьмя правами доступа

Новые ключи создаются с правами read и write. Права можно изменить в любой момент на странице Developer; сужение прав вступает в силу со следующего запроса, перевыпускать ключ не нужно.

Запрос за пределами прав ключа возвращает 403 с кодом insufficient_scope: <scope> required.

Ключи, созданные до появления прав, имеют полный доступ и продолжают работать без изменений. Назначьте им явные права, когда будет удобно.

Требования к тарифу

API и вебхуки доступны на тарифах Advanced, Pro и Ultimate. Если ваш тариф их не включает, запросы возвращают 403 с кодом developer_api_not_available.

Быстрый старт

Получить недавно обновлённые диалоги:

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

Интерактивный справочник

Автоматически генерируемый актуальный справочник (OpenAPI / Swagger) доступен по адресу https://chatonio.com/api/v1/docs. Там перечислены все эндпоинты, параметры и схемы ответов.