Налаштування автоматичного імпорту лідів з VK Ads до Бітрікс24

Налаштування автоматичного імпорту лідів з VK Ads у Бітрікс24

VK Lead Ads — основний інструмент лідогенерації ВКонтакте для B2C-сегменту. На відміну від Facebook, VK надає кілька механізмів отримання лідів: вебхуки через VK Callback API, Leads API для опитування та пряму інтеграцію через сервіс VK Міні-застосунків. Для автоматичного потрапляння лідів у Бітрікс24 оптимальний вебхук через Callback API.

VK Callback API для лід-форм

У налаштуваннях спільноти ВКонтакте: «Управління → Робота з API → Callback API» — додається сервер з URL обробника.

Верифікація сервера:

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

// Підтвердження сервера
if ($data['type'] === 'confirmation') {
    echo VK_CONFIRMATION_STRING; // рядок з налаштувань Callback API
    exit;
}

// Верифікація підпису
if ($data['secret'] !== VK_CALLBACK_SECRET) {
    http_response_code(403);
    exit;
}

Обробка нового ліда (подія lead_forms_new):

if ($data['type'] === 'lead_forms_new') {
    $lead = $data['object'];

    $leadId   = $lead['lead_id'];
    $formId   = $lead['form_id'];
    $groupId  = $lead['group_id'];
    $userId   = $lead['user_id'];
    $adId     = $lead['ad_id']       ?? '';
    $utmData  = $lead['utm']         ?? [];

    // Відповіді на поля форми
    $answers = $lead['answers'] ?? [];
    $fields  = [];
    foreach ($answers as $answer) {
        $fields[$answer['key']] = $answer['answer'] ?? '';
    }

    // Створюємо лід у Бітрікс24
    $this->createBitrix24Lead($leadId, $formId, $fields, $utmData, $adId);

    echo 'ok'; // VK очікує рядок 'ok' у відповіді
    exit;
}

Отримання повних даних через Leads API

Callback API для лід-форм передає відповіді користувача безпосередньо в answers. Проте для отримання даних про самого користувача (ім'я, телефон з профілю, якщо він дав дозвіл) — потрібен додатковий запит до VK API:

public function enrichLeadWithUserData(int $userId, string $accessToken): array
{
    $response = $this->vkApi->call('users.get', [
        'user_ids' => $userId,
        'fields'   => 'photo_100,city',
    ]);

    $user = $response['response'][0] ?? [];
    return [
        'first_name' => $user['first_name'] ?? '',
        'last_name'  => $user['last_name']  ?? '',
        'vk_profile' => "https://vk.com/id{$userId}",
    ];
}

Маппінг полів VK Lead Forms у Бітрікс24

VK використовує стандартні ключі для типових полів: first, last, name, phone, email. Кастомні питання мають довільні ключі, задані при створенні форми.

public function createBitrix24Lead(
    string $vkLeadId,
    int    $formId,
    array  $fields,
    array  $utm,
    string $adId
): void {
    // Стандартні поля
    $name  = trim(($fields['first'] ?? '') . ' ' . ($fields['last'] ?? ''))
          ?: ($fields['name'] ?? 'Лід з VK');
    $phone = $fields['phone'] ?? '';
    $email = $fields['email'] ?? '';

    $b24Fields = [
        'TITLE'             => 'VK Lead Ads: ' . date('d.m.Y H:i'),
        'NAME'              => $name,
        'PHONE'             => [['VALUE' => $phone, 'VALUE_TYPE' => 'MOBILE']],
        'EMAIL'             => [['VALUE' => $email, 'VALUE_TYPE' => 'WORK']],
        'SOURCE_ID'         => 'ADVERTISING',
        'SOURCE_DESCRIPTION' => 'VK Lead Ads',
        'UF_CRM_VK_LEAD_ID' => $vkLeadId,
        'UF_CRM_VK_FORM_ID' => $formId,
        'UF_CRM_VK_AD_ID'   => $adId,
        'UF_CRM_UTM_SOURCE'   => $utm['source']   ?? 'vk',
        'UF_CRM_UTM_CAMPAIGN' => $utm['campaign'] ?? '',
        'UF_CRM_UTM_MEDIUM'   => $utm['medium']   ?? 'cpc',
    ];

    // Кастомні поля форми — у коментар
    $customFields = array_diff_key($fields, array_flip(['first','last','name','phone','email']));
    if (!empty($customFields)) {
        $b24Fields['COMMENTS'] = implode("\n", array_map(
            fn($k, $v) => "{$k}: {$v}",
            array_keys($customFields),
            array_values($customFields)
        ));
    }

    $this->b24->call('crm.lead.add', [
        'FIELDS' => $b24Fields,
        'PARAMS' => ['REGISTER_SONET_EVENT' => 'Y'],
    ]);
}

Кілька спільнот і форм

Якщо компанія веде кілька спільнот ВКонтакте або використовує безліч лід-форм під різні продукти — кожному group_id та form_id можна зіставити конкретну воронку та відповідального в Бітрікс24:

$routingConfig = [
    ['group_id' => 123456, 'form_id' => 111, 'pipeline_id' => 1, 'assigned_by' => 5],
    ['group_id' => 123456, 'form_id' => 222, 'pipeline_id' => 3, 'assigned_by' => 8],
    ['group_id' => 789012, 'form_id' => 333, 'pipeline_id' => 2, 'assigned_by' => 11],
];

Конфігурація зберігається у таблиці або JSON-файлі, оновлюється без деплою.

Дедублікація та перевірка за телефоном

ВКонтакте користувачі іноді надсилають форму кілька разів. Дедублікація — за vk_lead_id (унікальний ID у VK), який зберігаємо у користувацькому полі. Перед створенням:

$existing = $this->b24->call('crm.lead.list', [
    'filter' => ['UF_CRM_VK_LEAD_ID' => $vkLeadId],
]);
if (!empty($existing)) return; // вже створено

Склад робіт

• Налаштування Callback API у спільноті ВКонтакте
• Розробка обробника: верифікація, маппінг полів, створення ліда
• Користувацькі поля в Б24 для VK-атрибутів
• Routing config для кількох спільнот/форм
• Дедублікація за vk_lead_id та телефоном
• Журналювання помилок, моніторинг доставки вебхуків

Терміни: 3–5 днів для однієї спільноти. До 2 тижнів при складному роутингу та великій кількості форм.