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

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

Facebook Lead Ads — один з основних каналів лідогенерації для B2C-сегменту. Заповнена форма залишається у Facebook Lead Center або вивантажується через Webhook, але в CRM не потрапляє автоматично. Ручний експорт CSV раз на день — втрата швидкості реакції, а швидкість реакції на лід критична: через 5 хвилин шанси додзвонитися падають у 10 разів, за даними досліджень LeadResponseManagement.

Технічний механізм

Facebook надає Lead Gen Webhooks — push-сповіщення про нові ліди в реальному часі. Це кращий варіант: затримка не більше 1–2 секунд від моменту відправки форми.

Налаштування вебхука:

1. У Facebook Developers створити застосунок, підключити дозволи leads_retrieval та pages_manage_metadata
2. У налаштуваннях вебхука вказати URL та Verify Token
3. Підписатися на подію leadgen для потрібної сторінки

Верифікація вебхука Facebook (GET-запит):

// Початкова верифікація endpoint'а
if ($_GET['hub_mode'] === 'subscribe' &&
    $_GET['hub_verify_token'] === FB_VERIFY_TOKEN) {
    echo $_GET['hub_challenge'];
    exit;
}

Обробка вхідного ліда (POST-запит):

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

// Верифікація підпису
$signature = 'sha256=' . hash_hmac('sha256',
    file_get_contents('php://input'),
    FB_APP_SECRET
);
if ($signature !== $_SERVER['HTTP_X_HUB_SIGNATURE_256']) {
    http_response_code(403);
    exit;
}

foreach ($payload['entry'] as $entry) {
    foreach ($entry['changes'] as $change) {
        if ($change['field'] === 'leadgen') {
            $leadgenId = $change['value']['leadgen_id'];
            $formId    = $change['value']['form_id'];
            $adId      = $change['value']['ad_id'];
            $campaignId = $change['value']['campaign_id'];

            // Отримуємо повні дані ліда через Graph API
            $leadData = $this->getLeadData($leadgenId);

            // Створюємо в Бітрікс24
            $this->createBitrix24Lead($leadData, [
                'ad_id'       => $adId,
                'campaign_id' => $campaignId,
                'form_id'     => $formId,
            ]);
        }
    }
}

http_response_code(200); // Facebook вимагає 200 OK протягом 20 секунд

Отримання даних ліда через Graph API

Вебхук передає лише leadgen_id. Повні дані потрібно запросити окремо:

public function getLeadData(string $leadgenId): array
{
    $response = $this->fbGraph->get(
        "/{$leadgenId}?fields=field_data,created_time,ad_id,form_id",
        $this->pageAccessToken
    );

    $lead = $response->getDecodedBody();
    $fields = [];

    foreach ($lead['field_data'] as $field) {
        $fields[$field['name']] = $field['values'][0] ?? '';
    }

    return [
        'name'        => $fields['full_name']   ?? $fields['first_name'] . ' ' . $fields['last_name'],
        'phone'       => $fields['phone_number'] ?? $fields['phone'] ?? '',
        'email'       => $fields['email']        ?? '',
        'custom'      => $fields, // усі поля форми
        'created_at'  => $lead['created_time'],
    ];
}

Назви полів у Facebook Lead Ads залежать від налаштування форми — стандартні поля називаються full_name, email, phone_number, кастомні — довільно. Маппінг потрібно налаштовувати під кожну форму.

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

public function createBitrix24Lead(array $leadData, array $fbMeta): void
{
    $fields = [
        'TITLE'      => 'Facebook Lead Ads: ' . date('d.m.Y H:i'),
        'NAME'       => $leadData['name'],
        'PHONE'      => [['VALUE' => $leadData['phone'], 'VALUE_TYPE' => 'WORK']],
        'EMAIL'      => [['VALUE' => $leadData['email'], 'VALUE_TYPE' => 'WORK']],
        'SOURCE_ID'  => 'WEB',
        'SOURCE_DESCRIPTION' => 'Facebook Lead Ads',
        'UF_CRM_FB_AD_ID'       => $fbMeta['ad_id'],
        'UF_CRM_FB_CAMPAIGN_ID' => $fbMeta['campaign_id'],
        'UF_CRM_FB_FORM_ID'     => $fbMeta['form_id'],
        'UF_CRM_FB_LEAD_TIME'   => $leadData['created_at'],
    ];

    // Додаємо кастомні поля форми в коментар
    if (!empty($leadData['custom'])) {
        $customText = implode("\n", array_map(
            fn($k, $v) => "{$k}: {$v}",
            array_keys($leadData['custom']),
            array_values($leadData['custom'])
        ));
        $fields['COMMENTS'] = $customText;
    }

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

Резервний polling через API

Вебхуки Facebook іноді не доставляються (збої, таймаути). Резервний механізм — polling кожні 30 хвилин через GET /{page_id}/leadgen_forms/{form_id}/leads?since={timestamp}.

Склад робіт

• Створення Facebook App, налаштування дозволів leads_retrieval
• Налаштування вебхука Lead Ads для сторінок
• Розробка обробника: верифікація, Graph API, маппінг полів
• Користувацькі поля в Б24 для Facebook-атрибутів
• Дедублікація за телефоном/email
• Резервний polling, журналювання помилок

Терміни: 1–2 тижні з урахуванням проходження модерації Facebook App.