# Живой чат с оператором (открытые линии Bitrix24) — подробная инструкция Цель: клиент пишет боту (MAX/Telegram) → сообщение оператору в Б24; оператор отвечает в Б24 → ответ приходит клиенту в мессенджер. > ⚠️ Методы `imconnector.*` работают ТОЛЬКО в контексте **локального приложения** > Bitrix24 (не через вебхук). Поэтому сначала — приложение, потом коннектор. Везде ниже подставлены твои реальные значения: - Домен портала: **замени `portal.bitrix24.ru`** на свой (тот, где CRM). - Домен сервера бота: **`spa-bitrix.ru`**, папка `/var/www/spa-bitrix.ru/msch/bot/`. - Публичные URL файлов бота: `https://spa-bitrix.ru/msch/bot/<файл>`. --- ## Что уже сделано в коде (готово) - `b24_app.php` — обработчик установки приложения (сохраняет токен). - `src/B24Token.php` — хранит и **сам обновляет** токен приложения. - `src/Relay.php` — шлёт сообщения клиента в линию (`imconnector.send.messages`) от имени приложения. - `operator_reply.php` — принимает ответы оператора и шлёт клиенту. - Кнопка «оператор» открывает диалог; `/stop` завершает. Тебе нужно: создать приложение, установить его, зарегистрировать коннектор, привязать событие, вписать 4 значения в `config.php`. --- ## ПРЕДВАРИТЕЛЬНО - Права **администратора** портала. - Файлы `b24_app.php` и `operator_reply.php` должны открываться по HTTPS и работать на **PHP 8.1+** (на Apache/PHP 7.x — не запустятся; см. про php8.3-fpm). - Проверь, что открываются в браузере: - `https://spa-bitrix.ru/msch/bot/b24_app.php` → «b24_app.php готов…» - `https://spa-bitrix.ru/msch/bot/operator_reply.php` → `{"ok":true}` --- ## ШАГ 1. Создать локальное приложение Портал → **Приложения** → слева внизу **Разработчикам** → **Другое** → **Локальное приложение** (кнопка «Создать»). Заполни поля ТОЧНО так: | Поле | Что вписать | |---|---| | **Название приложения** | `MSCH Bot Connector` | | **Путь вашего обработчика** (Handler path / URL обработчика) | `https://spa-bitrix.ru/msch/bot/b24_app.php` | | **Путь для первоначальной установки** (Installation path) | `https://spa-bitrix.ru/msch/bot/b24_app.php` | | **Использует только API** / «приложение не имеет пользовательского интерфейса» | ✅ поставить галочку (если есть) | | **Разрешения (scope)** | отметить: **CRM (crm)**, **Открытые линии (imopenlines)**, **Коннектор открытых линий (imconnector)**, **Чат и уведомления (im)**, **Пользователи (user)** | Сохрани. После сохранения портал покажет: - **Код приложения** (client_id) — вида `local.xxxxxxxxxxxxxx.xxxxxxxx` - **Ключ приложения** (client_secret) — длинная строка Скопируй оба. --- ## ШАГ 2. Вписать client_id/secret и установить приложение 1. В `config.php` бота (или через переменные окружения) впиши: ```php 'bitrix24' => [ // ... webhook/category_id/stage_id/assigned_by_id для сделок оставь как есть ... 'client_id' => 'local.xxxxxxxxxxxxxx.xxxxxxxx', // Код приложения из Шага 1 'client_secret' => 'СКОПИРОВАННЫЙ_КЛЮЧ', 'connector_id' => 'msch_bot', // впишем после Шага 3 'line_id' => 0, // впишем после Шага 4 ], ``` 2. В портале открой приложение (в списке «Разработчикам» → твоё приложение → кнопка **«Открыть»** / **«Переустановить»**). Б24 дёрнет `b24_app.php`, тот сохранит токен в `b24_token.json`. Должно показать «Приложение установлено». Проверь, что файл появился: ```bash cat /var/www/spa-bitrix.ru/msch/bot/b24_token.json # должны быть access_token/refresh_token ``` Если файла нет — значит `b24_app.php` недоступен по HTTPS или падает (PHP 7.x). --- ## ШАГ 3. Зарегистрировать коннектор Все вызовы ниже удобно делать через встроенную консоль REST в портале (**Разработчикам → Другое → Настроить свой REST-запрос**) или curl'ом с токеном из `b24_token.json` (поле `access_token`, база `rest`). `imconnector.register`: ``` POST {rest}imconnector.register?auth={access_token} Body (JSON): { "ID": "msch_bot", "NAME": "Бот МСЧ 168 (MAX/Telegram)", "ICON": { "DATA_IMAGE": "data:image/svg+xml,", "COLOR": "#2fc6f6" } } ``` `ID = msch_bot` — это твой **connector_id** (впиши в config, Шаг 2). --- ## ШАГ 4. Узнать ID линии и активировать коннектор **Контакт-центр → Открытые линии.** Открой нужную линию (или создай) — её ID виден в адресной строке (`.../openlines/edit/107/` → ID = `107`). `imconnector.activate`: ``` POST {rest}imconnector.activate?auth={access_token} { "CONNECTOR": "msch_bot", "LINE": 107, "ACTIVE": 1 } ``` Впиши `line_id = 107` в config (Шаг 2). `imconnector.connector.data.set` (данные виджета линии): ``` POST {rest}imconnector.connector.data.set?auth={access_token} { "CONNECTOR": "msch_bot", "LINE": 107, "DATA": { "id": "msch_bot_107", "name": "Бот МСЧ 168", "url": "https://spa-bitrix.ru" } } ``` Проверка: ``` POST {rest}imconnector.status?auth={access_token} { "CONNECTOR": "msch_bot", "LINE": 107 } → ожидаем CONFIGURED: true, STATUS: true ``` --- ## ШАГ 5. Привязать ответы оператора (событие) `event.bind` — чтобы сообщения оператора уходили на наш endpoint: ``` POST {rest}event.bind?auth={access_token} { "event": "OnImConnectorMessageAdd", "handler": "https://spa-bitrix.ru/msch/bot/operator_reply.php?secret=ВАШ_СЕКРЕТ", "auth_type": 1 } ``` `ВАШ_СЕКРЕТ` — тот же, что в `config.php → operator_reply_secret`. Проверить привязку: `POST {rest}event.get?auth={access_token}` — в списке должно быть `OnImConnectorMessageAdd`. --- ## ШАГ 6. Настроить открытую линию **Контакт-центр → Открытые линии → линия 107 → Настроить:** - **Очередь операторов:** добавить сотрудников (в т.ч. 78), правило распределения. - **Рабочее время:** график + автоответ в нерабочее время. - **CRM:** «создавать/привязывать по телефону» — по желанию (диалог подтянется к пациенту). --- ## ШАГ 7. Финальный config.php ```php 'bitrix24' => [ 'webhook' => 'https://portal.bitrix24.ru/rest/1/КОД/', // для сделок (отмена/перенос) 'category_id' => 82, 'stage_id' => 'C82:NEW', 'assigned_by_id' => 78, 'client_id' => 'local.xxxxxxxxxxxxxx.xxxxxxxx', 'client_secret' => 'КЛЮЧ_ПРИЛОЖЕНИЯ', 'connector_id' => 'msch_bot', 'line_id' => 107, ], 'operator_reply_secret' => 'ВАШ_СЕКРЕТ', ``` После правки — перезапусти поллер: `systemctl restart msch-bot-poll`. --- ## ШАГ 8. Проверка формата события (важно) Реальный формат `OnImConnectorMessageAdd` нужно увидеть один раз. Временно в начало `operator_reply.php` добавь дамп: ```php file_put_contents(__DIR__.'/event_dump.txt', $raw); // сразу после чтения $raw ``` Напиши клиенту как оператор из линии, затем пришли мне содержимое `event_dump.txt` — подгоню разбор (`chat_ref`/`text`/`finish`) под точные имена полей события. --- ## ПРОВЕРКА END-TO-END 1. Клиент в боте жмёт «Соединение с оператором» → в линии 107 появляется диалог. 2. Клиент пишет → текст виден оператору. 3. Оператор отвечает → клиенту приходит «👤 Оператор: …». 4. Клиент шлёт `/stop` → диалог закрывается. --- ## ЧАСТЫЕ ПРОБЛЕМЫ | Симптом | Причина / решение | |---|---| | `b24_token.json` не создался | `b24_app.php` недоступен по HTTPS или падает (PHP 7.x под Apache) | | `imconnector.register` → ошибка контекста/прав | вызов без токена приложения, или в scope нет `imconnector` | | Диалог не появляется у оператора | коннектор не активирован (Шаг 4) или в линии нет операторов (Шаг 6) | | Ответ оператора не доходит | событие не привязано (Шаг 5) или `operator_reply.php` даёт 500 (PHP 7.x) / не тот `secret` | | «не удалось обновить токен» | переустанови приложение (Шаг 2), проверь client_id/secret | | Telegram: ответы не уходят | нет исходящего доступа к `api.telegram.org` с сервера | --- ## Прод-требования (напоминание) - `b24_app.php` и `operator_reply.php` — только PHP **8.1+** (php8.3-fpm на папку бота). - Токен приложения обновляется автоматически (`B24Token`), но если приложение удалить/переустановить — токен надо получить заново (Шаг 2). - Для Telegram — исходящий доступ к API. Как пройдёшь Шаги 1–2 и пришлёшь дамп события (Шаг 8) — я финализирую разбор в `operator_reply.php`, и чат заработает полностью.