Bots: An Introduction For Developers: Inline Requests Bot Api
Bots: An Introduction For Developers: Inline Requests Bot Api
Bots are third-party applications that run inside Telegram. Users can interact with bots by sending them messages,
commands and inline requests. You control your bots using HTTPS requests to our Bot API.
Integrate with other services. A bot can enrich Telegram chats with content
from external services.
Gmail Bot, GIF bot, IMDB bot, Wiki bot, Music bot, Youtube bot, GitHub
bot
Accept payments from Telegram users. A bot can offer paid services or
work as a virtual storefront. Read more »
Demo Shop Bot
Create custom tools. A bot may provide you with alerts, weather forecasts,
translations, formatting or other services.
Markdown bot, Sticker bot, Vote bot, Like bot
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, Gamee
Build social services. A bot could connect people looking for conversation partners based on common
interests or proximity.
Do virtually anything else. Except for dishes — bots are terrible at doing the dishes.
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
2. How do bots work?
At the core, Telegram 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.
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 Telegram API for you. You communicate with
this server via a simple HTTPS-interface that offers a simplified version of the Telegram API. We call that interface
our Bot API.
You may also like to check out some code examples here »
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
Bots never eat, sleep or complain (unless expressly programmed otherwise).
5. Bot perks
Telegram 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.
Check out this blog to see a sample inline bot in action. You can also try the
@sticker and @music bots to see for yourself.
\
We've also implemented an easy way for your bot to switch between inline and PM modes.
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
Payments platform
You can use bots to accept payments from Telegram users around the world.
From the users' perspective the system is completely seamless. Your bot sends a
specially formatted invoice message. Such messages feature a photo and
description of the product along with a prominent Pay button. Tapping this button
opens a special payment interface right in the Telegram app.
The user enters the necessary info, choose one of their saved cards or enter a new
one (Telegram also supports Apple Pay and Android Pay) — and pay for your
product. Here's what the process may look like:
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
Read more about the Payments Platform »
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.
0:00
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
\
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:
Math Battle
Lumberjack
Corsairs
You can also check out the @gamee bot that has more than 20 games.
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
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). Telegram 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).
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
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, @vote, @like.
Commands
Commands present a more flexible way to communicate with your bot. The following syntax may be used:
/command
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
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). Telegram 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 BotFather). 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.
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
\\
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. Telegram apps will have interface shortcuts for these commands.
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
/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 (see Deep linking)
/help - returns a help message. It can be a short text about what your bot can do and a list of commands.
/settings - (if applicable) returns the bot's settings for this user and suggests commands to edit these settings.
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.
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
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:
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 (the bot
will need to be re-added to the group for this change to take effect). 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.
Deep linking
Telegram bots have a deep linking mechanism, that allows for passing additional parameters to the bot on startup. It
could be a command that launches the bot — or an auth token to connect the user's Telegram account to their
account on some external service.
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
Each bot has a link that opens a conversation with it in Telegram — https://t.me/<bot username> . You can
add the parameters start or startgroup to this link, with values up to 64 characters long. For example:
https://t.me/triviabot?startgroup=test
A-Z , a-z , 0-9 , _ and - are allowed. We recommend using base64url to encode parameters with binary and
other types of content.
Following a link with the start parameter will open a one-on-one conversation with the bot, showing a START button
in the place of the input field. If the startgroup parameter is used, the user is prompted to select a group to add the
bot to. As soon as a user confirms the action (presses the START button in their app or selects a group to add the
bot to), your bot will receive a message from that user in this format:
/start PAYLOAD
PAYLOAD stands for the value of the start or startgroup parameter that was passed in the link.
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
Some bots need extra data from the user to work properly. For example, knowing the user's location helps provide
more relevant geo-specific results. The user's phone number can be very useful for integrations with other services,
like banks, etc.
Bots can ask a user for their location and phone number using special buttons. Note that both phone number and
location request buttons will only work in private chats.
\
When these buttons are pressed, Telegram clients will display a confirmation alert that tells the user what's about to
happen.
6. BotFather
Jump to top to learn everything about Telegram bots »
BotFather is the one bot to rule them all. It will help you create new bots and change settings for existing ones.
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
Use the /newbot command to create a new bot. The BotFather will ask you for a name and username, then
generate an authorization token for your new bot.
The Username is a short name, to be used in mentions and t.me 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. 'tetris_bot' or 'TetrisBot'.
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
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
‘/’, 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.
Edit settings
Manage games
Please note, that it may take a few minutes for changes to take effect.
Status alerts
Millions choose Telegram for its speed. To stay competitive in this environment, your bot also needs to be
responsive. In order to help developers keep their bots in shape, Botfather will send status alerts if it sees something
is wrong.
We will be checking the number of replies and the request/response conversion rate for popular bots (~300 requests
per minute: but don't write this down as the value may change in the future). If we get abnormally low readings, you
will receive a notification from Botfather.
Responding to alerts
By default, you will only get one alert per bot per hour. Each alert has the following buttons:
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
Fixed. Use this if you found an issue with your bot and fixed it. If you press the fix button, we will resume
sending alerts in the regular way so that you can see if your fix worked within 5-10 minutes instead of having to
wait for an hour.
Support. Use this to open a chat with @BotSupport if you don't see any issues with your bot or if you think the
problem is on our side.
Mute for 8h/1w. Use this if you can't fix your bot at the moment. This will disable all alerts for the bot in
question for the specified period of time. We do not recommend using this option since your users may migrate
to a more stable bot. You can unmute alerts in your bot's settings via Botfather.
Monitored issues
We will currently notify you about the following issues:
1.
Too few **private messages** are sent compared to previous weeks: **{value}**
Your bot is sending much fewer messages than it did in the previous weeks. This is useful for newsletter-style bots
that send out messages without prompts from the users. The larger the value, the more significant the difference.
2.
Your bot is not replying to all messages that are being sent to it (the request/response conversion rate for your bot
was too low for at least two of the last three 5-minute periods). To provide a good user experience, please respond
to all messages that are sent to your bot. Respond to message updates by calling send… methods (e.g.
sendMessage).
3.
Your bot is not replying to all inline queries that are being sent to it, calculated in the same way as above. Respond
to inline_query updates by calling answerInlineQuery.
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD
4.
Your bot is not replying to all callback queries that are being sent to it (with or without games), calculated in the
same way as above. Respond to callback_query updates by calling answerCallbackQuery.
Please note that the status alerts feature is still being tested and will be improved in the future.
That's it for the introduction. You are now definitely ready to proceed to the BOT API MANUAL.
If you've got any questions, please check out our Bot FAQ »
Create PDF in your applications with the Pdfcrowd HTML to PDF API PDFCROWD