SMeetBot API
Sections and contents

Sections

On this page

SMeet Bot API

Overview

A SMeet bot is a program on your own server that talks to people in private chats, groups, topics and channels. Your program receives allowed events through the Bot API and answers.

What a bot is#

A bot is a special SMeet account with the Bot label next to its name. Its messages are written by a program, not by a person. The program runs on the author's server and uses the SMeet Bot API over HTTPS: it receives updates (messages, button presses, access changes) and calls methods such as sendMessage.

  • In a private chat a bot writes only after the person has pressed Start. In a group or channel it acts only after the owner installs it with explicit permissions.
  • The person stays in control: Stop or Block ends the bot's right to write at once, and the bot's code cannot undo it.
  • The Bot API is SMeet's own API. It is not compatible with the Telegram Bot API, and Telegram client libraries do not work with it.

Where bots work#

Every bot belongs to exactly one space: the public SMeet space or one organisation. The bot's token works only in that space, and people outside it do not see a bot of an organisation. Details are in Organisations and permissions.

Bots work in private chats, groups and their topics, and channels. Group installation and permissions are described in Groups, topics and channels.

Bots are supported in the SMeet web app and in SMeet for iOS and macOS: the bot profile, the Start button, the command menu after "/", buttons under messages and files. Other apps and older versions show a bot's messages as plain text without buttons, and sending a message to a bot may ask for an app update.

SMeet BotFather#

SMeet BotFather (@smeet_botfather) is the platform's own bot. Open it in any space where you may create bots, and it walks you through the rest:

  • /newbot creates a bot: a name for people and an address that ends with _bot;
  • /mybots lists your bots; the card of a bot shows its status, its queue and its delivery errors;
  • /setname, /setdescription and /setcommands edit the profile and the command menu;
  • /pause, /resume, /revoke and /deletebot pause, resume, revoke the token and delete.

BotFather never posts a token into the chat. For the token and for the delivery settings it shows a button that opens the protected My bots screen of your app. The full list of commands is in Managing your bot.

Where your code runs#

SMeet does not run bot code. Your program runs where you choose: a server, a container, a cloud function. SMeet keeps the queue of updates for up to 7 days and delivers them in one of two ways, chosen by the bot's owner:

Long polling (default)Webhook
Who connectsYour program calls getUpdatesSMeet sends an HTTPS POST to your address
What you needOutgoing HTTPS access to messenger.scrile.comA public HTTPS address with a valid certificate
Works behind NATYesNo

Both modes are fine for production. Receiving updates explains how to choose and how each mode guarantees that nothing is lost. The address of the Bot API is https://messenger.scrile.com/bot-api/v1.

How a conversation goes#

  1. A person opens the bot's profile, by search or by a link such as https://messenger.scrile.com/u/support_helper_bot. The profile shows the description, the author and a notice that the bot's developer processes the messages.
  2. The person presses Start. The bot receives a chat_access_changed update with the status started, followed by the person's message /start.
  3. The bot answers with sendMessage, with text and, if it wants, buttons.
  4. A press on a button reaches the bot as a callback_query. The bot confirms it with answerCallbackQuery and may edit its message.
  5. When the person presses Stop or Block, the bot receives chat_access_changed again and can no longer write to that chat.

What version 1 includes#

  • Text messages, commands and a command menu, replies to messages.
  • Buttons under a message: callback buttons and https links.
  • Editing the bot's own messages, including their buttons.
  • Photos and documents in both directions, checked by an antivirus scanner, when the installation has file support switched on.
  • Long polling and webhook delivery, the FAILED list with replay, diagnostics.
  • Groups, topics and channels with independent visibility, posting and moderation permissions.
  • Since 1.2.0: revisions of access, installations and messages in every update, conditional changes that check them together with the action, getChatContext, and the strict conditions mode (Conditional requests).
  • Since 1.2.0: the bot's Mini App, opened by a mini_app button, with the person's forms arriving as mini_app_submission (Mini Apps).

Not in version 1: payments, inline mode, unsolicited private chats, history access for group bots, and the Telegram API.

Where to go next#