Интеграция с 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 соответственно.

{
  "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 объекта.

{
  "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:

• Используйте указанные названия полей в формах триггерных сообщений 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)

{
  "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)

{
  "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.