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
Метод | URL | Описание |
---|---|---|
GET | /apps/{id}/activeusers | Получить онлайн-пользователей на сайте |
GET | /apps/{id}/users | Получить пользователей (лидов) |
GET | /apps/{id}/conversations | Получить диалоги приложения |
GET | /apps/{id}/channels | Получить каналы приложения |
Метод | 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 | Закрыть диалог |
Метод | 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 | Внутренняя ошибка сервиса |