Интеграция Telegram-бота с Битрикс24: Полное пошаговое руководство

Ваш менеджер снова пропустил заявку в Telegram? Клиент написал в бота, а ответ получил только на следующий день, когда уже нашел конкурентов? Если эти ситуации вам знакомы, вы теряете не просто сообщения — вы теряете деньги. В современном бизнесе скорость реакции решает все, а ручная обработка заявок из мессенджеров — прямой путь к упущенной прибыли.

Решение есть, и оно мощнее, чем вы думаете. Это прямая интеграция вашего Telegram-бота с CRM-системой Битрикс24. Забудьте о копировании данных вручную, потерянных диалогах и несвоевременных ответах. Правильная настройка превращает вашего бота из простого автоответчика в неутомимого сотрудника, который мгновенно фиксирует каждую заявку, создает лиды, ставит задачи менеджерам и двигает клиентов по воронке продаж 24/7.

Это не магия, а технология, доступная каждому. В этом полном руководстве мы пошагово, простым и понятным языком, разберем весь процесс:

  • Создадим Telegram-бота и получим его уникальный токен.
  • Настроим вебхук (webhook) — мост между Telegram и вашей системой.
  • Подготовим Битрикс24 к приему данных через REST API.
  • Напишем и разберем скрипт-обработчик, который будет создавать лиды, контакты и сделки.
  • Рассмотрим сценарии автоматизации: от приветственного сообщения до смены стадии сделки после оплаты.
  • Научимся обрабатывать ошибки, чтобы ваша система работала как часы.

Это руководство — ваша инвестиция в эффективность. Прочитав его, вы сможете либо самостоятельно реализовать интеграцию, либо четко поставить задачу разработчику, сэкономив время и бюджет. Давайте начнем автоматизировать ваш бизнес!

Зачем вашему бизнесу нужна интеграция Telegram и Битрикс24?

На первый взгляд, можно просто добавить менеджеров в Telegram и попросить их переносить заявки в CRM. Но на практике этот подход не выдерживает критики и приводит к системным проблемам. Давайте разберемся, какие конкретные преимущества дает автоматизированная связка.

  • Скорость обработки заявок x10. Заявка, оставленная в 2 часа ночи, не будет ждать утра. Бот мгновенно отправит ее в Битрикс24, где будет создан лид и поставлена задача первому освободившемуся менеджеру. Клиент получает быструю реакцию, а вы — конкурентное преимущество.
  • Исключение человеческого фактора. Менеджер может забыть, отвлечься, неправильно скопировать номер телефона. Автоматика работает без ошибок. Каждая заявка, каждое сообщение будет зафиксировано в карточке клиента, создавая полную и достоверную историю взаимодействия.
  • Централизация всех каналов коммуникации. Вся переписка с клиентом из Telegram автоматически подгружается в таймлайн его карточки в Битрикс24. Любой сотрудник с доступом сможет быстро войти в курс дела, не спрашивая коллегу: “А о чем вы с ним договаривались?”.
  • Автоматизация воронки продаж. Интеграция — это не только про создание лидов. Это про автоматическое движение по воронке. Клиент нажал кнопку “Узнать цену” в боте? В сделке автоматически сменилась стадия. Клиент оплатил заказ через интегрированный сервис? Сделка автоматически закрывается как успешная, а клиенту уходит благодарственное сообщение.
  • Сбор и аналитика данных. Когда все заявки проходят через CRM, вы получаете бесценные данные для анализа: какой канал приносит больше всего лидов? На каком этапе “отваливаются” клиенты? Как быстро менеджеры реагируют на новые обращения? Эти данные — основа для принятия верных управленческих решений.

По сути, интеграция Telegram-бота с CRM — это переход от хаотичного управления заявками к выстроенной, прогнозируемой и масштабируемой системе продаж.

Как это работает? Принцип связи Telegram-бота и CRM

Чтобы понимать, что мы будем делать дальше, важно разобраться в базовом принципе работы этой связки. Представьте себе двух собеседников, говорящих на разных языках (Telegram и Битрикс24), и переводчика между ними. Наша задача — создать этого “переводчика”.

В этой схеме участвуют три ключевых компонента:

  1. Серверы Telegram. Когда пользователь пишет что-то вашему боту, Telegram фиксирует это событие (новое сообщение, нажатие кнопки и т.д.).
  2. Ваш скрипт-обработчик (переводчик). Это PHP-файл (или написанный на другом языке), который лежит на вашем хостинге или сервере. Его главная задача — получать информацию от Telegram, “переводить” ее на язык, понятный Битрикс24, и отправлять туда.
  3. Серверы Битрикс24 (CRM). Ваша CRM-система, которая имеет свой собственный “язык” для общения с внешним миром — REST API. Она умеет принимать команды вроде “создай новый лид с таким-то именем и телефоном”.

А как Telegram узнает, куда именно отправлять информацию о новом сообщении? Для этого существует Webhook (вебхук).

Webhook — это механизм уведомления. Мы “говорим” Telegram: “Эй, как только кто-то напишет моему боту, пожалуйста, немедленно отправь всю информацию об этом сообщении вот по этому URL-адресу”. Этим URL-адресом и будет путь к нашему скрипту-обработчику.

Процесс выглядит так:

  1. Клиент пишет сообщение в ваш Telegram-бот.
  2. Telegram видит это и отправляет HTTP-запрос (POST) с данными о сообщении (текст, ID чата, информация о пользователе) на URL вашего вебхука.
  3. Ваш скрипт-обработчик, находящийся по этому URL, получает запрос.
  4. Скрипт анализирует полученные данные (JSON-объект).
  5. Далее скрипт формирует новый запрос, но уже к REST API Битрикс24, с командой, например, crm.lead.add и данными клиента.
  6. Битрикс24 получает команду, исполняет ее (создает лид) и отправляет ответ об успешном выполнении обратно на ваш скрипт.

Теперь, когда теория ясна, перейдем к практике.

Шаг 1: Подготовка. Что понадобится для интеграции?

Прежде чем писать код и нажимать на кнопки, убедитесь, что у вас есть все необходимое. Это сэкономит массу времени.

  • Права администратора в вашем портале Битрикс24. Без них вы не сможете создавать вебхуки и настраивать API. Подойдет любой коммерческий тариф Битрикс24 (включая “Базовый”) или коробочная версия.
  • Аккаунт в Telegram. Очевидно, но все же.
  • Хостинг с поддержкой PHP и SSL-сертификата.
    • PHP: Наш скрипт-обработчик будет написан на PHP, самом распространенном языке для веб-разработки. Подойдет практически любой современный хостинг.
    • SSL-сертификат (HTTPS): Это критически важно. Telegram не будет отправлять данные на незащищенные адреса (http://). Ваш сайт, где будет лежать скрипт, должен быть доступен по адресу, начинающемуся с https://. Большинство хостинг-провайдеров сегодня предоставляют бесплатные SSL-сертификаты от Let’s Encrypt.
  • Базовое понимание структуры данных (JSON). Мы будем постоянно работать с данными в формате JSON. Это простой текстовый формат для обмена информацией, и понимание его структуры “ключ-значение” сильно облегчит вам жизнь.
  • Текстовый редактор. Подойдет любой, от простого “Блокнота” до продвинутых редакторов кода вроде VS Code или Sublime Text.

Если все пункты выполнены, можно приступать к созданию бота.

Шаг 2: Создание и настройка Telegram-бота

Этот этап полностью проходит внутри Telegram. Наша цель — зарегистрировать нового бота и получить его уникальный “паспорт” — токен.

Создаем бота через @BotFather

@BotFather — это официальный бот от Telegram, который управляет всеми остальными ботами.

  1. Найдите @BotFather в поиске Telegram (у него синяя галочка верификации) и начните с ним диалог, нажав “Start”.
  2. Отправьте команду /newbot. BotFather попросит вас придумать имя для вашего бота. Это имя, которое пользователи будут видеть в списке контактов. Например, Мой Тестовый Магазин.
  3. Придумайте уникальный username для бота. Это его техническое имя, по которому его можно будет найти. Оно должно быть уникальным во всем Telegram и обязательно заканчиваться на bot. Например, MyTestShopBot или moy_test_shop_bot.
  4. Получите токен! Если username не занят, BotFather поздравит вас с созданием бота и пришлет сообщение, содержащее токен. Это длинная строка из букв и цифр, разделенная двоеточием. Пример: 1234567890:AAH_AbcDeFgHiJkLmNoPqRsTuVwXyZ.

Важно! Токен — это ключ к вашему боту. Не сообщайте его никому и не публикуйте в открытом доступе. Тот, у кого есть токен, может полностью управлять вашим ботом. Сохраните его в надежном месте, он нам скоро понадобится.

Что такое Webhook и как его установить?

Теперь нам нужно сообщить Telegram, куда отправлять обновления. Для этого мы установим вебхук. Сделать это можно, отправив специальный запрос к Telegram Bot API.

Формат запроса для установки вебхука выглядит так:

https://api.telegram.org/bot<ВАШ_ТОКЕН>/setWebhook?url=<URL_ВАШЕГО_СКРИПТА>

Давайте разберем его:

  • <ВАШ_ТОКЕН>: сюда нужно подставить тот самый токен, который вы получили от @BotFather.
  • <URL_ВАШЕГО_СКРИПТА>: это полный HTTPS-адрес, по которому будет доступен ваш PHP-файл-обработчик. Например: https://vash-site.ru/telegram_handler.php.

Как это сделать на практике?

  1. Пока у нас нет готового скрипта, мы можем просто создать пустой файл telegram_handler.php и загрузить его на ваш хостинг в корневую папку сайта.
  2. Сформируйте полную ссылку для установки вебхука, подставив свои данные.
  3. Самый простой способ отправить этот запрос — просто вставить получившуюся ссылку в адресную строку вашего браузера и нажать Enter.

Если все правильно, вы увидите ответ в формате JSON: {"ok":true,"result":true,"description":"Webhook was set"}

Это значит, что Telegram успешно “запомнил” адрес вашего обработчика. Чтобы проверить статус или удалить вебхук, можно использовать команду getWebhookInfo:

https://api.telegram.org/bot<ВАШ_ТОКЕН>/getWebhookInfo

Шаг 3: Настройка на стороне Битрикс24: Входящий вебхук

Теперь подготовим “принимающую сторону”. Нам нужно создать в Битрикс24 специальную точку входа, которая будет слушать команды от нашего скрипта. Эта точка входа называется входящий вебхук.

  1. Зайдите в ваш портал Битрикс24 с правами администратора.

  2. В левом меню найдите раздел “Разработчикам” или воспользуйтесь глобальным поиском вверху страницы. В выпадающем списке выберите “Другое” -> “Вебхуки”.

  3. Нажмите на кнопку “Добавить вебхук” и выберите “Входящий вебхук”.

  4. Откроется окно настройки. Здесь самое важное — настроить права доступа. Вы должны дать этому вебхуку разрешение только на те действия, которые ему необходимы. Для нашей задачи это, в первую очередь, “CRM”. Поставьте галочку напротив этого пункта.

  5. Нажмите “Сохранить”. Система сгенерирует для вас уникальный URL. Он будет выглядеть примерно так: https://vash-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/

    • vash-portal.bitrix24.ru: адрес вашего портала.
    • 1: ID пользователя, который создал вебхук.
    • xxxxxxxxxxxxxxxx: секретный код авторизации.

Сохраните эту ссылку! Это ваш ключ доступа к API Битрикс24. Любой, у кого есть эта ссылка, сможет выполнять действия в вашей CRM от имени пользователя, создавшего вебхук.

К этому URL мы будем добавлять названия методов API, которые хотим выполнить. Например, чтобы создать лид, итоговый запрос будет отправляться на адрес: https://vash-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/crm.lead.add.json

Шаг 4: “Магия” синхронизации: Пишем скрипт-обработчик

Настало время для самого интересного — создания того самого “переводчика”. Мы напишем PHP-скрипт, который будет лежать по адресу, указанному в вебхуке Telegram.

Базовая структура скрипта (telegram_handler.php)

Вот основа, с которой мы начнем. Этот код получает данные от Telegram, декодирует их и записывает в лог-файл для отладки.

<?php
// Ваш секретный токен от @BotFather
define('TELEGRAM_TOKEN', '1234567890:AAH_AbcDeFgHiJkLmNoPqRsTuVwXyZ');

// URL вашего входящего вебхука в Битрикс24
define('BITRIX_WEBHOOK_URL', 'https://vash-portal.bitrix24.ru/rest/1/xxxxxxxxxxxxxxxx/');

// --- Получаем данные от Telegram ---
$request_data = file_get_contents('php://input');
$data = json_decode($request_data, true);

// --- Логирование для отладки ---
// Записываем все, что пришло от Telegram, в файл. Помогает понять структуру данных.
file_put_contents('telegram_log.txt', print_r($data, true), FILE_APPEND);

// Проверяем, есть ли в данных сообщение
if (isset($data['message'])) {
    $message = $data['message'];
    $chat_id = $message['chat']['id'];
    $text = $message['text'];
    $first_name = $message['from']['first_name'];
    $last_name = $message['from']['last_name'] ?? ''; // Фамилия может отсутствовать
    $username = $message['from']['username'] ?? 'N/A'; // Username тоже

    // Дальше будет логика обработки...
}

// Отвечаем Telegram, что все ОК, чтобы он не слал запрос повторно
http_response_code(200);
?>

Что здесь происходит?

  1. Мы определяем константы с токеном и URL вебхука Битрикс24. Это хорошая практика, чтобы не “разбрасывать” их по коду.
  2. file_get_contents('php://input') — эта команда читает “сырые” данные, которые Telegram прислал в теле POST-запроса.
  3. json_decode() — превращает строку JSON в понятный для PHP массив.
  4. file_put_contents() — очень полезная функция для отладки. Она создает файл telegram_log.txt рядом со скриптом и записывает в него все, что пришло. Если что-то не работает, первый шаг — посмотреть в этот лог.
  5. Мы извлекаем из массива ключевые данные: ID чата (чтобы знать, кому отвечать), текст сообщения и информацию о пользователе.
  6. http_response_code(200) — обязательно отвечаем серверу Telegram кодом “200 OK”, иначе он решит, что доставка не удалась, и будет пытаться отправить тот же запрос снова и снова.

Логика 1: Создание нового лида из сообщения в боте

Это самый частый сценарий. Пользователь впервые пишет боту. Наша задача — создать в Битрикс24 новый лид.

Дополним наш скрипт. Внутри блока if (isset($data['message'])) добавим код для отправки запроса в Битрикс24.

// ... (код из предыдущего блока) ...

if (isset($data['message'])) {
    // ... (извлечение данных) ...

    // --- Логика создания лида в Битрикс24 ---
    
    // Формируем данные для нового лида
    $lead_data = [
        'fields' => [
            'TITLE' => 'Заявка из Telegram-бота от ' . $first_name,
            'NAME' => $first_name,
            'LAST_NAME' => $last_name,
            'STATUS_ID' => 'NEW', // Статус "Новый"
            'OPENED' => 'Y', // Открыт для всех
            'ASSIGNED_BY_ID' => 1, // ID ответственного менеджера (1 - обычно администратор)
            'SOURCE_ID' => 'TELEGRAM', // Указываем источник
            // Добавляем контактные данные
            'PHONE' => [ ['VALUE' => 'Не указан', 'VALUE_TYPE' => 'WORK'] ], // Заглушка, если номера нет
            'UF_CRM_1605885422' => $username, // Пример: записываем username в пользовательское поле
        ],
        'params' => ['REGISTER_SONET_EVENT' => 'Y'] // Чтобы появилось уведомление в "живой ленте"
    ];

    // Вызываем функцию для отправки запроса
    callBitrixAPI('crm.lead.add', $lead_data);
}

// --- Функция для отправки запросов в Битрикс24 ---
function callBitrixAPI($method, $params) {
    $query_url = BITRIX_WEBHOOK_URL . $method . '.json';
    $query_data = http_build_query($params);

    $curl = curl_init();
    curl_setopt_array($curl, [
        CURLOPT_SSL_VERIFYPEER => 0,
        CURLOPT_POST => 1,
        CURLOPT_HEADER => 0,
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_URL => $query_url,
        CURLOPT_POSTFIELDS => $query_data,
    ]);

    $result = curl_exec($curl);
    curl_close($curl);

    // Можно добавить логирование ответа от Битрикс24
    file_put_contents('bitrix_log.txt', print_r(json_decode($result, true), true), FILE_APPEND);
    
    return json_decode($result, true);
}

// ... (код с http_response_code(200)) ...

Разбор кода:

  • Мы создали отдельную функцию callBitrixAPI(), чтобы не дублировать код отправки запросов. Она принимает на вход метод API (crm.lead.add) и параметры.
  • Внутри функции мы используем библиотеку cURL — стандартный способ для PHP отправлять HTTP-запросы.
  • Мы формируем массив $lead_data в точном соответствии с документацией Битрикс24 REST API для метода crm.lead.add.
    • TITLE — обязательное поле, заголовок лида.
    • NAME, LAST_NAME — имя и фамилия.
    • ASSIGNED_BY_ID — ID пользователя, на которого будет назначен лид. Важно: укажите здесь ID реального сотрудника.
    • SOURCE_ID — источник. Рекомендую заранее создать в настройках CRM источник “TELEGRAM”, чтобы потом фильтровать заявки.
    • UF_CRM_... — так выглядят пользовательские поля. Вы можете создать в Битрикс24 поле для хранения Telegram username и подставить сюда его код.

Теперь, когда пользователь напишет вашему боту, в Битрикс24 автоматически появится новый лид!

Логика 2: Связь существующих контактов и обновление данных

Что если пользователь пишет нам не в первый раз? Создавать каждый раз новый лид — плохая идея. Нужно найти существующий контакт или лид и добавить новое сообщение в его историю.

Для этого нам нужно:

  1. При первом контакте сохранить связь между chat_id из Telegram и ID лида/контакта из Битрикс24. Эту связь можно хранить в базе данных на вашем хостинге или даже в пользовательском поле самого Битрикс24.
  2. При последующих сообщениях сначала проверять, есть ли у нас запись для данного chat_id.
  3. Если есть, то не создавать новый лид, а добавлять комментарий к существующей сущности с помощью метода crm.timeline.comment.add.

Это более сложная логика, которая требует работы с базой данных, но она является ключом к построению качественной истории общения.

Логика 3: Автоматизация сделок (например, после оплаты)

Представьте, что в вашем боте есть кнопка “Оплатить”, которая ведет на страницу платежной системы. После успешной оплаты платежная система может отправить уведомление (тоже через вебхук) на другой ваш скрипт.

Этот скрипт, получив уведомление об оплате и ID заказа:

  1. Находит по ID заказа соответствующую сделку в Битрикс24 (метод crm.deal.list с фильтром).
  2. Меняет ее стадию на “Оплачено” с помощью метода crm.deal.update.
  3. Отправляет через Telegram Bot API сообщение пользователю в чат: “Спасибо за оплату! Ваш заказ №… принят в работу.”

Это уже полноценная автоматизация бизнес-процесса.

Шаг 5: Автоматизация действий с помощью роботов Битрикс24

Сила Битрикс24 — во встроенных инструментах автоматизации. После того как лид или сделка созданы через API, за дело могут взяться триггеры и роботы.

  • Триггеры реагируют на действия клиента. Например, если клиент ответил на письмо, триггер может автоматически передвинуть сделку на следующий этап.
  • Роботы выполняют действия. Как только лид попадает на определенную стадию, робот может:
    • Отправить уведомление менеджеру: “Новая заявка из Telegram! Срочно свяжись!”.
    • Поставить задачу: “Провести квалификацию лида”.
    • Отправить клиенту email или SMS с дополнительной информацией.

Пример настройки робота:

  1. Зайдите в CRM -> Лиды -> Роботы.
  2. На стадии “Новый” нажмите “Настроить роботов”.
  3. Добавьте робота “Уведомление”.
  4. В тексте уведомления напишите: Новый лид из Telegram: {{Имя}}, {{Заголовок лида}}. Ответственный: {{Ответственный}}. Значения в {{...}} подставятся автоматически из полей лида.
  5. Укажите получателем ответственного менеджера.

Теперь, как только ваш скрипт создаст лид, менеджер мгновенно получит персональное уведомление и сможет приступить к работе.

Неизбежное зло: Обработка ошибок и логирование

Интеграция может сломаться. Токен истек, Битрикс24 недоступен, в вашем коде ошибка. Если не предусмотреть обработку ошибок, вы просто перестанете получать заявки и даже не узнаете об этом.

Что нужно делать?

  1. Логируйте все. Мы уже добавили базовое логирование в наши скрипты (file_put_contents). Расширьте его: записывайте не только входящие данные, но и ответы от API Битрикс24. Если в ответе есть поле "error", значит, что-то пошло не так.
  2. Проверяйте ответы. После каждого вызова callBitrixAPI() проверяйте результат. Если он не содержит "result", значит, произошла ошибка.
  3. Настройте уведомления об ошибках. Если скрипт поймал ошибку (например, не удалось создать лид), он должен немедленно сообщить об этом вам. Самый простой способ — отправить уведомление в ваш личный Telegram-чат. Для этого создайте еще одного бота или используйте сервисы вроде LogSentry, которые умеют слать алерты.

Пример проверки ответа от Битрикс24:

$result = callBitrixAPI('crm.lead.add', $lead_data);

if (isset($result['error'])) {
    // Ошибка! Записываем в отдельный лог и шлем уведомление администратору.
    $error_message = 'Ошибка при создании лида: ' . $result['error_description'];
    file_put_contents('error_log.txt', $error_message . "\n", FILE_APPEND);
    // Здесь код для отправки уведомления администратору
}

Надежная система логирования и оповещения — это ваша страховка от потерянных клиентов.

Готовые решения vs. Самостоятельная настройка: Что выбрать?

Создание собственной интеграции, как мы описали выше, дает максимальную гибкость и полный контроль. Но это требует технических знаний и времени на поддержку. Существуют и альтернативы.

  • Маркетплейс Битрикс24. В официальном каталоге есть десятки готовых приложений для интеграции с Telegram. Они устанавливаются в один клик и предлагают базовый функционал.
    • Плюсы: Быстро, просто, не нужен программист.
    • Минусы: Ограниченный функционал, часто есть абонентская плата, вы зависите от разработчика приложения.
  • Сервисы-коннекторы (Albato, Zapier). Эти платформы позволяют “связывать” сотни различных сервисов между собой без написания кода, через визуальный интерфейс.
    • Плюсы: Очень гибко, можно строить сложные цепочки автоматизации.
    • Минусы: Абонентская плата, которая зависит от количества операций. На больших объемах может быть дорого.

Что же выбрать?

КритерийСамостоятельная настройкаГотовое приложениеСервис-коннектор
ГибкостьМаксимальнаяНизкаяВысокая
СтоимостьРазово на разработку + хостингЕжемесячная подпискаЕжемесячная подписка
СложностьВысокаяНизкаяСредняя
КонтрольПолныйНетЧастичный

Вывод: Если вам нужен стандартный функционал “создать лид из сообщения” и вы не хотите вникать в код — начните с готового приложения из Маркетплейса. Если вам нужны сложные, нестандартные сценарии, но без программирования — посмотрите на коннекторы. Если же вы хотите полный контроль, максимальную гибкость и не платить абонентскую плату — самостоятельная разработка по нашему руководству будет лучшим выбором.

Заключение: Ваша CRM на автопилоте

Мы прошли большой путь: от создания простого бота до понимания логики автоматизации бизнес-процессов. Интеграция Telegram и Битрикс24 — это не просто техническая “фишка”. Это фундаментальное изменение подхода к работе с клиентами.

Вы перестаете быть реактивными, ожидая, пока менеджер заметит заявку. Вы становитесь проактивными, где система мгновенно захватывает каждого потенциального клиента и ведет его по заранее продуманному маршруту. Вы получаете полный контроль над входящим потоком обращений, достоверную аналитику и высвобождаете время своих сотрудников для более сложных и творческих задач, чем копирование данных.

Да, первоначальная настройка требует усилий и вдумчивого подхода. Но это та инвестиция, которая окупается многократно за счет сохраненных клиентов, ускоренных продаж и порядка в бизнес-процессах.

Не бойтесь экспериментировать. Начните с простого создания лидов, постепенно добавляйте новую логику, используйте роботов и триггеры. Превратите вашу CRM из пассивного хранилища данных в активный центр управления вашим бизнесом. Будущее за автоматизацией, и оно начинается прямо сейчас.