---
slug: "carrot-quest"
name: "Carrot quest Web API"
vendor: "Carrot quest"
industry: "crm"
docsUrl: "https://developers.carrotquest.io/webapi/"
version: 2
updatedAt: "2026-10-24"
---

# Carrot quest Web 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.

```bash
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. Используй одинаковые имена событий везде — по ним строятся сегменты и триггерные рассылки.

```bash
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}.

```bash
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 запросов в минуту.

```bash
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
```

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

```json
{
  "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 — общее](https://developers.carrotquest.io/webapi/)
- [Авторизация](https://developers-v2.carrotquest.io/webapi/auth/)
- [Ограничения](https://developers-v2.carrotquest.io/webapi/limits/)
- [Методы Web API](https://developers-v2.carrotquest.io/webapi/endpoints/)
- [Свойства пользователя](https://developers-v2.carrotquest.io/webapi/endpoints/users/props/)
- [Запись события](https://developers-v2.carrotquest.io/webapi/endpoints/users/events/post/)
- [Ручное сообщение](https://developers-v2.carrotquest.io/webapi/endpoints/users/sendmessage/)
- [Данные пользователя](https://developers-v2.carrotquest.io/webapi/endpoints/users/user/)
- [Диалоги приложения](https://developers-v2.carrotquest.io/webapi/endpoints/apps/conversations/)

---

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