Custom Bots & Smart Apps | BotX API

You can create your own bot or SmartApp yourself using the BotX API or order one from the eXpress vendor.

Creating Bots & SmartApps

Can Regular Users Add Bots and SmartApps to the Server?

No, you cannot. A user without access to the administrator console can't add a bot to the server on their own. To add a bot, contact your organization's support team.

Who Can Create Bots and SmartApps?

The following can create a bot or SmartApp:

• The eXpress development team. To implement or modify such a bot or SmartApp, contact your eXpress account manager or the sales department.
• The customer does this independently via the BotX API. API documentation is available via the links below.
• The customer's partners. To modify such a bot, contact the partner organization's support team.

Is There a Bot Builder or an Analogue of Telegram's Bot Father?

No, you cannot. Bots must be created and connected to the corporate server on your own or through a custom development order.

How a Chatbot Works and Where to Start Development

A chatbot in eXpress is a separate user type backed by a web application on your organization's server. An employee sees a bot as a contact and a chat with it. For the platform, a bot is an HTTP service: the corporate server forwards messages to it and receives responses from it. There are three participants in this scheme.

Participant	What It Does
eXpress app	Shows the bot as a contact. Everything the user writes to the bot or taps in its messages goes to the corporate server as a regular message.
BotX on the corporate server CTS	The intermediary between the messenger and bots. Delivers messages to the bot via HTTP requests and receives requests from the bot to send messages, create chats, and search for users.
Bot backend	A web application on the organization's server, usually a Docker container. Receives commands from BotX, communicates with internal systems (Jira, 1C, email), and responds through BotX. Its address is specified by the administrator when creating the bot in the admin console.

Hence two different APIs:

• Bot API is implemented by the bot itself: the addresses to which BotX sends user commands and system events (POST /command), message delivery results (POST /notification/callback), and a request for the list of commands for the chat menu (GET /status). The Bot API version is set in the bot card in the Protocol version field.
• BotX API is provided by the platform: the methods the bot calls to act on its own behalf — send a message with buttons, create a chat, find a user, download a file.

What Happens When a User Writes to the Bot?

The message goes to the corporate server, and BotX delivers it to the bot with a POST /command request. The bot must reply within 5 seconds that it has accepted the command, otherwise the user will see “Failed to get a response from the bot”. Then the bot works for as long as it needs and responds via the BotX API; the delivery result comes to the bot in a separate request. The check marks on a user's message show these stages: one gray means sent, two gray mean BotX received it, and two blue mean the bot confirmed receipt. Two blue check marks mean that the bot has responded to the request. They do not report on the completion of the task.

Both directions are protected by the bot secret key. It is created together with the bot in the admin console. BotX uses it to sign every request to the bot, and the bot uses it to obtain a token for the BotX API. By default, traffic between BotX and the bot goes without TLS within the organization's network. To enable encryption, upload a certificate to the server and configure the bot card.

Where to Start Bot Development?

1. Understand the platform: what corporate and regional servers are, what the bot knows about users from other servers, and what the checkmarks mean.
2. Decide whether the bot needs its own user interface. If yes, it is a SmartApp — see the next subsection.
3. Prepare the server: Linux, Docker, PostgreSQL, Redis, and network access to the corporate server in both directions.
4. Register the bot in the admin console: Bots > Create bot, specify the name, APP_ID, backend URL, and protocol version, then save the ID and Secret key. Who the bot is available to and what it sees in group chats is configured in the same place.
5. Implement the Bot API and obtain a BotX API token.
6. Do not write everything from scratch: for Python there is the pybotx library, the async-box bot template, and the next-feature-bot and todo-bot examples; source code — GitHub ExpressApp. The language can be any: both APIs are plain HTTP with JSON.
7. Deploy the bot in Docker.

What Else the Bot Can Do

• Buttons under a message and a keyboard, widgets made of several messages.
• A link or QR code that opens a chat with the bot and immediately sends it a command.
• Creating chats, managing participants and administrators, pinning messages, threads.
• Searching for users on its own server by email, login, or HUID.
• Receiving and sending files.

How a SmartApp Works and Where to Start Development

A SmartApp is a chatbot that has its own interface: a single-page web application that opens inside eXpress. Everything said about bots in the previous subsection also applies to a SmartApp: it has the same backend bot, the same BotX, and the same two APIs. What is added is a frontend and a way to deliver it to the user.

SmartApp Part	What It Is
Frontend	A web application on any stack (React, Vue, Angular) that the eXpress app shows in an embedded window: on Web and Desktop this is an iframe, on mobile — a WebView. The frontend communicates with the messenger through the SmartApp SDK library: contacts, chats, files, secure storage, NFC, and Bluetooth.
Backend	A regular chatbot whose SmartApp block is filled in in the admin console. Stores the frontend static files, processes its requests, and communicates with the organization's internal systems.
BotX on the corporate server CTS	The intermediary: the frontend never calls its backend directly. A request from the interface goes through the eXpress app to BotX, from there to the bot, and the response returns along the same path.

What Types of SmartApps Are There?

The developer selects one of three types based on where the frontend comes from. The type determines how the app works offline.

• Cache-based. The frontend is built into an archive (bundle) that the eXpress app downloads from the bot and stores on the device in encrypted form. It opens immediately and works offline. The most common choice for apps written from scratch.
• Non-cache-based. The frontend is requested from the bot every time, like a regular website. It does not work offline, but it can proxy files from the corporate network.
• Proxy-based. An existing internal web resource of the organization opens in the embedded window, with access through the corporate server. This is how ready-made systems are published without rewriting them. For limitations, see the What are the limitations of a Proxy SmartApp? subsection.

How Does the Frontend Communicate with the Bot?

The frontend calls an SDK method, and the eXpress app passes the event to BotX. BotX delivers it to the bot as a system event in POST /command. The bot responds via the BotX API, and the response arrives in the frontend. This exchange is called SmartApp RPC. The bot can also reach out to the user on its own: send a push notification or update the counter on the app icon.

The bot sends a manifest to BotX. It defines how the eXpress app displays the SmartApp: window size, docking to the panel, preloading, full-screen mode on mobile. A cache-based SmartApp also has a second manifest, inside the bundle: it sets the build version and the update method.

Where to Start SmartApp Development?

1. Choose the SmartApp type. If the goal is to show an existing system inside eXpress, a ready-made Proxy SmartApp from the collection is usually enough.
2. Plan the project: the method for authenticating the bot in the external system, the specification of frontend ↔ backend requests, backend and frontend projects, build and publication.
3. Prepare the server and register the bot in the admin console in the same way as for a regular bot, additionally filling in the SmartApp block with the App ID.
4. Write the backend: a regular bot that additionally serves the frontend static files and processes SmartApp events.
5. Write the frontend: connect the SmartApp SDK, call ready at startup, and follow the bundle build requirements.
6. Debug: the eXpress web app has a SmartApps debugging mode that opens a local frontend build instead of the published one. Remote debugging works on iOS and Android through Safari and Chrome.
7. Send the manifest to BotX and deploy the bot; for a proxy-based SmartApp, you additionally need a subdomain of the corporate server and a certificate.

What Else a SmartApp Can Do

• Open by a link from a chat or email and receive parameters.
• Appear in the contact card and in the “Send to” menu.
• Upload files from the device with media quality selection and open files.
• Store tokens and settings in secure storage on the device.
• Read NFC tags and work with Bluetooth and geolocation on mobile.
• Adapt to the app theme and language.
• Let the user into an external system without a password through SSO.

BotX API

GitHub repository with libraries and examples:

• ExpressApp (in Russian)