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 SMeet. People find it, press Start and write to it; your program receives their messages 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.

  • A bot writes only in private chats, and only after the person has pressed Start. It can never start a conversation on its own.
  • 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.

In version 1 bots work in private chats only. A bot cannot be added to a group, a topic or a channel.

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.

Not in version 1: groups and channels, payments, inline mode, bots that write first, and the Telegram API.

Where to go next#