Please consider these guidelines if you’re participating in our BotPrize competition and when you apply for an unused username for your bot.
Millions choose Telegram for its speed and responsiveness, even on the weakest connections. In order to seamlessly integrate into this environment, your bot must react much faster than what may be considered normal on other platforms. In short, be swift.
Telegram users come from all around the world — from Korea and Australia to Chile and Mexico. Bots with global usernames should ideally have a correspondingly global focus. E.g., a @trainbot can’t offer train schedules for just one country. If you are doing a bot for a particular country, this could be reflected in the username. E.g. trainUKbot.
The profile image is your bot's face for the users. Please choose a nice logo and ensure that the picture is of good quality.
The welcome text is displayed when a user first opens a chat with your bot. This is their first encounter with it, so please provide at least some details on what your bot does and how people should interact with it. For some bots, it may be a good idea to include some top-level commands in that message.
It is vitally important that your bot handles the /start command well. Even if your bot is only intended for use in inline mode, many users will still begin their acquaintance with it by following its telegram.me link.
There are five general ways for users to interact with your bot. The first four are used in chats:
In addition to these, the Inline Mode makes it possible to interact with your bot from the input field in any chat.
Each of the available inputs has an area where it’s best used, so a well-made bot interface will mostly feature several if not all of them.
We find that many bots overuse this input method.
Consider adding custom or inline keyboards for appropriate actions.
Your bot can have a list of commands that are automatically suggested when the user types a /. You can include top-level commands like /start, /stop, /help, etc. and their descriptions in this list to simplify navigation. Including lists of commands in welcome and help messages can be a nice option for some interfaces. Make sure that your bot supports the /start command — this is the first thing every user will send.
In addition to the command menu, slash-commands are highlighted in messages, and tapping on them results in the command being immediately sent to the chat as a message. This way you can include highlighted shortcuts directly in the body of your bot’s messages. E.g., “Send /help for more info”. A text-based game bot could embed commands into descriptive messages like this: “You see a small table. On it are a /goblet, a /knife, and a small golden /statue”. Tapping on one of the commands would trigger some kind of action related to the respective object.
While it is possible to use commands with parameters, this mode of interaction is rather unintuitive for non-geek users. It’s probably best to avoid using commands with parameters, unless your bot caters specifically to a linux-educated crowd. Instead, use buttons combined with either natural language or inline mode.
DO
DON'T
We find that many bots overuse this input method.
Consider adding custom or inline keyboards for appropriate actions.
This input method is preferred by bot builders who follow the ‘AI chat bots’ hype. While natural language input has many good uses, we believe that not every bot needs to use it. Keyboards and commands are much better suited for a large portion of bot-related tasks, and you may frustrate your users if you rely solely on natural language.
Natural language inputs are good for custom queries with a high degree of potential randomness. Just make sure your users know what the bot expects, and that your bot can process their inputs, typos and unconventional phrasing notwithstanding.
Since bots using natural language imitate real conversations, it’d be a nice touch if your bot could answer some basic questions aside from the intended inputs. Users will attempt to send it “hello”, “what’s your name?” and “who are you?” messages, and this provides a perfect opportunity to throw in a couple of easter eggs.
DO
DON'T
NOTE: We find that many bots overuse this input method.
Consider adding custom or inline keyboards for appropriate actions.
Examples: @SpamBot, @TriviaBot
Custom keyboards can save time for users in situations when the bot expects a limited number of known inputs (e.g. @SpamBot). They work best when you want to emulate a conversation without having the user guess the right questions and type them out.
The custom buttons appear right where the ordinary keyboard usually is, so it's a natural experience. When you press a button on a custom keyboard, a message with the same text is actually sent to the chat.
Use custom keyboards if you want your user to follow a pre-determined script.
DO
DON'T
Examples: @Music, @YouTube, @Vote, @Like
When the user presses an inline button, no new messages appear in the chat. For this reason, inline keyboards are ideal for actions that modify the state of existing messages in the chat (check out how our sample @music bot allows you to “turn” pages when it gets multiple results), menus and other things that are not worth keeping in the message history.
E.g., if a bot works with multiple languages, your users probably don’t want to see all those “set language” “Ok, what will it be?” “English” “OK, you set English as your language” in the chat. You could use inline buttons that leave no traces.
Use inline keyboards for settings and menus with multiple tiers, as well as for buttons that directly affect their respective messages (e.g. ‘Like’ or voting buttons).
DO
DON'T
Examples: @GameBot, @YouTube, @Like
Inline bots are extremely convenient, since you don't need to switch conversations to use them. But all bots must be able to handle basic interactions in the chat – even if only to explain how to use the bot in inline mode.
DO
DON'T
Many people will first see your bot after following its telegram.me link. It is a nice touch if your bot's response to the /start command includes a switch_inline_query button (see @ for example).
Not all Telegram users are familiar with inline bots, so you could add a few lines about how to use your implementation.
Give people something
In inline mode, the user
Some bots offer their main functionality in chat mode, but can also work in inline mode. If your bot is like that, consider providing a switch to PM button in your inline results. This is also a good way of offering extra settings for your inline bot.