Боты и SmartApps

Обзор

Функция	Описание	Возможности
Бот	Lite CTS eCTS Бот — это специальный контакт, за которым скрывается веб-приложение. Взаимодействует с пользователем через чат. Чат-боты обладают функциональностью, знакомой многим из других мессенджеров. Пользователям eXpress Lite можно использовать только встроенные служебные боты.	отправка текстовых сообщений, файлов; отправка сообщений с кнопками; получение системных событий (создание чата, вход пользователя в чат и т.д.); включение/отключение режима повышенной конфиденциальности; назначение администраторов чата; создание чата с пользователем (полезно для корпоративных чат-ботов) и т.д. обмен данными со сторонними корпоративными системами или приложениями.
SmartApp	CTS eCTS SmartApps — это веб-приложения с полноценным пользовательским интерфейсом для различных бизнес-процессов: почта, календарь, кадровые сервисы, электронный документооборот, порталы, поддержка и другие. Они встраиваются прямо в приложение eXpress или ETS -приложение.	Все корпоративные сервисы доступны в любое время и на любом устройстве с eXpress в формате единого окна; SSO: вошли на одном устройстве, на других входить не потребуется — мобильные и десктопные устройства объединяются в единую корпоративную платформу; Интеграция со множеством систем: почтовые клиенты, документооборот, 1С, CRM, обучение сотрудников и др. Позволяет быстро решать рабочие задачи на смартфоне или планшете — быстрее и дешевле традиционной разработки мобильных приложений, экономит время и повышает продуктивность сотрудников.

Кто может управлять ботами и SmartApps?

Управлять ботами и SmartApps или подключать внутренние боты в глобальный чат может администратор корпоративного сервера /.

Кому доступны боты SmartApps?

SmartApps доступны обладателям расширенной лицензии (тариф SmartApps). Для ботов необходим любой корпоративный тариф, расширенная лицензия не требуется. По вопросам подключения обращайтесь в коммерческий отдел или к вашему аккаунт-менеджеру eXpress.

Как защищены SmartApps на стороне пользователей?

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

Не могу найти SmartApps в приложении для Aurora. Почему?

⚠️ Приложение для Aurora временно не поддерживает SmartApps.

Внутренние боты

В eXpress есть идущие в комплекте внутренние боты, необходимые для работы определённых функций приложения. Некоторые из них:

Внутренние боты	Описание
Conference Notifier bot	Оповещает пользователей о предстоящих конференциях. С его помощью также можно настроить регулярные напоминания о бессрочных конференциях.
Notifications bot	Бот для отправки сообщений в глобальный чат.
Poll bot	Бот для отправки результатов опросов.
Recordings bot	Бот для уведомлений о готовых записях звонков.

Стандартные SmartApps

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

---

❓ Связанные вопросы:
• Что делать, если чат-бот не работает или работает неправильно
• Что делать, если SmartApp не работает или работает неправильно
• В чате, созданном ботом, отправляемые сообщения зависают с ошибкой
• Используйте актуальный Android System WebView

Коллекция ботов и SmartApps

Доступны готовые к развёртыванию боты и SmartApps:

Для каждого бота и SmartApp в каталоге предусмотрен файл .env с переменными, содержащий подробное описание всех конфигурационных параметров.

Описание некоторых ботов и SmartApps:

Бот/SmartApp	Описание и инструкция для пользователей
Webhook Bot	Подписки на уведомления сторонних сервисов — подробнее. Есть готовый шаблон для настройки оповещений Zabbix.
TgMigrate Bot	Бот для переноса чатов из Telegram — подробнее. Дистрибутив с описанием и инструкция для пользователей бота доступны здесь.
Contacts Bot	Справочник контактов — подробнее.
Forwarder Bot	Автоматические пересылки сообщений по правилам — подробнее.
Sticker Bot	Бот для создания и редактирования созданных через него наборов стикеров. Также есть функция импорта статичных стикеров (без анимации) из Telegram. ⚠️ Чтобы импорт стикеров из Telegram работал, необходим доступ до серверов Telegram со стороны бот-сервера, на котором размещён Sticker Bot.
Jira Monitoring Bot	Интеграция обсуждений в eXpress с комментариями в Jira — подробнее
Календарь SmartApp	Интеграция с календарём — подробнее
Email SmartApp	Почтовый клиент — подробнее
Homescreen SmartApp	Главная страница с информацией о вашей компании — подробнее
Proxy SmartApp	Показывает внутренний веб-ресурс организации прямо в eXpress: корпоративный портал, дашборд, систему заявок, вики. Ресурс при этом остаётся внутри защищённой сети и не публикуется в интернет. Внутри вы работаете с сайтом так же, как в браузере.

Подробнее об остальных ботах и SmartApps, а также инструкции администраторам:

Вопросы по SmartApp «Почта»

Можно ли подключить несколько почтовых ящиков?

Да. Внутри Email SmartApp нажмите на свой аватар и добавьте аккаунт — переключаться между ящиками можно без выхода из приложения.

Почему уведомления приходят только о письмах во «Входящих»?

Приложение отслеживает новые письма в папке «Входящие». Если у вас настроены правила, раскладывающие письма по другим папкам, уведомлений о них не будет — это ожидаемое поведение.

Как отключить уведомления о новых письмах?

В самом приложении «Почта» нажмите на кнопку с тремя точками и выключите уведомления. Настройка общая для всех ваших устройств.

Почему не находится нужный адресат?

Поиск идёт по корпоративному каталогу вашей организации и по контактам, накопленным в почтовом ящике. Если человека нет ни там, ни там, введите его адрес полностью (и нажмите Enter) — адрес подставится.

Вопросы по SmartApp «Календарь»

Приходят ли напоминания о встречах из Календаря?

Уведомления о приближающихся событиях в приложении «Календарь» приходят от бота «Календарь».

Можно ли синхронизировать «Календарь» с календарём телефона?

Нет, это разные приложения. Но если один и тот же аккаунт (например, Яндекс) подключён и в календаре телефона, и в SmartApp, вы будете видеть одни и те же события.

Как забронировать переговорную?

Переговорные доступны, если календарь подключён к Exchange, — комнаты создаёт администратор на календарном сервере. Для других сервисов место встречи указывается вручную.

Остальные вопросы по ботам и SmartApps

Как установить бота или SmartApp?

Если вы корпоративный пользователь (и ваша организация обладает расширенной лицензией с поддержкой SmartApps), обратитесь в поддержку своей организации, чтобы заказать установку. См. Руководство по развёртыванию бота и SmartApps для администратора.

Где хранятся учётные данные SmartApps «Почта» и «Календарь»?

Пароли почтовых и календарных учётных записей хранятся на стороне корпоративного сервера в зашифрованном виде. Поэтому входить в SmartApps достаточно только на одном из ваших устройств.

Какие ограничения у Proxy SmartApp?

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

Проксируемый ресурс должен работать по протоколу HTTPS и разрешать встраивание. Сетевые папки (SMB, DFS, библиотеки SharePoint) через Proxy SmartApp не публикуются.

Почему я не вижу нужный SmartApp в каталоге?

Набор доступных SmartApps настраивает администратор вашей организации, в том числе индивидуально для групп сотрудников. Если приложение пропало после обновления — очистите кэш SmartApp «Каталог» через кнопку с тремя точками или выполните повторный вход.

Бот не отдаёт файл или отвечает ошибкой в чате с участниками разных серверов

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

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

Почему в сообщении от бота пропало упоминание

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

Почему SmartApp открывается на половину экрана?

Ширину окна SmartApp в веб- и десктоп-версии можно менять кнопкой в правом верхнем углу. Доступные варианты отображения задаёт администратор.

Можно ли изучить код готовых ботов и SmartApps?

Мы не предоставляем исходный код.

Платформа eXpress поддерживает создание собственных ботов и SmartApps. Создать бота или SmartApp можно самостоятельно, используя API BotX, либо заказать у поставщика eXpress.

Создание ботов и SmartApps

Обычные пользователи могут добавлять ботов и SmartApps на сервер?

Пользователь без доступа к консоли администратора не может добавить бота на сервер самостоятельно — для внедрения бота необходимо обращаться в поддержку своей организации.

Кто может создавать ботов и SmartApps?

Боты и SmartApps могут быть созданы:

• Командой разработки eXpress. Заявки на внедрение и доработку таких ботов и SmartApps делаются через аккаунт-менеджера со стороны eXpress или коммерческий отдел.
• Заказчиком самостоятельно с использованием API BotX. Описание API доступно по ссылкам ниже.
• Партнёрами заказчика. Заявки на доработку таких ботов делаются через поддержку организации-партнёра.

Есть конструктор ботов или аналог Bot Father из Telegram?

Нет, ботов необходимо создать и подключить к корпоративному серверу самостоятельно или на заказ.

Как устроен чат-бот и с чего начать разработку

Чат-бот в eXpress — это отдельный тип пользователя, за которым скрывается веб-приложение на сервере вашей организации. Для сотрудника бот выглядит как контакт и чат с ним; для платформы это HTTP-сервис, которому корпоративный сервер пересылает сообщения и от которого принимает ответы. Участников в этой схеме три.

Участник	Что делает
Приложение eXpress	Показывает бота как контакт. Всё, что пользователь пишет боту или нажимает в его сообщениях, уходит на корпоративный сервер как обычное сообщение.
BotX на корпоративном сервере CTS	Посредник между мессенджером и ботами. Доставляет боту сообщения HTTP-запросом и принимает от бота запросы на отправку сообщений, создание чатов, поиск пользователей.
Бэкенд бота	Веб-приложение на сервере организации, обычно docker-контейнер. Принимает команды от BotX, обращается к внутренним системам (Jira, 1С, почта) и отвечает через BotX. Его адрес администратор указывает при создании бота в консоли администратора.

Отсюда два API, которые важно не путать:

• Bot API реализует сам бот: адреса, на которые BotX присылает команды пользователей и системные события (POST /command), результаты отправки сообщений (POST /notification/callback) и запрос списка команд для меню в чате (GET /status). Версия Bot API задаётся в карточке бота в поле Версия протокола. Описание — HTTP(s) Bot API v4.
• BotX API предоставляет платформа: методы, которые бот вызывает, чтобы действовать от своего имени — отправить сообщение с кнопками, создать чат, найти пользователя, скачать файл. Описание — HTTP(s) BotX API, готовые запросы на типовые случаи — Примеры использования BotX API.

Что происходит, когда пользователь пишет боту?

Сообщение уходит на корпоративный сервер, BotX доставляет его боту запросом POST /command. Бот обязан за 5 секунд ответить, что принял команду, иначе пользователь увидит «Не удалось получить ответ от бота». Дальше бот работает сколько нужно и отвечает через BotX API; результат доставки приходит боту отдельным запросом. Галочки у сообщения пользователя показывают эти этапы: одна серая — отправлено, две серые — BotX получил, две синие — бот подтвердил приём. Две синие галочки означают, что бот ответил на запрос, а не то, что он выполнил задачу. Подробности — Разработка и отладка.

Оба направления защищены секретным ключом бота, который создаётся вместе с ботом в консоли администратора: BotX подписывает им каждый запрос к боту, а бот по нему получает токен для BotX API. Трафик между BotX и ботом по умолчанию идёт без TLS внутри сети организации; шифрование включается загрузкой сертификата на сервер и настройкой в карточке бота — Общее описание API.

С чего начать разработку бота?

1. Понять платформу: что такое корпоративные и региональные серверы, что бот знает о пользователях с других серверов, что означают галочки — Что такое чат-боты и SmartApp.
2. Решить, нужен ли боту собственный пользовательский интерфейс. Если да — это SmartApp, см. следующий подраздел.
3. Подготовить сервер: Linux, Docker, PostgreSQL, Redis, сетевой доступ к корпоративному серверу в обе стороны — Развертывание чат-бота, разделы «Предварительные условия» и «Системные требования».
4. Зарегистрировать бота в консоли администратора: Боты > Создать бота, указать имя, APP_ID, URL бэкенда и версию протокола, затем сохранить ID и Secret key — Подключение чат-бота. Кому бот доступен и что видит в групповых чатах, настраивается там же — Параметры чат-бота.
5. Реализовать Bot API и получить токен BotX API — Bot API, Bots API.
6. Не писать всё с нуля: для Python есть библиотека pybotx, шаблон бота async-box и примеры next-feature-bot и todo-bot — Общее описание API, разделы «Библиотеки» и «Примеры ботов»; исходный код — GitHub ExpressApp. Язык при этом любой: оба API — обычный HTTP с JSON.
7. Развернуть бота в Docker по инструкции Развертывание чат-бота и обновлять по Обновление образа приложения.

Что ещё умеет бот

• Кнопки под сообщением и клавиатура, виджеты из нескольких сообщений — Notifications API, Создание виджетов.
• Ссылка или QR-код, открывающий чат с ботом и сразу передающий ему команду — Ссылки на ботов с отправкой команды.
• Создание чатов, управление участниками и администраторами, закрепление сообщений, треды — Chats API.
• Поиск пользователей своего сервера по почте, логину или HUID — Users API.
• Приём и отправка файлов — Files API.
• История изменений платформы BotX по версиям — История изменений.

Как устроен SmartApp и с чего начать разработку

SmartApp — это чат-бот, у которого есть собственный интерфейс: одностраничное веб-приложение, которое открывается внутри eXpress. Всё, что сказано о ботах в предыдущем подразделе, относится и к SmartApp: у него тот же бэкенд-бот, тот же BotX и те же два API. Добавляется фронтенд и способ его доставить пользователю.

Часть SmartApp	Что это
Фронтенд	Веб-приложение на любом стеке (React, Vue, Angular), которое приложение eXpress показывает во встроенном окне: на Web и Desktop это iframe, на мобильных — WebView. С мессенджером фронтенд общается через библиотеку SmartApp SDK: контакты, чаты, файлы, защищённое хранилище, NFC и Bluetooth.
Бэкенд	Обычный чат-бот, у которого в консоли администратора заполнен блок SmartApp. Хранит статику фронтенда, обрабатывает его запросы, обращается к внутренним системам организации — Backend.
BotX на корпоративном сервере CTS	Посредник: фронтенд никогда не обращается к своему бэкенду напрямую. Запрос из интерфейса уходит через приложение eXpress в BotX, оттуда боту, и ответ возвращается тем же путём.

Какие бывают SmartApps?

Разработчик выбирает один из трёх видов по тому, откуда берётся фронтенд, и от этого зависит поведение приложения без сети — Виды SmartApp.

• С кешированием. Фронтенд собирается в архив (бандл), который приложение eXpress скачивает с бота и хранит на устройстве в зашифрованном виде. Открывается мгновенно и работает без сети. Самый частый выбор для приложений, написанных с нуля.
• Без кеширования. Фронтенд каждый раз запрашивается с бота, как обычный сайт. Не работает без сети, но умеет проксировать файлы из корпоративной сети.
• С проксированием. Во встроенном окне открывается уже существующий внутренний веб-ресурс организации, доступ к нему идёт через корпоративный сервер. Так публикуют готовые системы, не переписывая их. Ограничения — в подразделе Какие ограничения у Proxy SmartApp?

Как фронтенд общается с ботом?

Фронтенд вызывает метод SDK, приложение eXpress передаёт событие в BotX, BotX доставляет его боту как системное событие в POST /command, бот отвечает через BotX API, и ответ приходит во фронтенд. Этот обмен называется SmartApp RPC — Backend, раздел «Взаимодействие SmartApp frontend и backend»; методы со стороны фронтенда — Взаимодействие с ботом. Бот может и сам обратиться к пользователю: прислать push-уведомление или обновить счётчик на иконке приложения — Push-уведомления.

Как приложение eXpress показывает SmartApp — размер окна, закрепление на панели, предзагрузка, полноэкранный режим на мобильных, — бот сообщает манифестом, который отправляет на BotX — SmartApp API, раздел «Отправка SmartApp-манифеста». У SmartApp с кешированием есть и второй манифест, внутри бандла: он задаёт версию сборки и способ обновления — SmartApp c кешированием.

С чего начать разработку SmartApp?

1. Выбрать вид SmartApp — Виды SmartApp. Если задача — показать внутри eXpress уже существующую систему, обычно достаточно готового Proxy SmartApp из коллекции.
2. Спроектировать по плану из документации: способ аутентификации бота во внешней системе, спецификация запросов фронтенд ↔ бэкенд, проекты бэкенда и фронтенда, сборка и публикация — Разработка и отладка.
3. Подготовить сервер и зарегистрировать бота в консоли администратора так же, как для обычного бота, дополнительно заполнив блок SmartApp с App ID — Развертывание чат-бота/SmartApp.
4. Написать бэкенд: обычный бот, который дополнительно отдаёт статику фронтенда и обрабатывает события SmartApp — Backend.
5. Написать фронтенд: подключить SmartApp SDK, вызвать ready при запуске, учесть требования к сборке бандла — SmartApp SDK, SmartApp c кешированием.
6. Отладить: в веб-приложении eXpress есть режим отладки SmartApps, который открывает локальную сборку фронтенда вместо опубликованной; на iOS и Android доступна удалённая отладка через Safari и Chrome — Frontend.
7. Отправить манифест на BotX и развернуть бота; для SmartApp с проксированием дополнительно нужны поддомен корпоративного сервера и сертификат — Развертывание и обновление.

Что ещё умеет SmartApp

• Открываться по ссылке из чата или письма и получать параметры — Диплинки.
• Появляться в карточке контакта и в меню «Отправить в» — Ссылки в карточке контакта, Меню «Отправить в».
• Загружать файлы с устройства с выбором качества медиа и открывать файлы — Файлы, Работа с файлами.
• Хранить токены и настройки в защищённом хранилище на устройстве — Хранение данных на клиенте.
• Читать NFC-метки, работать с Bluetooth и геолокацией на мобильных — Устройства.
• Подстраиваться под тему и язык приложения — Внешний вид, Локализация.
• Пускать пользователя во внешнюю систему без пароля через SSO — Backend, раздел «Аутентификация в интегрируемых сервисах».

API BotX

О ботах в базе знаний:

• Общая информация о ботах
• Разработчику ботов

Документация по API BotX:

• Приветственная страница документации BotX
• Общее описание BotX
• HTTP(s) Bot API v4 — протокол отправки данных от BotX к боту (BotX → Bot). Версия протокола задаётся на странице редактирования бота в панели администратора, в поле Версия протокола.
• HTTP(s) BotX API — API сервиса BotX. Позволяет боту взаимодействовать с внутренними сервисами eXpress.

Документация по SmartApps:

• О SmartApps в базе знаний — разработчику

Репозиторий GitHub с библиотеками и примерами:

• ExpressApp

Используйте актуальный Android System WebView

Для корректной работы SmartApps в мобильном приложении для Android компонент операционной системы Android System WebView должен иметь актуальную версию. Очистите кэш приложения после обновления Android System WebView.

Бот не работает или работает неправильно — общие рекомендации

1. Определите, на какой платформе возникает проблема: веб/десктоп или мобильное приложение, и уточните версию приложения.
2. Проверьте, воспроизводится ли проблема на другой клиентской платформе.
3. Зафиксируйте шаги воспроизведения, сделайте скриншоты или запишите видео.

Проблема с ботом возникает на нескольких клиентских платформах?

Если проблема возникает на двух и более платформах (например, iOS и Android), возможные причины:

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

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

Администратору: сбор данных для диагностики чат-бота

CTS

eCTS

Для диагностики можно получить с корпоративного сервера:

• логи контейнера с ботом,
• логи контейнера botx,
• логи контейнера messaging.

Передайте в поддержку eXpress:

• описание проблемы, скриншоты, видео,
• файл .env со значениями переменных,
• собранные логи.

Проблема с ботом возникает на одной клиентской платформе?

Если проблема возникает только на одной платформе (веб/десктоп/iOS/Android), передайте в поддержку eXpress:

• описание проблемы,
• логи клиентского приложения.

При необходимости проблема будет заведена как баг и исправлена в будущем.

Ошибка авторизации бота “401 Unauthorized”

Откройте свойства бота в панели администратора корпоративного сервера, установите флажок Разрешить вход по устаревшему токену и сохраните изменения.

SmartApp не работает или работает неправильно — общие рекомендации

1. Попробуйте очистить кэш SmartApp через кнопку-троеточие на экране или на панели самого SmartApp.
2. Если проблема не решена, определите, на какой платформе она возникает (веб/десктоп/мобильное приложение), и уточните версию приложения.
3. Проверьте, воспроизводится ли проблема на другой платформе.
4. Зафиксируйте шаги воспроизведения, сделайте скриншоты или видео.
5. Соберите клиентские логи SmartApp.
6. Через администратора корпоративного сервера запросите:
   • логи SmartApp с сервера,
   • файл .env со значениями переменных.
7. Отправьте все данные в поддержку eXpress для дальнейшего анализа.

При необходимости проблема будет заведена как баг и исправлена в будущем.

Proxy SmartApp не открывает ресурс или показывает пустой экран

Учтите, что в веб-версии проксирование не работает — откройте приложение на компьютере или на телефоне.

Очистите кэш Proxy SmartApp: нажмите три точки в правом верхнем углу приложения и выберите очистку кэша, затем откройте его заново.

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

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

Администратору: сбор диагностики Proxy SmartApp

Соберите файл .env, серверные логи бота и SmartApp, клиентскую диагностику и HAR с десктопа.

Ошибка «Нет подключения к интернету» в SmartApp

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