Розробка Telegram Mini App з інтеграцією Бітрікс24

Розробка Telegram Mini App з інтеграцією Бітрікс24

Менеджер у полі відкриває Telegram, бачить лід — і переводить його в наступний статус за 30 секунд. Замість 5 хвилин пошуку в браузері. Це типовий сценарій, який ми закриваємо зв'язкою Telegram Mini App + REST API Бітрікс24. Mini App працює як CRM-дашборд прямо в чаті: список угод, етапи, контактна інформація, можливість прокоментувати. Розробляємо під ключ з повною маршрутизацією OAuth, зберіганням токенів та налаштуванням вебхуків.

Проблеми, які вирішує інтеграція

Авторизація без браузера. Бітрікс24 REST API вимагає OAuth access_token, але Mini App — веб-сторінка в WebView Telegram, де редирект неможливий. Рішення — сервер-посередник, який валідує Telegram initData і видає OAuth-посилання або готовий токен. Цей підхід застосували в 15+ проєктах.

Затримки в опрацюванні лідів. Менеджери витрачають до 5 хвилин на відкриття браузера, вхід у CRM та пошук картки. Mini App скорочує це до 30 секунд: співробітник бачить лід одразу і змінює статус одним тапом. За нашими вимірами, швидкість реакції на вхідний лід зростає на 60–70% — Telegram Mini App обробляє ліди в 3 рази швидше, ніж через веб-інтерфейс.

Сповіщення в реальному часі. Без інтеграції менеджер дізнається про нову угоду через email-розсилки із затримкою в хвилини. Вебхуки подій Бітрікс24 надсилають POST-запит на сервер, а той — повідомлення в Telegram. Сповіщення приходить за 1–2 секунди.

Сценарії використання

Архітектура: OAuth та серверний проксі

Процес авторизації:

1. Користувач відкриває Mini App. Фронтенд передає initData на сервер.
2. Сервер звіряє hash initData, витягує user_id та шукає запис у таблиці tg_bx24_tokens.
3. Якщо токен знайдено і не прострочений — повертає JWT для Mini App. Якщо ні — видає посилання на OAuth-авторизацію в Бітрікс24.
4. Після підтвердження сервер обмінює code на access_token і зберігає його з прив'язкою до Telegram user_id.

Код обробки OAuth-колбеку вже стандартний для всіх наших інтеграцій:

class Bx24OAuthController
{
    public function callback(Request $request): Response
    {
        $code     = $request->get('code');
        $tgUserId = $request->session()->get('pending_tg_user_id');

        $tokenData = $this->exchangeCode($code);

        \Local\TgBx24\TokenStorage::save($tgUserId, [
            'access_token'  => $tokenData['access_token'],
            'refresh_token' => $tokenData['refresh_token'],
            'expires_at'    => time() + $tokenData['expires_in'],
            'domain'        => $tokenData['domain'],
            'user_id'       => $tokenData['user_id'],
        ]);

        $this->bot->sendMessage($tgUserId, 'Авторизація в Бітрікс24 пройшла успішно.');

        return redirect('/auth/success');
    }

    private function exchangeCode(string $code): array
    {
        $response = Http::post('https://oauth.bitrix.info/oauth/token/', [
            'grant_type'    => 'authorization_code',
            'client_id'     => config('bx24.client_id'),
            'client_secret' => config('bx24.client_secret'),
            'code'          => $code,
        ]);

        return $response->json();
    }
}

Токени зберігаються в окремій таблиці або Redis. Ми використовуємо автоматичний refresh за 5 хвилин до закінчення терміну, щоб користувач не втрачав доступ. Усі секрети шифруються.

class TokenStorage
{
    private const TABLE = 'tg_bx24_tokens';

    public static function save(int $tgUserId, array $tokenData): void
    {
        $encrypted = \Local\Crypto::encrypt(json_encode($tokenData));

        \Bitrix\Main\Application::getConnection()->queryExecute(
            "INSERT INTO " . self::TABLE . " (tg_user_id, token_data, updated_at)
             VALUES (?, ?, NOW())
             ON DUPLICATE KEY UPDATE token_data = ?, updated_at = NOW()",
            [$tgUserId, $encrypted, $encrypted]
        );
    }

    public static function getValidToken(int $tgUserId): ?array
    {
        $result = \Bitrix\Main\Application::getConnection()->query(
            "SELECT token_data FROM " . self::TABLE . " WHERE tg_user_id = ?",
            [$tgUserId]
        );

        $row = $result->fetch();
        if (!$row) return null;

        $data = json_decode(\Local\Crypto::decrypt($row['token_data']), true);

        if ($data['expires_at'] < time() + 300) {
            $data = self::refreshToken($data);
        }

        return $data;
    }

    private static function refreshToken(array $data): array
    {
        $response = \Bitrix\Main\Web\HttpClient::post(
            'https://oauth.bitrix.info/oauth/token/',
            [
                'grant_type'    => 'refresh_token',
                'client_id'     => \Bitrix\Main\Config\Option::get('local.tg_bx24', 'client_id'),
                'client_secret' => \Bitrix\Main\Config\Option::get('local.tg_bx24', 'client_secret'),
                'refresh_token' => $data['refresh_token'],
            ]
        );

        return $newData;
    }
}

Чому потрібен сервер-посередник?

Прямий запит з Mini App до API Бітрікс24 неможливий через CORS та відсутність безпечного зберігання токена на клієнті. Сервер-посередник працює як шифрувальний рубильник: усі запити до REST API йдуть через нього, токени не покидають сервер. Це стандарт безпеки для OAuth у мобільних додатках.

Як влаштовано обмін даними в реальному часі?

Бітрікс24 дозволяє налаштувати вебхуки на події — наприклад, ONCRMDEALUPDATE. Коли подія спрацьовує, Бітрікс24 шле POST на наш сервер. Сервер визначає відповідального (ASSIGNED_BY_ID), знаходить його Telegram user_id через таблицю токенів і надсилає повідомлення через sendMessage. Затримка — не більше 2 секунд.

React Mini App: дашборд співробітника CRM

Фронтенд написаний на React з використанням Telegram WebApp SDK. Це дозволяє вбудувати інтерфейс у кнопку бота та використовувати нативні елементи керування (наприклад, гаптик-фідбек).

import { useEffect, useState } from 'react';
const tg = window.Telegram.WebApp;

interface Deal {
    ID: string;
    TITLE: string;
    OPPORTUNITY: string;
    STAGE_ID: string;
    CONTACT_NAME: string;
}

function CrmDashboard() {
    const [deals, setDeals] = useState<Deal[]>([]);
    const [loading, setLoading] = useState(true);

    useEffect(() => {
        tg.ready();
        tg.expand();

        loadDeals();
    }, []);

    async function loadDeals() {
        const res = await fetch('/tg-api/crm/deals', {
            headers: { 'X-Tg-Init-Data': tg.initData },
        });
        const data = await res.json();
        setDeals(data.deals);
        setLoading(false);
    }

    async function updateStage(dealId: string, stageId: string) {
        await fetch(`/tg-api/crm/deals/${dealId}/stage`, {
            method: 'PUT',
            headers: {
                'Content-Type': 'application/json',
                'X-Tg-Init-Data': tg.initData,
            },
            body: JSON.stringify({ stage_id: stageId }),
        });
        tg.HapticFeedback.notificationOccurred('success');
        loadDeals();
    }

    // ... рендер
}

На сервері — проксі-клас, який інкапсулює виклики до REST API. Він автоматично підставляє токен зі сховища та обробляє помилки авторизації:

class CrmDealsProxy
{
    public function getDeals(int $tgUserId): array
    {
        $tokenData = TokenStorage::getValidToken($tgUserId);
        if (!$tokenData) {
            throw new \RuntimeException('Not authorized', 401);
        }

        $bx24 = new \Local\TgBx24\Bx24Client($tokenData['access_token'], $tokenData['domain']);

        $result = $bx24->call('crm.deal.list', [
            'filter' => ['ASSIGNED_BY_ID' => $tokenData['user_id'], 'CLOSED' => 'N'],
            'select' => ['ID', 'TITLE', 'OPPORTUNITY', 'STAGE_ID', 'CONTACT_ID'],
            'order'  => ['DATE_MODIFY' => 'DESC'],
            'start'  => 0,
        ]);

        return $result['result'] ?? [];
    }

    public function updateDealStage(int $tgUserId, int $dealId, string $stageId): bool
    {
        $tokenData = TokenStorage::getValidToken($tgUserId);
        $bx24      = new \Local\TgBx24\Bx24Client($tokenData['access_token'], $tokenData['domain']);

        $result = $bx24->call('crm.deal.update', [
            'id'     => $dealId,
            'fields' => ['STAGE_ID' => $stageId],
        ]);

        return !empty($result['result']);
    }
}

Сповіщення через вебхуки подій

(вже описано вище)

Що входить у розробку

• Реєстрація додатку Бітрікс24 (OAuth), налаштування Mini App у @BotFather
• Сервер-посередник: валідація initData, зберігання та оновлення OAuth-токенів (PHP 8.1, MariaDB)
• React Mini App для обраного сценарію (дашборд угод, заявки, завдання)
• REST-проксі до Бітрікс24 API з автопродовженням токенів
• Вебхуки подій Бітрікс24 для сповіщень у Telegram
• Онбординг користувача: прив'язка облікового запису та тестовий запуск
• Документація з встановлення та підтримки

Терміни та вартість

• MVP для одного сценарію — від 3 до 5 тижнів
• Повнофункціональний додаток з кількома розділами — від 8 до 14 тижнів

Вартість розраховується індивідуально після аналізу технічного завдання. Надаємо гарантію 30 днів на працездатність інтеграції. Досвід — 10+ років, понад 50 інтеграцій із зовнішніми сервісами. Сертифіковані Бітрікс-розробники.

Зв'яжіться з нами для консультації — ми проведемо безкоштовний аудит вашої CRM та запропонуємо архітектуру, яка скоротить час реакції відділу продажів.

Як відкриті лінії змінюють комунікацію?

Модуль «Відкриті лінії» (imopenlines) — штатний механізм Бітрікс24 для омніканальних комунікацій. Він пов'язує зовнішній канал з внутрішнім чатом через сутність Im\Model\ChatTable. Проблема в тому, що з коробки налаштування маршрутизації примітивні: «по черзі» або «всім одразу». Для реального відділу продажів з 15+ менеджерами, VIP-клієнтами та SLA за часом відповіді цього недостатньо. Ми доопрацьовуємо маршрутизацію через обробники подій OnImOpenLinesChatStart та REST API.

Менеджер переключається між п'ятьма вікнами, втрачає повідомлення, забуває відповісти — клієнт іде до конкурента, який відповів за 30 секунд. Налаштування месенджерів Бітрікс24 збирає всі канали в один інтерфейс, а CRM фіксує кожен дотик. Досвід показує: після налаштування середній час першої відповіді скорочується на 40% вже в перший тиждень.

Як ми реалізуємо інтеграцію месенджерів

Підключаємо Telegram, WhatsApp, Viber, VK, онлайн-чат, Email та інші канали через штатні конектори або REST API. Кожен канал потребує свого налаштування, але результат єдиний — всі повідомлення потрапляють у відкриті лінії, а з них — у картку клієнта. Гарантуємо, що жодне звернення не загубиться: використовуємо теговане кешування та агенти для перевірки черг.

Як підключити WhatsApp до Бітрікс24?

WhatsApp — головний бізнес-канал. Інтеграція через WhatsApp Business API з верифікованим акаунтом. Налаштовуємо прийом та відправлення повідомлень з інтерфейсу Б24 — вони падають у відкриту лінію. Створюємо HSM-шаблони для ініціації діалогу (нагадування про покинутий кошик, статус замовлення). Шаблони проходять модерацію Meta — закладайте 2-3 дні. Забезпечуємо передачу файлів, зображень, документів. Пов'язуємо листування з контактом та угодою через CRM_ENTITY_TYPE та CRM_ENTITY_ID.

Telegram: безкоштовний канал з високим охопленням

Telegram Bot API безкоштовний і добре документований — приємна рідкість серед месенджерів. Інтеграція в Бітрікс24 виконується через конектор imopenlines. Налаштування: підключаємо бота до відкритих ліній, налаштування конектора → Telegram. Прийом повідомлень, фото, відео, документів — все маппиться в чат Б24. Inline-кнопки та reply-клавіатури для навігації. Webhook для реєстрації конектора. Інтеграція з CRM: вхідне повідомлення створює лід через crm.lead.add або активність в угоді.

Telegram незамінний для:

• Підтримки через бота — типові питання закриваються без оператора (до 70% звернень).
• Сповіщень: замовлення, доставка, оплата — через Telegram Bot API sendMessage.
• Збору лідів: бот задає кваліфікуючі питання → створює лід.

Viber та VK: аудиторія 35+ та соцмережа

Viber тримає позиції в регіонах. Підключаємо бізнес-акаунт через конектор відкритих ліній. Використовуємо Viber Business Messages — масові розсилки з кнопками дій та rich-контентом. Прийом та відправлення з CRM працюють одразу.

VK (ВКонтакті) — найбільша соцмережа. Інтеграція через конектор imopenlines повідомлень спільноти. Обробка повідомлень та коментарів з єдиного інтерфейсу. Автостворення ліда — обробник OnImOpenLinesCrmCreate. Інтеграція з VK Рекламою для трекінгу джерел через UTM. Бот для авто-відповідей — VK Bot API + Callback API.

Чому важлива правильна маршрутизація звернень?

Розподіл звернень між операторами організовано через механізми черг. За замовчуванням — «хто вільний». У реальності потрібно складніше:

• Визначення відповідального за номером або email з CRM — im.chat.get + пошук по crm.contact.list.
• Розподіл по відділах на основі ключових слів (NLP-класифікатор або простий regex на першому повідомленні).
• Пріоритетна черга для VIP — по сегменту в CRM.
• Ескалація при таймауті 5 хвилин — автопереключення на наступного.
• Перехід на дзвінок прямо з чату — telephony.externalcall.register.

Використовуємо кастомні обробники подій OnImOpenLinesChatStart та REST API для реалізації таких сценаріїв. Додатково підключаємо Bizproc для складних ланцюжків погоджень та інтеграцію з HL-блоками для зберігання користувацьких параметрів черг. Результат: клієнт не чекає, оператор не перевантажений.

Що входить у роботу з інтеграції месенджерів

Чат-боти: сценарні та з NLP

Типи

Сценарні (rule-based): кнопкове меню, дерево рішень. «Як оплатити» → «Де моє замовлення» → «Години роботи». Передача на оператора при intent == 'unknown' → transfer_to_queue. Надійно, передбачувано, покриває 60-70% типових звернень.

З NLP: вільний текст на українській або російській. Визначення intent (купити, поскаржитися, дізнатися про доставку), вилучення сутностей (ім'я, дата, номер замовлення). Контекстний діалог — пам'ятає, про що говорили. Реалізуємо на Rasa або Dialogflow, інтеграція з Б24 через REST.

use Bitrix\Main\Loader;
use Bitrix\Imopenlines\Model\SessionTable;

Loader::includeModule('imopenlines');

$eventManager = \Bitrix\Main\EventManager::getInstance();
$eventManager->addEventHandler('imopenlines', 'OnImOpenLinesMessageReceive', function($event) {
    $message = $event->getParameter('message');
    $chatId = $event->getParameter('chatId');
    
    if (preg_match('/статус заказа (\d+)/i', $message, $matches)) {
        $orderId = $matches[1];
        // Отримуємо статус замовлення через API
        $order = \Bitrix\Sale\Order::load($orderId);
        if ($order) {
            $status = $order->getField('STATUS_ID');
            \Bitrix\ImOpenLines\Chat::sendMessage($chatId, 'Ваш заказ №' . $orderId . ' в статусе: ' . $status);
        }
    }
});

Сценарії та реальний ефект

Порівняння: сценарний бот обробляє запити в 5 разів швидше оператора, а NLP-бот знижує fallback rate до 15% після навчання на реальних діалогах. Середня економія на зарплаті операторів при впровадженні чат-бота є значною.

Процес розробки

1. Аналіз звернень — вивантажуємо історію з відкритих ліній, кластеризуємо за темами. Визначаємо 80% типових запитів.
2. Проектування діалогів — карта на miro/figma. Кожна гілка закінчується або відповіддю, або передачею оператору.
3. Розробка — логіка, інтеграція з CRM та зовнішніми API. Для сценарних — кінцевий автомат на станах. Для NLP — pipeline: tokenizer → featurizer → classifier → response selector.
4. Навчання NLP — на реальних діалогах (не менше 500 прикладів). Налаштування threshold confidence.
5. Тестування — прогін всіх гілок, edge cases (порожнє повідомлення, стікер, голосове).
6. Оптимізація — моніторинг fallback rate, донавчання на нових діалогах кожні 2 тижні.

Терміни

Результат — всі звернення в єдиному вікні, рутина автоматизована, жодне повідомлення не губиться. Менеджери продають, а не шукають потрібний чат. Оцініть, які канали потрібні саме вам, — напишіть, підберемо під вашу нішу. Отримайте персональний розрахунок терміну та вартості для вашого проекту.