Carrot quest Web API API

Отрасль: CRM и продажи. Актуально на 2026-10-24.

Web API платформы автоматизации маркетинга и чатов Carrot quest: данные пользователей (лидов) и их свойства, события, ручные сообщения в чат, диалоги приложения и пользователя, список пользователей приложения. Отправлять запросы из браузерного JavaScript нельзя — для браузера используется JS-библиотека Carrot quest.

Сценарии

Передать данные пользователя с сервера

Обновлять карточку лида в Carrot quest данными из своей системы: имя, email, телефон, тариф, сумма покупок.

1. Создай API-ключ: «Настройки» → «Разработчикам» → «API-ключи». Передавай его в заголовке Authorization: Token <ключ>. Вызывай API только с сервера — из браузерного JavaScript нельзя, для сайта есть JS-библиотека.
2. Запиши свойства: POST /users/{id}/props, где id — твой User ID и by_user_id = true. В operations — список операций с op, key и value; системные свойства начинаются с $ ($name, $email, $phone), свои — без него.
3. Если пользователя с таким User ID ещё нет, Carrot quest его создаст. За запрос — до 250 свойств.
4. Невалидные операции не дают ошибку, а попадают в meta.ignored_operations — проверяй этот список в ответе.
5. Лимит — 60 запросов в минуту на ключ; при превышении придёт 429 TooManyRequests.

curl -X POST https://api.carrotquest.io/users/user_42/props \
  -H "Authorization: Token $CQ_TOKEN" \
  --data-urlencode 'by_user_id=true' \
  --data-urlencode 'operations=[
    {"op": "update_or_create", "key": "$name", "value": "Иван Петров"},
    {"op": "update_or_create", "key": "$email", "value": "ivan@example.ru"},
    {"op": "update_or_create", "key": "Тариф", "value": "Про"}
  ]'

Записать событие пользователя

Сообщить Carrot quest о действии, которое произошло на сервере: оплата, продление подписки, отмена заказа — для сегментов и автосообщений.

1. Запиши событие: POST /users/{id}/events с by_user_id = true, event — именем события (до 255 символов) и params — его свойствами.
2. Если событие произошло раньше, передай created — время в UTC (timestamp). Для таких событий автосообщения не планируются.
3. Проверь, что событие записалось: GET /users/{id}/events.
4. Используй одинаковые имена событий везде — по ним строятся сегменты и триггерные рассылки.

curl -X POST https://api.carrotquest.io/users/user_42/events \
  -H "Authorization: Token $CQ_TOKEN" \
  --data-urlencode 'by_user_id=true' \
  --data-urlencode 'event=Оплатил заказ' \
  --data-urlencode 'params={"Номер заказа": "1042", "Сумма": 15000}'

Написать пользователю в чат

Отправить сообщение от имени поддержки: статус заказа, ответ на обращение из другой системы.

1. Найди пользователя: GET /users/{id} с by_user_id = true. Если его нет, вернётся 400 LookupError.
2. Отправь сообщение: POST /users/{id}/sendmessage с body — текстом. type задаёт вид: popup_chat (по умолчанию), popup_small или popup_big.
3. В ответе data.conversation — ID диалога и data.message — ID сообщения. По ID диалога можно получить переписку: GET /conversations/{id}.

curl -X POST https://api.carrotquest.io/users/user_42/sendmessage \
  -H "Authorization: Token $CQ_TOKEN" \
  --data-urlencode 'by_user_id=true' \
  --data-urlencode 'body=Ваш заказ №1042 передан в доставку. Курьер привезёт его завтра с 14 до 16.'

Выгрузить неразобранные диалоги

Забирать открытые обращения, которые никому не назначены, — для отчёта или своей системы поддержки.

1. Запроси диалоги приложения: GET /apps/{id}/conversations с closed = false и assigned = 0 (неразобранные). Отбор по тегам — tags, по каналу — channel.
2. Для следующей страницы используй параметры пагинации из meta, например next_after.
3. Полную переписку по диалогу получай через GET /conversations/{id}, а все диалоги конкретного пользователя — через GET /users/{id}/conversations.
4. Для событий в реальном времени (новое сообщение, закрытие диалога) удобнее вебхуки — опрос упрётся в лимит 60 запросов в минуту.

curl -G https://api.carrotquest.io/apps/<ID приложения>/conversations \
  -H "Authorization: Token $CQ_TOKEN" \
  -d closed=false -d assigned=0

Базовые URL

• Боевой: https://api.carrotquest.io

Авторизация

Тип: API-ключ

Токен берётся в панели администратора: «Настройки» → «Разработчикам» → «API-ключи». Передаётся в заголовке Authorization: Token <токен> (или Bearer <токен>) либо параметром auth_token.

curl -X GET -H "Authorization: Token <ваш_токен>" https://api.carrotquest.io/users/123

Методы

GET /users/{id} — Данные пользователя

Если пользователя нет — 400 LookupError.

Параметр	Где	Тип	Обяз.	Описание
id	path	string	да	ID в Carrot quest или ваш User ID (с by_user_id=true)
by_user_id	query	boolean	нет	Искать по вашему User ID, по умолчанию false
props	query	boolean	нет	Системные свойства, по умолчанию true
props_events	query	boolean	нет	Свойства, связанные с событиями
props_custom	query	boolean	нет	Пользовательские свойства
events	query	boolean	нет	События
segments	query	boolean	нет	Сегменты
notes	query	boolean	нет	Заметки
tags	query	boolean	нет	Теги
email_status	query	boolean	нет	Статус подписки на email
app	query	integer	нет	ID приложения (по умолчанию из токена)

POST /users/{id}/props — Установка свойств пользователя

Операции выполняются по порядку; невалидные не дают ошибку, а попадают в meta.ignored_operations. Если пользователя с таким User ID нет, он создаётся.

Параметр	Где	Тип	Обяз.	Описание
id	path	string	да	ID в Carrot quest или ваш User ID
by_user_id	body	boolean	нет	Искать по вашему User ID
operations	body	array	да	Операции op, key, value, до 250 свойств; системные свойства начинаются с $
double_subscribe	body	boolean	нет	Переподписать отписанного при обновлении $email
parse_custom_props_type	body	boolean	нет	Определять тип пользовательских свойств, по умолчанию true
source	body	object	нет	Источник контакта для $email/$phone (type, id)

Пример запроса:

curl -X POST \
  --data-urlencode "operations=[{"op": "update_or_create", "key": "$name", "value": "Maks"}]" \
  -H "Authorization: Token XXX" \
  https://api.carrotquest.io/users/8173131/props

Пример ответа:

{
  "meta": {
    "status": 200,
    "affected_props": [],
    "ignored_operations": []
  },
  "data": {
    "id": 123123123,
    "app": 12345
  }
}

POST /users/{id}/events — Запись события

Параметр	Где	Тип	Обяз.	Описание
id	path	string	да	ID в Carrot quest или ваш User ID
by_user_id	body	boolean	нет	Искать по вашему User ID
event	body	string	да	Имя события, 1–255 символов; системные — с $
params	body	object	нет	Свойства события
created	body	integer	нет	Время события (timestamp UTC); при передаче автосообщения не планируются

GET /users/{id}/events — События пользователя

Параметр	Где	Тип	Обяз.	Описание
id	path	string	да	ID пользователя
by_user_id	query	boolean	нет	Искать по вашему User ID

POST /users/{id}/sendmessage — Ручное сообщение пользователю

В ответе data: conversation (ID диалога) и message (ID сообщения).

Параметр	Где	Тип	Обяз.	Описание
id	path	string	да	ID пользователя
by_user_id	body	boolean	нет	Искать по вашему User ID
body	body	string	да	Текст сообщения
type	body	string	нет	popup_chat (по умолчанию), popup_small, popup_big

Пример запроса:

curl -X POST \
  --data-urlencode 'body=Hello' \
  -H "Authorization: Token XXX" \
  https://api.carrotquest.io/users/2137216/sendmessage

GET /users/{id}/conversations — Диалоги с пользователем

Параметр	Где	Тип	Обяз.	Описание
id	path	string	да	ID пользователя

GET /apps/{id}/conversations — Диалоги приложения

В meta — параметры пагинации (например, next_after).

Параметр	Где	Тип	Обяз.	Описание
id	path	integer	да	ID приложения
closed	query	boolean	нет	Закрытые (true) или открытые (false)
answered	query	boolean	нет	Последним ответил админ (true) или пользователь (false)
assigned	query	integer	нет	ID администратора; 0 — неразобранные
tags	query	array	нет	Диалоги со всеми указанными тегами
channel	query	integer	нет	ID канала; 0 — без канала

GET /apps/{id}/users — Пользователи (лиды) приложения

Параметр	Где	Тип	Обяз.	Описание
id	path	integer	да	ID приложения

GET /conversations/{id} — Диалог

Параметр	Где	Тип	Обяз.	Описание
id	path	integer	да	ID диалога

Нюансы

• Параметры передаются GET- или POST-параметрами в UTF-8.
• Ответы — JSON с полями meta и data; meta.status дублирует HTTP-код.
• {id} пользователя — ID Carrot quest или ваш User ID с by_user_id=true; запись свойств и событий по неизвестному User ID создаёт пользователя.
• Токен даёт почти неограниченный доступ к данным приложения — не передавайте его третьим лицам.
• Для получения событий в реальном времени есть вебхуки и Realtime Services API.

Ошибки

Код	Описание
400 LookupError	Пользователь не найден
429 TooManyRequests	Превышен лимит запросов

Ограничения

• 60 запросов в минуту на один API-ключ.
• До 250 свойств за один запрос props.

Источники

• Web API — общее
• Авторизация
• Ограничения
• Методы Web API
• Свойства пользователя
• Запись события
• Ручное сообщение
• Данные пользователя
• Диалоги приложения

---

Если этого недостаточно — официальная документация: https://developers.carrotquest.io/webapi/ JSON: https://mcp-everything.ru/api/integrations/carrot-quest. MCP: https://mcp-everything.ru/mcp