Telegram и MAX

Агент умеет разговаривать не только из 1С, но и из мессенджера. Человек пишет боту вопрос — получает ответ, не открывая 1С.

Это другой вход, а не другой доступ: права остаются теми же, что и в 1С. Кому нельзя выполнять операции в базе — тому нельзя и через Telegram.

Раздел платный. В бесплатной редакции его в консоли нет.

Что понадобится

1. Бот — создаётся у провайдера, занимает несколько минут.
2. Адрес службы по HTTPS — доступный снаружи, с действующим сертификатом.

Второе требование — основное, и выполнять его следует в первую очередь. И Telegram, и MAX отказываются доставлять сообщения на обычный HTTP, а MAX дополнительно не принимает самоподписанный сертификат.

Если служба у вас внутри сети и наружу не смотрит, мессенджеры работать не будут — это ограничение провайдеров, а не Vrio. Обычное решение: поставить службу за тот же обратный прокси с сертификатом, за которым у вас работает остальное.

Если сервер выходит к Telegram только через прокси или Telegram не может достучаться до сервера (так бывает с серверами в России), смотрите раздел Если Telegram не доходит до сервера.

Просто попробовать, без настройки сети

Если вы хотите сначала посмотреть, как это вообще работает, публичный адрес можно получить на время — туннелем. Он выдаёт временное имя в интернете и переправляет запросы на вашу локальную службу.

Tuna (tuna.am) — российский сервис, работает без VPN. Нужна бесплатная учётная запись. Установка:

sh -c "$(curl -sSLf https://releases.tuna.am/tuna/get.sh)"   # Linux

winget install --id yuccastream.tuna                          # Windows

Затем сохраните токен из личного кабинета Tuna и запустите туннель:

tuna config save-token <ваш токен>
tuna http 8765

Tuna напечатает публичный адрес на tuna.am вида https://… — его и впишите в консоли как публичный адрес, затем нажмите «Зарегистрировать вебхук».

На бесплатном тарифе сеанс длится 30 минут и работает один туннель, а имя выдаётся заново при каждом запуске. Через полчаса бот перестанет отвечать: запустите туннель снова, впишите новый адрес и ещё раз зарегистрируйте вебхук. На платном тарифе сеанс не ограничен и имя можно закрепить.

Tuna — российский сервис. Если соединения от Telegram до серверов в России не доходят (см. Если Telegram не доходит до сервера), через Tuna бот тоже не получит сообщений; для пробы тогда подойдёт вариант с localhost.run ниже.

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

Есть вариант и без учётной записи — ssh -R 80:localhost:8765 nokey@localhost.run. Он проще, но заметно менее надёжен: имя выдаётся заново при каждом запуске, может смениться во время работы, а соединение разрывается примерно через двадцать минут простоя. Внешне все эти случаи выглядят одинаково: бот не отвечает. Для кратковременной демонстрации это приемлемо, для постоянной работы — нет.

Шаг 1. Создать бота

Telegram. Напишите @BotFather, команда /newbot. Он спросит имя и короткое имя (должно заканчиваться на bot), затем выдаст токен вида 123456:AA…. Токен сохраните — он показывается один раз.

MAX. То же самое у @MasterBot.

Для MAX на сервере должен быть установлен корневой сертификат Минцифры («Russian Trusted Root CA»). Без него все обращения к MAX будут обрываться на проверке сертификата. Для Telegram это не нужно.

Шаг 2. Настроить провайдера в консоли

Консоль → Мессенджеры → «Настроить» напротив нужного провайдера.

Поле	Что вписать
Токен бота	тот самый токен от BotFather
Публичный адрес HTTPS	адрес, по которому ваша служба доступна снаружи
Прокси (только Telegram)	только если сервер выходит к Telegram через прокси: socks5://логин:пароль@адрес:порт или http://адрес:порт. Иначе оставьте пустым
Бот отвечает пользователям	включить, когда всё проверено

Сохраните, затем нажмите «Зарегистрировать вебхук» — это команда провайдеру доставлять сообщения на ваш адрес.

Кнопка «Проверить» показывает, что видит провайдер: имя бота, куда он доставляет, сколько сообщений в очереди и последнюю ошибку доставки, если она была. Если что-то настроено неверно, это видно именно здесь. Под свежей ошибкой консоль пишет, что она значит и что делать.

Через прокси Vrio отправляет запросы в Telegram: ответы, файлы, регистрацию вебхука. Входящие сообщения Telegram доставляет на ваш публичный адрес сам, прокси на это не влияет. Чтобы убрать прокси, нажмите «Убрать прокси» под полем; пустое поле при сохранении оставляет прежний. У MAX поля прокси нет: его серверы находятся в России.

Токен бота и прокси хранятся в базе зашифрованными: в адресе прокси может быть пароль, поэтому в консоли после сохранения виден только адрес, без логина и пароля. Ключ шифрования служба выпускает сама при первом запуске, поэтому настраивать для этого ничего не нужно.

Если Telegram не доходит до сервера

Признак. «Проверить» показывает ошибку доставки Connection timed out или Connection refused, число сообщений в очереди растёт, а консоль пишет: «Telegram не может подключиться к вашему серверу».

Почему так. Вебхук работает в обратную сторону: соединение открывает не Vrio, а серверы Telegram, они сами подключаются к вашему публичному адресу. Если эти соединения по дороге отбрасываются (так бывает с серверами в России), прокси не поможет: он работает только для соединений, которые открывает ваш сервер.

Проверьте сначала, что адрес жив. Откройте в браузере https://ваш-адрес/tg/webhook. Ответ Method Not Allowed — это нормально: служба отвечает, а Telegram шлёт сюда запросы другого вида. Если так отвечает и с машины вне вашей сети (например, через VPN), а Telegram всё равно не доходит, значит, отбрасываются соединения именно от Telegram.

Решение — промежуточный сервер в сети, до которой Telegram доходит, например вне России. Telegram доставляет сообщения на него, а он передаёт их вашей службе. Vrio для этого менять не нужно: защитный заголовок Telegram проходит через промежуточный сервер как есть. Если у вас уже есть такой сервер для прокси, подойдёт он же.

Способ 1. Пересылка через nginx. На промежуточном сервере нужны доменное имя и сертификат (например, Let's Encrypt). Конфигурация nginx:

server {
    listen 443 ssl;
    server_name relay.example.com;
    ssl_certificate     /etc/letsencrypt/live/relay.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/relay.example.com/privkey.pem;

    location /tg/webhook {
        proxy_pass https://vrio.example.ru/tg/webhook;   # адрес вашей службы
        proxy_ssl_server_name on;
    }
}

Этот способ требует, чтобы ваш сервер принимал соединения от промежуточного. Если он закрыт для соединений извне, используйте способ 2.

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

autossh -M 0 -N -o ServerAliveInterval=30 -o ExitOnForwardFailure=yes \
    -R 127.0.0.1:8443:localhost:8765 user@relay.example.com

autossh переподключает туннель после обрыва; поставьте его как службу системы, чтобы он поднимался после перезагрузки. 8765 — порт службы Vrio на этом сервере. На промежуточном сервере в той же конфигурации nginx замените строку proxy_pass на:

        proxy_pass http://127.0.0.1:8443/tg/webhook;

В консоли в обоих случаях впишите публичным адресом промежуточный сервер (https://relay.example.com), сохраните и нажмите «Зарегистрировать вебхук». Через минуту нажмите «Проверить»: очередь должна стать 0, а ошибка — пропасть.

Шаг 3. Связать сотрудника с его чатом

Бот отвечает только связанным чатам: пока чат не связан с учётной записью Vrio, ответов не будет.

В том же разделе, карточка «Связать чат сотрудника»:

1. Выберите человека из списка.
2. Нажмите «Выдать токен» — появится команда вида /link <токен>.
3. Отдайте её сотруднику целиком.
4. Он отправляет её вашему боту сообщением.

Строка длинная — в ней несколько сотен символов, и переносить её глазами не нужно: копируйте целиком. Токен живёт десять минут и срабатывает один раз, так что просроченный выпускается заново.

После этого его чат связан, и он может разговаривать с агентом.

Сотрудник может выпустить эту строку сам, не обращаясь к вам: в 1С раздел «Vrio agent» → «Привязать мессенджер».

Форма выдаёт готовую команду /link …, которую остаётся отправить боту. Для этого нужна роль «Vrio: выпуск токенов привязки мессенджера» (Vrio_MessengerAccess): без неё обычный пользователь команды в 1С не увидит и остаётся путь через консоль.

У пользователя с полными правами 1С команда видна всегда — полные права распространяются и на объекты расширения. Но роль этим не заменяется: по нажатию придёт отказ «Нет прав на выпуск токенов привязки мессенджера». Роль нужно выдать так же, как остальные, — см. инструкцию по установке.

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

Токен отображается один раз и действует десять минут. Если срок истёк, выпустите новый. Короткий срок действия нужен для того, чтобы перехваченная строка быстро становилась бесполезной.

Связанные чаты видны в таблице «Подключённые чаты», там же кнопка «Отключить» — она разрывает связь, не трогая самого человека.

Файлы

Боту в Telegram можно отправить файл — документ, фотографию или таблицу. Подпись к файлу агент читает как вопрос к нему: например, скан карточки предприятия с подписью «заведи контрагента по этим реквизитам». Файл можно прислать и без подписи — агент откроет его, коротко скажет, что в нём, и спросит, что с ним сделать.

Правила те же, что в чате внутри 1С: те же разрешённые форматы из раздела «Форматы файлов» в консоли и то же распознавание текста на сканах и фотографиях. Отличие одно: Telegram отдаёт боту файлы размером до 20 МБ, а в 1С можно приложить до 25 МБ.

Если файл не подходит, бот отвечает, почему: такой тип не читается, формат вам не разрешён, файл слишком большой или его не удалось получить. Вопрос из подписи в этом случае агенту не передаётся — отправьте подходящий файл заново.

Голосовые сообщения и видеокружки агент не понимает. Бот попросит написать текстом.

Две особенности Telegram, которые стоит знать сотрудникам:

• Фотографию Telegram пересжимает. Для скана с мелким текстом надёжнее отправить снимок как файл, а не как фото — тогда он дойдёт в исходном качестве.
• Несколько файлов одним сообщением приходят боту по отдельности, и подпись достаётся только одному из них. Надёжнее отправлять по одному файлу с подписью.

Бот в MAX принимает файлы и фотографии по тем же правилам и с тем же пределом в 20 МБ.

Файлы от агента

Агент может прислать в чат готовый документ — счёт или акт в PDF, выгрузку в Excel. Попросите прямо: «сформируй счёт на оплату по заказу 125 и пришли файлом». Агент сформирует документ в 1С и отправит его в этот же чат, откуда его можно переслать клиенту. Формирование документа — это выполнение кода в 1С, поэтому перед ним придёт запрос подтверждения кнопками.

В чате внутри 1С документ появляется прямо в переписке — карточкой с названием и размером файла; нажмите на неё, чтобы сохранить файл. Если нужен файл в мессенджере, скажите об этом: «пришли его мне в Telegram» — агент отправит документ в ваш чат с ботом, если он привязан.

Размер одного документа — до 10 МБ. Если документ больше или мессенджер его не принял, агент скажет об этом.

Чего в мессенджере нет

Форм и HTML-страниц. Их показывает только окно 1С, поэтому в мессенджере агент их не строит.

Как это выглядит у сотрудника

Он пишет боту обычным сообщением: «сколько мы должны поставщику Ромашка», «покажи документы за сентябрь». Агент отвечает в том же чате.

Действия, меняющие данные, по-прежнему требуют подтверждения — оно приходит в чат кнопками, как и в 1С.

Если администратор включил лимиты расхода, команда /usage показывает, сколько процентов лимита на 5 часов и на неделю израсходовано и когда они восстановятся. Лимит общий с 1С: вопросы в боте и в 1С тратят одно и то же.

Если не работает

Бот молчит на любое сообщение. Проверьте «Бот отвечает пользователям» — выключенный бот принимает сообщения и ничего не делает. Затем «Проверить»: если провайдер не знает вашего адреса, нажмите «Зарегистрировать вебхук» ещё раз.

Бот молчит одному человеку, остальным отвечает. Его чат не связан. Выдайте токен привязки.

«Проверить» показывает ошибку доставки. Провайдер не смог достучаться до вашей службы: адрес недоступен снаружи, сертификат не принят или служба остановлена. Под свежей ошибкой консоль пишет, какой из этих случаев ваш.

Ошибка доставки Connection timed out или Connection refused. Telegram не может подключиться к вашему серверу. Смотрите Если Telegram не доходит до сервера.

Растёт очередь сообщений. То же самое: провайдер накапливает недоставленное. Разберитесь с доступностью адреса — очередь разойдётся сама.

MAX обрывается, Telegram работает. Не установлен корневой сертификат Минцифры.

Бот работал, затем перестал отвечать, при этом используется туннель. Это первое, что следует проверить: туннель мог закрыться или сменить адрес, тогда как на вашей машине всё выглядит работающим. Откройте адрес туннеля в браузере. Если он не отвечает или возвращает ошибку, поднимите туннель заново, укажите новый адрес в консоли и зарегистрируйте вебхук ещё раз.