Заказные боты и SmartApps | API BotX

Платформа 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