Web API

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

Авторизация

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

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. Токен можно сгенерировать в панели администратора ("Настройки > Разработчикам").

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 в минуту. При превышении этого лимита запросы не принимаются. При значительном превышении ключ может быть автоматически заблокирован. Если вам требуется массово обновлять данные пользователей, формируйте очереди запросов, чтобы не превышать допустимое количество запросов в минуту. Если нужно отправлять более 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 Внутренняя ошибка сервиса