Настройка автоматического импорта лидов из 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 permissions
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 ОК в течение 20 секунд

Получение данных лида через Graph API

Webhook передаёт только 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.