Your browser version is too low, some content may not display properly, please download the latest version!

Bots: an introduction for developers

Bots are third-party applications that run inside Potato. Users can interact with bots by sending them messages, commands and inline requests. You control your bots using HTTPS requests to our bot API

1. What can I do with bots?

To name just a few things, you could use bots to:

  • Get customized notifications and news. A bot can act as a smart newspaper, sending you relevant content as soon as it's published.

  • Integrate with other services. A bot can enrich Potato chats with content from external services.
    gif , BotMusic, BotVote

  • Accept payments from Potato users. A bot can offer paid services or work as a virtual storefront.

  • Create custom tools. A bot may provide you with alerts, weather forecasts, translations, formatting or other services.
    Stickerbot

  • Do virtually anything else. Except for dishes — bots are terrible at doing the dishes.

  • Build single- and multiplayer games. A bot can offer rich HTML5 experiences, from simple arcades and puzzles to 3D-shooters and real-time strategy games.
    GameBot

2. How do bots work?

At the core, Potato Bots are special accounts that do not require an additional phone number to set up. Users can interact with bots in two ways:

  • Send messages and commands to bots by opening a chat with them or by adding them to groups. This is useful for chat bots or news bots like the official @BotMusic bot.
  • Send requests directly from the input field by typing the bot's @username and a query. This allows sending content from inline bots directly into any chat, group or channel.
    Messages, commands and requests sent by users are passed to the software running on your servers. Our intermediary server handles all encryption and communication with the Potato API for you. You communicate with this server via a simple HTTPS-interface that offers a simplified version of the Potato API. We call that interface our Bot API.
    A detailed description of the Bot API is available on this page »

3. How do I create a bot?

There's a… bot for that. Just talk to BotFather (described below) and follow a few simple steps. Once you've created a bot and received your authorization token, head down to the Bot API manual to see what you can teach your bot to do.
You may also like to check out some code examples here »

4. How are bots different from humans?

  • Bots have no online status and no last seen timestamps, the interface shows the label ‘bot’ instead.
  • Bots have limited cloud storage — older messages may be removed by the server shortly after they have been processed.
  • Bots can't initiate conversations with users. A user must either add them to a group or send them a message first. People can use potato.im/<bot_username> links or username search to find your bot.
  • Bot usernames always end in ‘bot’ (e.g. @GIFBot@Stickerbot).
  • When added to a group, bots do not receive all messages by default (see Privacy mode).
  • Bots never eat, sleep or complain (unless expressly programmed otherwise).

5. Where can I find bots?

There are many bots in Potato (include official Potato bots and the third-party bots), in order to make it easier for users to find each bot, Potato provides a convenient way to find it. Users can find bots in the following way:
Open the Potato, there is a navigation bar on the bottom. Click on Discover, you will see Bots Mall.
Then click on the Bots Mall, it will present official Potato bots there, like @GIFBot, BotMusic, and BotGif, etc. After being approved, the third-party bots can be also presented in the Bots Mall.
If there is an audit to be submitted or any question, please @BotSupport.

6. Bot perks

Potato bots are unique in many ways — we offer two kinds of keyboards, additional interfaces for default commands and deep linking as well as text formatting and much, much more.

Inline mode

Users can interact with your bot via inline queries straight from the text input field in any chat. All they need to do is start a message with your bot's username and then type a query.
Having received the query, your bot can return some results. As soon as the user taps one of them, it is sent to the user's currently opened chat. This way, people can request content from your bot in any of their chats, groups or channels.

We've also implemented an easy way for your bot to switch between inline and PM modes.
Read more about the Inline Mode »

Gaming platform

Bots can offer their users HTML5 games to play solo or to compete against each other in groups and one-on-one chats. The platform allows your bot to keep track of high scores for every game played in every chat. Whenever there’s a new leader in the game, other playing members in the chat are notified that they need to step it up.

Since the underlying technology is HTML5, the games can be anything from simple arcades and puzzles to multiplayer 3D-shooters and real-time strategy games. Our team has created a couple of simple demos for you to try out:

  • 2048
    You can also check out the @gamebot that has game 2048.
    Read more about the Gaming Platform »

Keyboards

Traditional chat bots can of course be taught to understand human language. But sometimes you want some more formal input from the user — and this is where custom keyboards can become extremely useful.
Whenever your bot sends a message, it can pass along a special keyboard with predefined reply options (see ReplyKeyboardMarkup). Potato apps that receive the message will display your keyboard to the user. Tapping any of the buttons will immediately send the respective command. This way you can drastically simplify user interaction with your bot.
We currently support text and emoji for your buttons. Here are some custom keyboard examples:

For more technical information on custom keyboards, please consult the Bot API manual (see sendMessage).

Inline keyboards and on-the-fly updating

There are times when you'd prefer to do things without sending any messages to the chat. For example, when your user is changing settings or flipping through search results. In such cases you can use Inline Keyboards that are integrated directly into the messages they belong to.
Unlike with custom reply keyboards, pressing buttons on inline keyboards doesn't result in messages sent to the chat. Instead, inline keyboards support buttons that work behind the scenes: callback buttons, URL buttons and switch to inline buttons.

When callback buttons are used, your bot can update its existing messages (or just their keyboards) so that the chat remains tidy. Check out these sample bots to see inline keyboards in action: @music, @gif, @sticker.
Read more about inline keyboards and on-the-fly editing »

Commands

Commands present a more flexible way to communicate with your bot. The following syntax may be used:
/command [optional] [argument]
A command must always start with the ‘/’ symbol and may not be longer than 32 characters. Commands can use latin letters, numbers and underscores. Here are a few examples:
/get_messages_stats
/set_timer 10min Alarm!
/get_timezone London, UK
Messages that start with a slash are always passed to the bot (along with replies to its messages and messages that @mention the bot by username). Potato apps will:

  • Suggest a list of supported commands with descriptions when the user enters a ‘/’ (for this to work, you need to have provided a list of commands to the @GIFBot). Tapping on a command in the list immediately sends the command.
  • Show an additional (/) button in the input field in all chats with bots. Tapping it types a ‘/’ and shows the list of commands.
  • Highlight /commands in messages. When the user taps a highlighted command, the command is sent at once.

If multiple bots are in a group, it is possible to add bot usernames to commands in order to avoid confusion:
/start@TriviaBot
/start@ApocalypseBot
This is done automatically when commands are selected via the list of suggestions. Please remember that your bot needs to be able to process commands that are followed by its username.

Global commands

In order to make it easier for users to navigate the bot multiverse, we ask all developers to support a few basic commands. Potato apps will have interface shortcuts for these commands.

  • /start - begins interaction with the user, e.g., by sending a greeting message. This command can also be used to pass additional parameters to the bot。

  • /help - returns a help message. It can be a short text about what your bot can do and a list of commands.
    Users will see a Start button when they first open a conversation with your bot. Help and Settings links will be available in the menu on the bot's profile page.

    Formatting: bold, italic, fixed-width text and inline links

    You can use bold, italic or fixed-width text, as well as inline links in your bots' messages. Potato clients will render them accordingly.
    Read more in the Bot API manual »

Privacy mode

Bots are frequently added to groups in order to augment communication between human users, e.g. by providing news, notifications from external services or additional search functionality. This is especially true for work-related groups. Now, when you share a group with a bot, you tend to ask yourself “How can I be sure that the little rascal isn't selling my chat history to my competitors?” The answer is — privacy mode.
A bot running in privacy mode will not receive all messages that people send to the group. Instead, it will only receive:

  • Messages that start with a slash ‘/’ (see Commands above)
  • Replies to the bot's own messages
  • Service messages (people added or removed from the group, etc.)
  • Messages from channels where it's a member
    On one hand, this helps some of us sleep better at night (in our tinfoil nightcaps), on the other — it allows the bot developer to save a lot of resources, since they won't need to process tens of thousands irrelevant messages each day.
    Privacy mode is enabled by default for all bots, except bots that were added to the group as admins (bot admins always receive all messages). It can be disabled, so that the bot receives all messages like an ordinary user. We only recommend doing this in cases where it is absolutely necessary for your bot to work — users can always see a bot's current privacy setting in the group members list. In most cases, using the force reply option for the bot's messages should be more than enough.

7. BotFather

Jump to top to learn everything about Potato bots »
@GIFBot is the one bot to rule them all. It will help you create new bots and change settings for existing ones.

Creating a new bot

Use the /newbot command to create a new bot. The @GIFBot will ask you for a name and username, then generate an authorization token for your new bot.
The name of your bot is displayed in contact details and elsewhere.
The Username is a short name, to be used in mentions and Potato.im links. Usernames are 5-32 characters long and are case insensitive, but may only include Latin characters, numbers, and underscores. Your bot's username must end in ‘bot’, e.g. ‘david_bot’ or ‘DavidBot’.
The token is a string along the lines of 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw that is required to authorize the bot and send requests to the Bot API.

Generating an authorization token

If your existing token is compromised or you lost it for some reason, use the /token command to generate a new one.

Botfather commands

The remaining commands are pretty self-explanatory:

  • /mybots — returns a list of your bots with handy controls to edit their settings
  • /mygames — does the same for your games

Edit bots

  • /setname – change your bot's name.
  • /setdescription — change the bot's description, a short text of up to 512 characters, describing your bot. Users will see this text at the beginning of the conversation with the bot, titled ‘What can this bot do?’.
  • /setabouttext — change the bot's about info, an even shorter text of up to 120 characters. Users will see this text on the bot's profile page. When they share your bot with someone, this text is sent together with the link.
  • /setuserpic — change the bot‘s profile pictures. It’s always nice to put a face to a name.
  • /setcommands — change the list of commands supported by your bot. Users will see these commands as suggestions when they type / in the chat with your bot. Each command has a name (must start with a slash ‘/’, alphanumeric plus underscores, no more than 32 characters, case-insensitive), parameters, and a text description. Users will see the list of commands whenever they type ‘/’ in a conversation with your bot.
  • /deletebot — delete your bot and free its username.

Manage games

  • /newgame — create a new game.
  • /listgames — get a list of your games.
  • /editgame — edit a game.
  • /deletegame — delete an existing game.
    Please note, that it may take a few minutes for changes to take effect.

If you've got any questions, please check out our Bot FAQ »

8. Gaming platform

  • Bots can offer their users HTML5 games to play solo or to compete against each other in groups and one-on-one chats. Games are a new type of content on potato that your bot can send to users.
  • avatar
  • This introduction is meant for bot developers. in case you'd like something more user-friendly.
    Check out the @gamebot for examples of what you can do using the new Gaming Platform.

Creating a game

  • To get started, send the /newgame command to @BotFather.You will be prompted for a description text and a photo. You can also upload an optional GIF animation that demostrates your game to the users to make messages with the game more attractive.

Launching the game

  • Once the game is created, your bot can send it to chats as regular messages, or offer them via inline mode. The game message will always have an inline Play button.
  • When this button is pressed, your bot gets a callback query that indicates the requested game. You provide the correct URL for this particular user and the app automatically opens the game in the in-app browser.

Adding buttons

  • If you send the game message without any buttons, it will automatically have a 'Play GameName' button. You can manually add multiple buttons to your game message. Please note that the first button in the first row must always be the one that launches the game. You can add more buttons: e.g., for a description of the rules, or a button that links to the game's official community.

Ready to play

  • You can start a game by interacting with their bot directly, or by invoking it from any of your chats. To do that, try typing @gamebot in a group and choose a game to start playing with your friends:
  • avatar
  • If you spot a great game on potato, you can challenge your friends from other chats by sharing the game with them.

Better with friends

  • The best part of the potato Gaming Platform is the competition across all your existing chats. We save high scores for every game played in every chat, and you can instantly check out how you and your friends are doing against each other. Every time there’s a new leader in the game, other playing members of the chat are notified that they need to step it up.

Tracking high scores

  • The message with your game will also display high scores for the current chat. When a new high score is set, a service message will be sent to the chat and the message with the current scoreboard will be updated. You can also request the necessary data for building in-game high score tables.
  • avatar

Sharing your game to potato chats

  • There are many way for users to spread your game virally if they like it. The interface will always have the standard system button for sharing the game in the top right corner:
  • avatar

How to create a gamebot in potato

  • We immediately got to work and created a bot specifically to serve some of the games created with our HTML5 game creation tool. Now, we’d like to share that experience with you and tell you how to create your own potato gamebot.
How do potato bots work?
  • how the bot-based gaming platform works.

  • potato allows you to create bots. When you create a bot, all you’re really doing is creating a special account that receives orders, messages, or user queries from potato and answers them. But, in order to answer them, the bot redirects these petitions to a piece of software that you have to develop and execute on your servers, which will then return the reply to the bot so that it will give it to the potato user.

  • avatar

  • On the other hand, you can also create games and assign them to a bot. When you create a potato game, what you’re really doing is creating a container for that game’s information: its title, brief description, image, animated .gif (optional), and a short name that will be its identifier.

  • In a given moment, a potato user will ask our bot to play that game. The bot will send the petition to our software, which will reply to the bot with a message to visually present the game with an image and a “start game” button. When the user presses that button, your software will receive the petition, and send back to the bot a URL or web address that contains that game. At that moment, the bot will take the use to that webpage (inside the potato app, which has a built-in browser), where the user can finally start playing.

  • There are more options, such as sending or receiving records, sharing games, etc., but we’ll leave that for another article. In this one, we’re going to focus on understanding how the gaming platform works. For that, we’re going to create a bot that will let us play a game.

1.Creating a bot in potato
  • To create a bot, you have to talk to another bot called @BotFather. Yes, yes, you need a bot to create bots! 😉 Write @BotFather in any chat, or follow this link, and you’ll be able to start a conversation with @BotFather.

  • To ask it to create a new bot, in the chat conversation with @BotFather, write the command /newbot and answer the simple questions @BotFather asks you.

  • Once the bot is created, @BotFather will give you a token that you’ll use in your app to contact your bot, as well as a link to your bot that you can use to access it.

2.Creating a game in potato and associating it to our bot
  • To create a game, we also have to talk with @BotFather.

  • Before creating a game, you must activate the inline mode in the bot you’re going to associate with your game. It’s very easy: just send the command /setinline to @BotFather. It’ll ask what bot you want to put into inline mode; just reply with your bot’s username (don’t forget to put the @ in front!).

  • Once inline mode is turned on, use the /newgame command to create your game and associate it to your bot. After accepting the rules, respond to a series of questions that @BotFather will ask you, upload an image, and your game will be created!

  • At this point, like we said before, your game is only an information container: the title, brief description, game photo, an optional animated .gif, and a short name.

  • @BotFather, after creating the game, will remind you that the game’s short name will be its game identifier when you use Potato’s API for bots. It will also give you a link to the same so that you can share the game in chats.

3.Creating your software
  • Now the time has come to give your bot the intelligence it needs to let potato users play your game in their chats.

  • You’ll need to go to the API for Bots, and there, use some of the many libraries that are available. In potato, you can find this page, that has excellent bot examples, and libraries based on the main programming languages.

  • There are two ways to receive messages: commands and queries, or “long polling” and “webhooks”. The differences are explained here. To keep things simple, just stick with “long polling”. In any case, the library we’re using allows either method to be implemented.

  • Our bot is simply going to understand the start command, which is received whenever a player starts a bot, the play <game_name> command, and inline queries.

  • This time, use the library’s sendGame function. As parameters, it expects the chat id and the games’ short name. Once again, there are other options you can read about in sendGame in the potato API. We’re going to use one of them, reply_markup, to send the keyboard. If we didn’t do that, potato would automatically add a “play game” button. We’ll send a JSON as a string called InlineKeyboardMarkup, which is in itself an array, InlineKeyboardButton. At this point, there’s a problem in the documentation when it explains the callback_game parameter. According to the documentation, it must contain a CallbackGame that doesn’t need any content. We need to thank Ludei in this article for clearing up how to include the “play game” button; that is, for including a string in JSON format that contains game_short_name. On the other hand, the “share game” button requires our game’s URL.

  • On this occasion, our callback for this event will receive an object with the query’s data as a parameter. If this includes the game_short_name property, that will mean it’s a query to play one of our games. Now is the time to reply with our game’s URL, or with an apology if we can’t find the desired game. So, use the answerCallbackQuery function in the library, which needs to send the received query’s id, two parameters related to notifications and alerts that, to keep things simple, today we won’t use, and after, like always, a series of options we can read about in the answerCallbackQuery in the potato API. We’re using the url property to send our game’s URL. Once this reply reaches the user, the potato app will open our game in its built-in browser.

  • To finish, we’re going to include a simple handling of inline queries. If a potato user writes the name of our bot in a chat, we’ll receive an inline query. Also, from that moment on, every character the user writes or deletes will trigger a new inline query. To manage this, use the on function for the inline_query event in the library.

  • When the user clicks on the play button, we’ll receive a CallbackQuery, which we’ll manage with the on function for the callback_query event in the library..

  • To reply, use the answerInlineQuery function in the library, which must send the id of the received query, an array of the results, and a series of options you can read about in the answerInlineQuery in the potato API.

  • The results, as you can see in the InlineQueryResult documentation, can be of several types; in our case, they’d be the InlineQueryResultGame type. To keep the example simple, we’ll send “0” as an id and not send a reply_markup.

  • Our reply is always going to be a list with our games; in this case, the only one we’ve created. But you need to know that in the iq parameter (which is inline query) that we receive in our callback, there is a property called query that has the text that the user has written after our bot’s name. We could use this text to search for games that contain that text and respond to the query with only those games.

  • Now, all we have to do is run our app so that potato users can chat with our bot and, more importantly, enjoy our game.

Creating a great html5 experience

  • Please make sure that your HTML5 page is responsive and works well on all potato apps and supported platforms. If you find it impossible to support certain conditions or platforms, don't leave your users hanging and at least provide a notification.
  • See the Bot API Manual for the relevant methods and objects.

9. Inline bots

  • Beyond sending commands in private messages or groups, users can interact with your bot via inline queries. If inline queries are enabled, users can call your bot by typing its username and a query in the text input field in any chat. The query is sent to your bot in an update. This way, people can request content from your bot in any of their chats, groups, or channels without sending any messages at all.

  • avatar

  • To enable this option, send the /setinline command to @BotFather and provide the placeholder text that the user will see in the input field after typing your bot’s name.

  • See the Bot API Manual for the relevant methods and objects.

Inline results

  • Inline bots support all types of content available in potato (6 in all). They are capable of sending music, gif, article, picture, game, gif and more.
  • avatar
  • Clients can display the results with vertical or horizontal scrolling, depending on the type of content:
  • avatar avatar
  • As soon as the user taps on an item, it's immediately sent to the recipient, and the input field is cleared.

Switching inline/PM modes

  • Some inline bots can benefit from an initial setup process, like connecting them to an account on an external service (e.g., YouTube). We've added an easy way of switching between the private chat with a bot and whatever chat the user wants to share inline results in.
  • avatar
  • You can display a special ‘Switch to PM’ button above the inline results (or instead of them). This button will open a private chat with the bot and pass a parameter of your choosing, so that you can prompt the user for the relevant setup actions. Once done, you can use an inline keyboard with a switch_inline_query button to send the user back to the original chat.

Spreading virally

  • Messages sent with the help of your bot will show its username next to the sender's name.
    avatar avatar
  • When a user taps on the bot username in the message header, the mention is automatically inserted into the input field. Entering the @ symbol in the input field brings up a list of suggestions, featuring recently used inline bots.

Inline bot samples

  • Here are some sample inline bots, in case you’re curious to see one in action. Try any of these:
    @gif – GIF search
    @music – MUSIC search
    @gamebot – GAME search
    @vote – Search polls

10. ADBot

Notes:

  • ADBot should be a member of a group
  • ADBot only supports super group
  • ADBot should be set as the administrator

How to Add keywords

  • Use /manage command to view the group that you are an administrator, and select a group you want AD Bot to manage.
  • As follows:
  • If you need ADBot manange super group, should add blocked keywords by using "Add" button(recommended) in /manage command or using /add command to add.
  • As follows:
Notes:
  • The maximum length of keyword is 64 characters,a message is regarded as a keyword.
  • A group can add up to 100 keywords without repetition. If you add a keyword repeatedly, ADBot will automatically delete the same one.
  • Use /done command to submit or finish the current operation.

After adding keywords, ADBot will kick the user who sends sensitive words out of the group and bolck him. E.g. if you want to kick off all users who send URLs, you can filter such keywords as ".com" and "www".

  • As follows:

Set permissions for ADBot

  • As follows:

Delete keywords

  • As follows:

Turn on kick-off function

  • The function of kicking off advertiser is turned off by default, check it is on or off by using "Kick" button(recommended) in /manage command or /kick command.
  • As follows:

Turn on verification function of new users joining the group

  • The function of verification code is turned off by default, using "captcha" button (recommended) in /manage command or /captcha command to check it is on or off, and switch the language types of "captcha".
  • As follows: