Розробка бота для Facebook Messenger з інтеграцією Бітрікс24

Розробка бота для Facebook Messenger з інтеграцією Bitrix24

Facebook Messenger — робочий канал залучення клієнтів для бізнесу, орієнтованого на міжнародну аудиторію або працюючого з Facebook Ads. Бот отримує звернення в Messenger, кваліфікує їх за сценарієм та створює лідів у Bitrix24. Менеджер відповідає клієнту з карточки CRM — немає потреби переключатися між вкладками.

Технічні основи: Messenger Platform API

Meta надає Messenger Platform API для автоматизації роботи з повідомленнями сторінки. Потік даних:

Клієнт → Facebook Page Messenger
              ↓
        Meta Webhook → POST на сервер бота
              ↓
        Сервер бота → Messenger Send API
                   → Bitrix24 REST API

Потрібні:

• Facebook Developer App з продуктом Messenger.
• Сторінка Facebook (Page), прив'язана до додатку.
• PAGE_ACCESS_TOKEN — довгоживучий токен сторінки.
• Верифікація webhook через verify_token.

Верифікація та прийом webhook

Meta перед активацією webhook відправляє GET-запит для верифікації:

GET /webhook?hub.mode=subscribe&hub.verify_token=MY_TOKEN&hub.challenge=CHALLENGE_CODE

Сервер перевіряє verify_token та повертає hub.challenge.

Вхідні повідомлення приходять як POST:

{
  "entry": [{
    "messaging": [{
      "sender": { "id": "123456789" },
      "recipient": { "id": "PAGE_ID" },
      "message": {
        "mid": "m_abc123",
        "text": "Привіт, цікавить ваш продукт"
      }
    }]
  }]
}

Важливо: Meta очікує відповідь 200 OK протягом 5 секунд, інакше починає повторні спроби. Важку обробку (запити до Б24) виносимо в чергу.

Відправлення повідомлень

function sendMessengerMessage(string $psid, string $text, array $quickReplies = []): void {
    $payload = [
        'recipient' => ['id' => $psid],
        'message'   => ['text' => $text],
    ];

    if ($quickReplies) {
        $payload['message']['quick_replies'] = $quickReplies;
    }

    $ch = curl_init("https://graph.facebook.com/v18.0/me/messages?access_token=" . PAGE_ACCESS_TOKEN);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
    curl_exec($ch);
}

// Швидкі відповіді (кнопки-підказки)
$quickReplies = [
    ['content_type' => 'text', 'title' => 'Так, цікавить',  'payload' => 'INTERESTED'],
    ['content_type' => 'text', 'title' => 'Просто дивлюся', 'payload' => 'BROWSING'],
];
sendMessengerMessage($psid, 'Допомогти з вибором?', $quickReplies);

Generic Template для карточок товарів

Messenger підтримує структуровані повідомлення — каруселі з зображеннями, кнопками, посиланнями:

$template = [
    'recipient' => ['id' => $psid],
    'message'   => [
        'attachment' => [
            'type'    => 'template',
            'payload' => [
                'template_type' => 'generic',
                'elements'      => [[
                    'title'     => $productName,
                    'image_url' => $productImage,
                    'subtitle'  => $productDescription,
                    'buttons'   => [
                        ['type' => 'web_url',  'url' => $productUrl, 'title' => 'Детальніше'],
                        ['type' => 'postback', 'title' => 'Замовити', 'payload' => "ORDER_{$productId}"],
                    ],
                ]],
            ],
        ],
    ],
];

Отримання профілю користувача

Facebook дозволяє запросити ім'я та аватар користувача за PSID:

$profile = json_decode(file_get_contents(
    "https://graph.facebook.com/{$psid}?fields=first_name,last_name,profile_pic&access_token=" . PAGE_ACCESS_TOKEN
), true);

Ці дані заповнюють поля ліда в Bitrix24: NAME, LAST_NAME, UF_FB_PSID.

Створення ліда в Bitrix24 та збереження діалогу

$leadId = $b24->callMethod('crm.lead.add', [
    'fields' => [
        'TITLE'          => "Messenger: {$firstName} {$lastName}",
        'NAME'           => $firstName,
        'LAST_NAME'      => $lastName,
        'SOURCE_ID'      => 'WEBFORM',
        'SOURCE_DESCRIPTION' => 'Facebook Messenger',
        'UF_CRM_FB_PSID' => $psid,
        'COMMENTS'       => "Facebook Profile ID: {$psid}",
    ],
])['result'];

// Зберігаємо кожне повідомлення як активність
$b24->callMethod('crm.activity.add', [
    'fields' => [
        'OWNER_TYPE_ID' => 1,
        'OWNER_ID'      => $leadId,
        'TYPE_ID'       => 4,
        'SUBJECT'       => 'Повідомлення Facebook Messenger',
        'DESCRIPTION'   => "{$firstName}: {$messageText}",
        'DEADLINE'      => date('Y-m-d\TH:i:s'),
    ],
]);

Handoff Protocol: передача живому оператору

Коли клієнт хоче поговорити з менеджером, бот передає управління через Handoff Protocol (pass_thread_control). За наявності Inbox або LiveChat-інтеграції оператор перебирає діалог. Після завершення діалог повертається до бота через take_thread_control.

Обмеження та вимоги Meta

• Бот повинен відповісти клієнту протягом 24 годин після останнього повідомлення (стандартне вікно). За межами вікна — лише затверджені шаблони повідомлень (Message Tags).
• HTTPS обов'язковий для webhook.
• Додаток проходить ревью Meta перед запуском публічно (pages_messaging permission).
• Політика конфіденційності та обробки даних — обов'язкова вимога Meta при ревью.

Строки

Разом: 2–3 тижні з урахуванням ревью Meta (займає до 5 робочих днів).