Інтеграція квіз-форми з CRM Бітрікс24

Інтеграція квіз-форми з CRM Бітрікс24

Квіз-форма (опитувальник із запитаннями та варіантами відповідей) конвертує краще за звичайну форму заявки, тому що залучає користувача в діалог перед запитом контактних даних. Результати квізу несуть інформацію про потреби клієнта — це цінні дані для менеджера з продажів. Проблема в тому, що більшість квіз-сервісів (Marquiz, Qform, Tilda Quiz) надсилають дані у власну CRM або на email, не інтегруючись нативно з Бітрікс24. Задача — передати відповіді квізу в угоду/лід Бітрікс24 так, щоб менеджер бачив не просто «клієнт заповнив форму», а конкретні відповіді з контекстом.

Підходи до інтеграції

Варіант 1: Webhook від квіз-сервісу → Бітрікс24. Більшість квіз-платформ вміють надсилати webhook при завершенні квізу. Дані надходять на ваш ендпоінт, ви створюєте лід через REST API Бітрікс24.

Варіант 2: Кастомний квіз на сайті → пряма інтеграція з Бітрікс24 REST. Квіз написаний власними силами (React/Vue), останній крок — відправка даних через REST API.

Варіант 3: CRM-форми Бітрікс24 з мультикроком. Вбудований інструмент Бітрікс24, не потребує розробки. Обмежений у кастомізації дизайну.

Розберемо Варіант 1 як найбільш поширений.

Webhook-обробник: Marquiz → Бітрікс24

Marquiz надсилає POST з JSON-пейлоадом при завершенні квізу:

{
  "quiz_id": "abc123",
  "quiz_name": "Підбір вікон",
  "contact": {
    "name": "Іван",
    "phone": "+79161234567",
    "email": "[email protected]"
  },
  "answers": [
    {"question": "Тип приміщення", "answer": "Квартира"},
    {"question": "Кількість вікон", "answer": "3"},
    {"question": "Терміновість", "answer": "Протягом місяця"},
    {"question": "Бюджет", "answer": "50 000 – 100 000 грн"}
  ],
  "result": "Стандартний пакет",
  "utm": {
    "utm_source": "yandex",
    "utm_campaign": "windows_brand"
  }
}

Обробник на стороні вашого сервера (посередник між Marquiz і Бітрікс24):

// /local/api/quiz-webhook.php
require_once($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php');

header('Content-Type: application/json');

$payload = json_decode(file_get_contents('php://input'), true);

// Верифікація по секретному токену в заголовку
$token  = $_SERVER['HTTP_X_QUIZ_TOKEN'] ?? '';
$secret = \Bitrix\Main\Config\Option::get('local.quiz', 'webhook_secret_marquiz');

if (!hash_equals($secret, $token)) {
    http_response_code(403);
    exit(json_encode(['error' => 'Unauthorized']));
}

$integrator = new \Local\Quiz\Bx24Integrator();
$result     = $integrator->createLeadFromQuiz($payload);

echo json_encode(['success' => true, 'lead_id' => $result]);

Створення ліда в Бітрікс24 через REST

namespace Local\Quiz;

use Local\Bx24\RestClient;

class Bx24Integrator
{
    private RestClient $bx24;

    public function __construct()
    {
        // Вхідний вебхук Бітрікс24 з правами crm.lead.add
        $webhookUrl = \Bitrix\Main\Config\Option::get('local.quiz', 'bx24_webhook_url');
        $this->bx24 = new RestClient($webhookUrl);
    }

    public function createLeadFromQuiz(array $data): int
    {
        $contact = $data['contact'] ?? [];
        $answers = $data['answers'] ?? [];

        // Формуємо блок коментаря з відповідями квізу
        $comments = $this->buildQuizComment($data['quiz_name'] ?? '', $answers, $data['result'] ?? '');

        $leadFields = [
            'TITLE'          => ($data['quiz_name'] ?? 'Квіз') . ': ' . ($contact['phone'] ?? ''),
            'NAME'           => $contact['name'] ?? '',
            'PHONE'          => [['VALUE' => $contact['phone'] ?? '', 'VALUE_TYPE' => 'WORK']],
            'EMAIL'          => [['VALUE' => $contact['email'] ?? '', 'VALUE_TYPE' => 'WORK']],
            'SOURCE_ID'      => 'WEB',
            'STATUS_ID'      => 'NEW',
            'COMMENTS'       => $comments,
            'UF_QUIZ_ID'     => $data['quiz_id'] ?? '',
            'UF_QUIZ_RESULT' => $data['result'] ?? '',
            'UF_UTM_SOURCE'  => $data['utm']['utm_source'] ?? '',
            'UF_UTM_CAMPAIGN'=> $data['utm']['utm_campaign'] ?? '',
        ];

        // Додаємо окремі поля під конкретні запитання квізу
        $leadFields = $this->mapAnswersToFields($leadFields, $answers);

        $result = $this->bx24->call('crm.lead.add', ['fields' => $leadFields]);

        $leadId = (int)($result['result'] ?? 0);

        if ($leadId) {
            // Додаємо задачу менеджеру
            $this->bx24->call('crm.activity.add', [
                'fields' => [
                    'TYPE_ID'       => 2, // дзвінок
                    'SUBJECT'       => 'Зателефонувати по квізу: ' . ($contact['phone'] ?? ''),
                    'OWNER_TYPE_ID' => 1, // лід
                    'OWNER_ID'      => $leadId,
                    'DEADLINE'      => date('c', strtotime('+2 hours')),
                ],
            ]);
        }

        return $leadId;
    }

    private function buildQuizComment(string $quizName, array $answers, string $result): string
    {
        $lines = ["=== Квіз: {$quizName} ==="];

        foreach ($answers as $answer) {
            $lines[] = ($answer['question'] ?? '?') . ': ' . ($answer['answer'] ?? '—');
        }

        if ($result) {
            $lines[] = '';
            $lines[] = "Результат квізу: {$result}";
        }

        return implode("\n", $lines);
    }

    private function mapAnswersToFields(array $fields, array $answers): array
    {
        // Маппінг конкретних запитань у користувацькі поля Бітрікс24
        $mapping = [
            'Кількість вікон'   => 'UF_WINDOWS_COUNT',
            'Тип приміщення'    => 'UF_ROOM_TYPE',
            'Бюджет'            => 'UF_BUDGET_RANGE',
            'Терміновість'      => 'UF_URGENCY',
        ];

        foreach ($answers as $answer) {
            $question = $answer['question'] ?? '';
            $fieldCode = $mapping[$question] ?? null;

            if ($fieldCode) {
                $fields[$fieldCode] = $answer['answer'] ?? '';
            }
        }

        return $fields;
    }
}

Кастомні поля в Бітрікс24 для квізу

Поля створюються через REST API або в інтерфейсі Бітрікс24 (CRM → Налаштування → Користувацькі поля):

// Створення користувацького поля для ліда через REST
$this->bx24->call('crm.userfield.add', [
    'fields' => [
        'ENTITY_ID'   => 'CRM_LEAD',
        'FIELD_NAME'  => 'UF_QUIZ_RESULT',
        'USER_TYPE_ID'=> 'string',
        'XML_ID'      => 'QUIZ_RESULT',
        'EDIT_FORM_LABEL' => ['ru' => 'Результат квиза'],
        'LIST_COLUMN_LABEL' => ['ru' => 'Результат квиза'],
        'MANDATORY'   => 'N',
    ],
]);

Інтеграція через CRM-форму Бітрікс24

Якщо квіз розробляється з нуля — альтернативний підхід: CRM-форма Бітрікс24 з прихованими полями. Останній крок квізу надсилає дані напряму у форму через API:

// Фінальний крок квізу: надсилаємо дані в CRM-форму Бітрікс24
async function submitQuizToBx24(answers, contact) {
    const formData = new FormData();

    // Поля CRM-форми
    formData.append('fields[NAME]', contact.name);
    formData.append('fields[PHONE][0][VALUE]', contact.phone);
    formData.append('fields[UF_QUIZ_RESULT]', getQuizResult(answers));
    formData.append('fields[COMMENTS]', formatAnswers(answers));

    // ID форми з налаштувань Бітрікс24
    const formId = document.getElementById('quiz-container').dataset.bx24FormId;

    await fetch(`https://your-domain.bitrix24.ru/crm/webform/import/form/${formId}/`, {
        method: 'POST',
        body: formData,
    });
}

Склад робіт

• Webhook-обробник для квіз-сервісу (Marquiz, Qform або кастомний)
• Клієнт Бітрікс24 REST API: створення лідів, активностей
• Створення користувацьких полів під відповіді квізу
• Маппінг запитань квізу → поля CRM
• Формування структурованого коментаря з відповідями
• Передача UTM-міток у поля ліда
• Тестування сценарію: заповнення квізу → картка ліда в Бітрікс24

Терміни: інтеграція одного квіз-сервісу через webhook — 3–7 днів. Повна схема з кастомними полями та кількома квізами — 1–2 тижні.