Web API

Web API позволяет вам производить сложную интеграцию с Carrot quest и использовать систему на полную мощность.

Авторизация

Каждый запрос к API должен сопровождаться параметром auth_token. Токены можно создавать в панели администратора, в разделе "Настройки > Разработчикам":

Основы

Web API выдержан в стиле REST. Описание всех методов доступно в разделе методы. Базовый URL: https://api.carrotquest.io/v1. Рекомендуется взаимодействовать с API через HTTPS. Если такой возможности нет, можно использовать обычный HTTP. Однако, в будущем мы оставляем за собой право ограничить использование API через HTTP.

Аргументы могут передаваться как GET или POST параметры. Используется кодировка UTF-8.

Все ответы представляют собой JSON-объект. Используется особый "конверт":

{
    "meta": {
        "status": 200
    },
    "data": {
        ...
    }
}

Раздел meta содержит дополнительную информацию для разработчиков.

Поле status дублирует HTTP-код ответа. Статус 200 означает успешно выполненный запрос. Все остальные коды означают ошибку. Пример ответа с ошибкой:

{
    "meta": {
        "status": 400,
        "error_message": "The request could not be understood by the server due to malformed syntax",
        "error": "BadRequest"
    },
    "data": {}
}

Поле status содержит HTTP-код (400) и появляются дополнительные поля error (название ошибки) и error_message (более подробное описание ошибки, понятное для человека).

Описание возможных ошибок можно найти на странице соответствующего метода.

Пагинация

Некоторые методы возвращают множество объектов (диалоги, пользователи, события и т.д.). Мы предоставляем удобный способ получить весь набор данных за несколько последовательных запросов. Используется cursor-based пагинация.

В методах, поддерживающих пагинацию, в раздел meta добавляется поле next_after. Чтобы получить следующую страницу с данными, нужно повторить запрос с теми же параметрами, но, добавив параметр after, равный значению next_after из предыдущего вызова. Если next_after равен null - это означает, что следующей страницы нет и все данные получены.

В некоторых методах next_after — это целое число, в некоторых — число с плавающей точкой. Поэтому мы рекомендуем использовать строку для хранения курсора.

Параметр count задает максимальное количество объектов, которые будут возвращены в вызове (от 1 до 50). По умолчанию: 20.

Методы

Все вызовы требуют указания auth_token. Токен можно сгенерировать в панели администратора ("Настройки > Разработчикам"). Для получения в ответе целочисленного идентификатора carrotquest_uid и conversation_id в виде строки в запрос нужно добавить параметр id_as_string=true

Apps

Метод	URL	Описание
GET	/apps/{id}/activeusers	Получить онлайн-пользователей на сайте
GET	/apps/{id}/users	Получить пользователей (лидов)
GET	/apps/{id}/conversations	Получить диалоги приложения
GET	/apps/{id}/channels	Получить каналы приложения

Conversations

Метод	URL	Описание
GET	/conversations/{id}	Получить конкретный диалог
GET	/conversations/{id}/parts	Получить части (сообщения) диалога
POST	/conversations/{id}/reply	Ответить в диалоге
POST	/conversations/{id}/markread	Отметить диалог прочитанным (со стороны пользователя на сайте)
POST	/conversations/{id}/settyping	Кто-то печатает ...
POST	/conversations/{id}/assign	Назначить диалог администратору
POST	/conversations/{id}/tag	Добавить или удалить тег диалога
POST	/conversations/{id}/close	Закрыть диалог

Users

Метод	URL	Описание
GET	/users/{id}	Получить данные о пользователе
GET	/users/{id}/events	Получить события, совершенные пользователем
GET	/users/{id}/conversations	Получить диалоги с пользователем
POST	/users/{id}/events	Записать событие
POST	/users/{id}/props	Установить свойства пользователя
POST	/users/{id}/setpresence	Отправить heartbeat сигнал
POST	/users/{id}/sendmessage	Отправить ручное сообщение пользователю
POST	/users/{id}/startconversation	Создать диалог, начатый пользователем на сайте
POST	/users/{id}/unsubscribeemail	Отписывает пользователя от рассылки

Лимиты

На данный момент максимально допустимое количество серверных запросов для одного API ключа при отправке запросов через API — 60 в минуту. При превышении этого лимита запросы не принимаются. При значительном превышении ключ может быть автоматически заблокирован. Если вам требуется массово обновлять данные пользователей, формируйте очереди запросов, чтобы не превышать допустимое количество запросов в минуту.

Ошибки

Эта таблица содержит ошибки, которые могут быть возвращены. Однако, в случае непредвиденных ситуаций ввиду неработоспособности сервиса могут возникнуть другие ошибки. Всегда следует проверять параметр meta.status.

Ошибка	Код	Описание
MethodNotAllowed	405	Неверный HTTP-метод
Error404	404	Указанный метод API не существует
NotAuthenticated	401	Токен авторизации неверен (или отсутствует)
PermissionDeniedError	403	У токена авторизации недостаточно прав (скорее всего, объект принадлежит другому приложению)
TooManyRequests	429	Превышен лимит на количество запросов
ValidationError	400	Ошибка валидации аргументов запроса. Подробности ошибки указаны в полях ответа meta.error_fields и meta.error_message
BadRequest	400	Ошибка в параметрах запроса. Подробности указаны в поле ответа meta.error_message
LookupError	400	Указанный в параметрах идентификатор не найден
Error500	500	Внутренняя ошибка сервиса