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

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

Facebook Messenger — рабочий канал привлечения клиентов для бизнеса, ориентированного на международную аудиторию или работающего с Facebook Ads. Бот принимает обращения в Messenger, квалифицирует их по сценарию и создаёт лиды в Битрикс24. Менеджер отвечает клиенту из карточки CRM — переключаться между вкладками не нужно.

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

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

Клиент → Facebook Page Messenger
              ↓
        Meta Webhook → POST на сервер бота
              ↓
        Сервер бота → Messenger Send API
                   → Битрикс24 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);

Эти данные заполняют поля лида в Битрикс24: NAME, LAST_NAME, UF_FB_PSID.

Создание лида в Битрикс24 и сохранение диалога

$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 рабочих дней).