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.

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 »

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

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.

8. 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.
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, gif and more.
Clients can display the results with vertical or horizontal scrolling, depending on the type of content:
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.
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.
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
@app – APP search
@vote – Search polls

9. 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: