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
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.
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.
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.
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:
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 »
potato.im/<bot_username>links or username search to find your bot.
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.
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.
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 »
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:
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).
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 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:
/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:
If multiple bots are in a group, it is possible to add bot usernames to commands in order to avoid confusion:
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.
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 »
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:
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.
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.
If your existing token is compromised or you lost it for some reason, use the /token command to generate a new one.
The remaining commands are pretty self-explanatory:
If you've got any questions, please check out our Bot FAQ »
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.
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.
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.
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.
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.
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.
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.
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.