# Интеграция с CarrotQuest ### Инструкция по настройке Webhook CarrotQuest для интеграции с MacroCRM **Для специалистов CarrotQuest и тех, кто настраивает интеграцию CarrotQuest с MacroCRM** Данная инструкция описывает типы Webhook запросов, структуру данных, матрицу полей и API описание для интеграции CarrotQuest с MacroCRM. *** #### 4. Типы Webhook запросов MacroCRM поддерживает два типа Webhook запросов от CarrotQuest: * **`TYPE_CLASSIC` (`event`)**: Классический тип Webhook, отправляет данные о различных системных событиях, происходящих с пользователями на вашем сайте (просмотр страниц, изменение данных профиля, UTM инициализация и т.д.). Эти события инициируются системой CarrotQuest автоматически при определенных действиях пользователя. * **`TYPE_TRIGGER` (`message_webhook`)**: Webhook, отправляемый при срабатывании триггеров в CarrotQuest. Эти триггеры могут быть настроены для срабатывания при определенных условиях, например, при заполнении формы в чате или при отправке сообщения через триггерное сообщение. Данный тип Webhook предназначен для передачи данных, собранных в рамках триггерных сценариев. **Важно!** При настройке Webhook в CarrotQuest, необходимо выбрать, какой тип запросов будет отправляться в MacroCRM. Для полноценной интеграции лидов рекомендуется настроить отправку **обоих типов** Webhook запросов. `TYPE_CLASSIC` для отслеживания системных событий (например, UTM меток, изменений контактных данных), и `TYPE_TRIGGER` для получения данных из диалогов и форм, настроенных в триггерах CarrotQuest. #### 5. Структура данных Webhook запроса **5.1. Общая структура для обоих типов** Независимо от типа Webhook, запрос от CarrotQuest к MacroCRM представляет собой `POST` запрос в формате `application/json`. Основная структура данных для **обоих типов** включает следующие обязательные поля: * **`token`**: Строка токена для аутентификации запроса. Этот токен должен быть настроен как в CarrotQuest, так и в MacroCRM (в настройках интеграции CarrotQuest в MacroCRM). * **`type`**: Строка, указывающая тип Webhook запроса. Возможные значения: `"event"` (для `TYPE_CLASSIC`) или `"message_webhook"` (для `TYPE_TRIGGER`). **5.2. Структура данных для `TYPE_CLASSIC` (`event`)** Для Webhook типа `event`, данные об событии и пользователе передаются вложенными объектами `event` и `user` соответственно. ```json { "token": "your_webhook_token", "type": "event", "event": { "type": { "name": "[Название системного события]" // Например, "$session_start", "$utm_hit", "$phone_changed" }, "props": { // Объект со свойствами события, зависят от типа события // Например, для "$utm_hit": "$utm_campaign", "$utm_source", "$utm_medium", ... // Для "$phone_changed": "old_value", "new_value" }, // ... другие поля объекта события (см. документацию CarrotQuest) }, "user": { "id": "[ID пользователя в CarrotQuest]", "props": { "$phone": "[Номер телефона пользователя]", "$email": "[Email пользователя]", "$name": "[Имя пользователя]", "$initial_utm_campaign": "[UTM кампания]", "$initial_utm_source": "[UTM источник]", "$initial_utm_medium": "[UTM medium]", "$initial_utm_content": "[UTM content]", "$initial_utm_term": "[UTM term]", // ... другие свойства пользователя (см. документацию CarrotQuest) }, // ... другие поля объекта пользователя (см. документацию CarrotQuest) } } ``` **Ключевые поля `TYPE_CLASSIC`:** * **`event.type.name`**: Название системного события CarrotQuest. MacroCRM обрабатывает следующие системные события: * `$utm_hit`: Событие инициализации UTM меток при первом посещении сайта пользователем. * `$phone_changed`: Событие изменения номера телефона пользователя. * `$email_changed`: Событие изменения email пользователя. * **`event.props`**: Свойства события, специфичные для каждого типа системного события. * **`user.props`**: Свойства пользователя, включая контактные данные (`$phone`, `$email`, `$name`) и UTM метки, зафиксированные при первом посещении (`$initial_utm_*`). **5.3. Структура данных для `TYPE_TRIGGER` (`message_webhook`)** Для Webhook типа `message_webhook` (триггерные сообщения), данные передаются непосредственно в корне JSON объекта. ```json { "token": "your_webhook_token", "type": "message_webhook", "CarrotID": "[ID пользователя в CarrotQuest]", "Имя": "[Имя пользователя из формы триггера]", "Телефон": "[Номер телефона из формы триггера]", "email": "[Email из формы триггера]", "utmCampaign": "[UTM кампания]", "utmSource": "[UTM источник]", "utmMedium": "[UTM medium]", "utmContent": "[UTM content]", "utmTerm": "[UTM term]", "Комментарий CQ": "[Комментарий 1, настроенный в триггере]", "Комментарий CQ 2.0": "[Комментарий 2, настроенный в триггере]", // ... другие поля, добавленные в триггерном сообщении CarrotQuest } ``` **Ключевые поля `TYPE_TRIGGER`:** * **`CarrotID`**: ID пользователя в CarrotQuest. * **`Имя`**, **`Телефон`**, **`email`**: Данные пользователя, собранные через форму в триггерном сообщении CarrotQuest. Названия полей соответствуют русскоязычным названиям, как показано в примере. * **`utmCampaign`**, **`utmSource`**, **`utmMedium`**, **`utmContent`**, **`utmTerm`**: UTM метки, если настроена их передача в триггерном сообщении. **Важно!** Названия UTM параметров в `TYPE_TRIGGER` отличаются от `TYPE_CLASSIC` (отсутствует префикс `$initial_utm_`). * **`Комментарий CQ`**, **`Комментарий CQ 2.0`**: Поля для передачи комментариев к лиду, которые могут быть добавлены в настройках триггерного сообщения CarrotQuest. #### 6. Матрица полей для настройки Webhook в CarrotQuest Для обеспечения корректной интеграции и передачи данных из CarrotQuest в MacroCRM, особенно для `TYPE_TRIGGER` Webhook, необходимо согласовать названия полей в CarrotQuest с ожидаемыми полями в MacroCRM. **6.1. `TYPE_CLASSIC` (`event`) Webhook** Для системных событий (`TYPE_CLASSIC`), **дополнительная настройка полей в CarrotQuest не требуется**. CarrotQuest автоматически отправляет данные в предопределенном формате, который MacroCRM ожидает для системных событий. **6.2. `TYPE_TRIGGER` (`message_webhook`) Webhook (Триггерные сообщения)** При настройке триггерных сообщений в CarrotQuest, **важно убедиться, что названия полей, используемые в триггере (особенно в формах), соответствуют следующей матрице**, чтобы MacroCRM мог корректно распознать и обработать данные. | Поле в форме триггера CarrotQuest | Название поля в Webhook запросе (`TYPE_TRIGGER`) | Поле в MacroCRM (Лид) | Описание | | --------------------------------- | ------------------------------------------------ | ---------------------------- | ------------------------------------------ | | Имя | `Имя` | `name` | Имя клиента | | Телефон | `Телефон` | `phone` | Номер телефона клиента | | Email | `email` | `email` | Email клиента | | UTM кампания | `utmCampaign` | `utm.utm_campaign` | UTM кампания | | UTM источник | `utmSource` | `utm.utm_source` | UTM источник | | UTM medium | `utmMedium` | `utm.utm_medium` | UTM medium | | UTM content | `utmContent` | `utm.utm_content` | UTM content | | UTM term | `utmTerm` | `utm.utm_term` | UTM term | | Комментарий CQ | `Комментарий CQ` | `notes` | Комментарий к лиду (заметка 1) | | Комментарий CQ 2.0 | `Комментарий CQ 2.0` | `notes` | Комментарий к лиду (заметка 2) | | **CarrotQuest ID (скрытое поле)** | `CarrotID` | `carrotquest_cid` | ID пользователя в CarrotQuest (для связки) | | **Тип лида (скрытое поле)** | (не передается явно) | `type: 'living'` | Тип лида (живой лид) | | **Активность (скрытое поле)** | (не передается явно) | `activity: 'buy'` | Активность лида (покупка) | | **Источник (скрытое поле)** | (не передается явно) | `from_source: 'carrotquest'` | Источник лида (CarrotQuest) | **Рекомендации по настройке полей в триггерах CarrotQuest:** * **Используйте указанные названия полей** в формах триггерных сообщений CarrotQuest (например, "Имя", "Телефон", "Email"). * **Для UTM меток**, если необходимо их передавать через триггер, убедитесь, что названия полей в CarrotQuest соответствуют: `utmCampaign`, `utmSource`, `utmMedium`, `utmContent`, `utmTerm`. * **Для комментариев**, используйте поля с названиями "Комментарий CQ" и "Комментарий CQ 2.0", если требуется передавать комментарии к лиду из триггерных сообщений. * **Скрытые поля**: Поля "CarrotQuest ID", "Тип лида", "Активность", "Источник" **не нужно добавлять в настройки триггера CarrotQuest**. MacroCRM автоматически добавляет эти данные при обработке Webhook запроса типа `TYPE_TRIGGER`. #### 7. Описание API (с точки зрения MacroCRM) **Endpoint URL:** `[URL вашей MacroCRM]/api/web/carrotquest/[ID компании]/[Ключ безопасности]` **HTTP Method:** `POST` **Request Body Format:** `application/json` **Request Body Parameters:** **Для `TYPE_CLASSIC` (`event`)** ```json { "token": "string", // Обязательный, токен для аутентификации "type": "string", // Обязательный, всегда "event" "event": { "type": { "name": "string" // Обязательный, название системного события (например, "$utm_hit", "$phone_changed") }, "props": { // Объект, свойства события (зависит от типа события) }, // ... другие поля объекта события (см. документацию CarrotQuest) }, "user": { "id": "integer", // Обязательный, ID пользователя в CarrotQuest "props": { "$phone": "string", // Номер телефона пользователя "$email": "string", // Email пользователя "$name": "string", // Имя пользователя "$initial_utm_campaign": "string", // UTM кампания "$initial_utm_source": "string", // UTM источник "$initial_utm_medium": "string", // UTM medium "$initial_utm_content": "string", // UTM content "$initial_utm_term": "string", // UTM term // ... другие свойства пользователя }, // ... другие поля объекта пользователя } } ``` **Для `TYPE_TRIGGER` (`message_webhook`)** ```json { "token": "string", // Обязательный, токен для аутентификации "type": "string", // Обязательный, всегда "message_webhook" "CarrotID": "integer", // Обязательный, ID пользователя в CarrotQuest "Имя": "string", // Имя пользователя (из формы триггера) "Телефон": "string", // Телефон пользователя (из формы триггера) "email": "string", // Email пользователя (из формы триггера) "utmCampaign": "string", // UTM кампания "utmSource": "string", // UTM источник "utmMedium": "string", // UTM medium "utmContent": "string", // UTM content "utmTerm": "string", // UTM term "Комментарий CQ": "string", // Комментарий 1 "Комментарий CQ 2.0": "string", // Комментарий 2 // ... другие поля, настроенные в триггерном сообщении } ``` **Response Codes:** * **`200 OK`**: Успешная обработка Webhook запроса. MacroCRM возвращает JSON: `{"success": true}`. * **`[Error Code]`**: В случае ошибки (например, невалидный токен, невалидные данные пользователя). MacroCRM возвращает JSON: `{"success": false, "error": "[Сообщение об ошибке]"}`. Код ошибки HTTP может варьироваться в зависимости от типа ошибки. *** **Обратите внимание:** Данный документ предназначен для специалистов, настраивающих интеграцию CarrotQuest с MacroCRM. При настройке Webhook в личном кабинете CarrotQuest, используйте данную инструкцию как руководство по типам запросов, структуре данных и необходимым названиям полей для обеспечения корректной передачи данных в MacroCRM.