OpenSource/telegram-crawler
OpenSource/telegram-crawler
1
0
Fork 0
mirror of https://github.com/MarshalX/telegram-crawler.git synced 2024-12-29 15:59:13 +01:00
Code Issues Projects Releases Packages Wiki Activity

Update content of files

Browse source
This commit is contained in:
GitHub Action 2022-10-07 15:53:38 +00:00
parent 4e953f83bf
commit e40d0cc397
4 changed files with 2346 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

583
data/web/blogfork.telegram.org/bots/features.html Normal file
View file

@ -0,0 +1,583 @@
<!DOCTYPE html>
<html class="">
<head>
<meta charset="utf-8">
<title>Telegram Bot Features</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta property="description" content="This page describes individual bot elements in greater detail. For a general overview of bots, read the introduction to bots first.">
<meta property="og:title" content="Telegram Bot Features">
<meta property="og:image" content="https://blogfork.telegram.org/file/464001858/11318/ahAJjwERIX8.164875/ce1372cbf73e3ea94e">
<meta property="og:description" content="This page describes individual bot elements in greater detail. For a general overview of bots, read the introduction to bots first.">
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
<link href="/css/telegram.css?232" rel="stylesheet" media="screen">
<style>
</style>
</head>
<body class="preload">
<div class="dev_page_wrap">
<div class="dev_page_head navbar navbar-static-top navbar-tg">
<div class="navbar-inner">
<div class="container clearfix">
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
<ul class="nav navbar-nav">
<li><a href="//telegram.org/">Home</a></li>
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
<li class=""><a href="/api">API</a></li>
<li class=""><a href="/mtproto">Protocol</a></li>
<li class=""><a href="/schema">Schema</a></li>
</ul>
</div>
</div>
</div>
<div class="container clearfix">
<div class="dev_page">
<div id="dev_page_content_wrap" class=" ">
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/bots" >Telegram Bots</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/bots/features" >Telegram Bot Features</a></li></ul></div>
<h1 id="dev_page_title">Telegram Bot Features</h1>
<div id="dev_page_content"><!-- scroll_nav -->
<p>This page describes individual <strong>bot elements</strong> and <strong>features</strong> in detail. See also:</p>
<ul>
<li><a href="/bots">A General Bot Platform Overview</a></li>
<li><a href="/bots/api">Full API Reference for Developers</a></li>
</ul>
<h3><a class="anchor" name="what-features-do-bots-have" href="#what-features-do-bots-have"><i class="anchor-icon"></i></a>What features do bots have?</h3>
<ul>
<li><a href="#inputs"><strong>Inputs</strong></a><ul>
<li><a href="#inputs">Text</a></li>
<li><a href="#commands">Commands</a></li>
<li><a href="#keyboards">Buttons</a> </li>
</ul>
</li>
<li><a href="#interactions"><strong>Interactions</strong></a><ul>
<li><a href="#inline-requests">Inline</a></li>
<li><a href="#deep-linking">Deep Linking</a></li>
<li><a href="#attachment-menu">Attachment Menu</a></li>
</ul>
</li>
<li><a href="#payments"><strong>Integration</strong></a><ul>
<li><a href="#web-apps">Web Apps</a></li>
<li><a href="#payments">Payments</a></li>
<li><a href="#web-login">Web Login</a></li>
<li><a href="#html5-games">HTML5 Games</a></li>
<li><a href="#stickers">Stickers</a> </li>
</ul>
</li>
<li><a href="#language-support"><strong>Language Support</strong></a></li>
<li><a href="#bot-management"><strong>Bot Management</strong></a><ul>
<li><a href="#privacy-mode">Privacy Mode</a></li>
<li><a href="#status-alerts">Status Alerts</a></li>
<li><a href="#local-bot-api">Local API</a></li>
</ul>
</li>
<li><a href="#botfather"><strong>BotFather, creating and managing bots</strong></a></li>
</ul>
<hr>
<h3><a class="anchor" name="inputs" href="#inputs"><i class="anchor-icon"></i></a>Inputs</h3>
<p>Users can send <strong>messages of all types</strong> to bots, including text, files, locations, stickers, voice messages and even <a href="/bots/api#dice">dice</a> if they&#39;re feeling lucky. However, Telegram bots offer many other tools for building flexible interfaces tailored to your specific needs:</p>
<ul>
<li><a href="#commands">Commands</a> that are highlighted in messages and can be selected from a list after typing <code>/</code>.</li>
<li><a href="#keyboards">Keyboards</a> that replace the user&#39;s keyboard with predefined answer options.</li>
<li><a href="#inline-keyboards">Buttons</a> that are shown next to messages from the bot.</li>
</ul>
<p>For even more flexibility, <a href="#web-apps">Web Apps</a> support 100% custom interfaces with Javascript. </p>
<div>
<a href="/file/464001858/11318/ahAJjwERIX8.164875/ce1372cbf73e3ea94e" target="_blank"><img src="/file/464001858/11318/ahAJjwERIX8.164875/ce1372cbf73e3ea94e" title="Inputs" class="dev_page_image" width=70% /></a>
</div>
<blockquote>
<p><strong>Note:</strong> Telegram bots can support <a href="#language-support">multiple languages</a> that adapt to the users&#39; language settings in the app.</p>
</blockquote>
<h4><a class="anchor" name="commands" href="#commands"><i class="anchor-icon"></i></a>Commands</h4>
<p>A command is a simple <code>/keyword</code> that tells the bot what to do. Telegram apps will:</p>
<ul>
<li><strong>Highlight</strong> commands in messages. When the user taps a highlighted command, that command is immediately sent again.</li>
<li>Suggest a <strong>list of supported commands</strong> with descriptions when the user enters a <code>/</code> (for this to work, you need to have provided a list of commands to <a href="https://t.me/botfather">@BotFather</a> or via the <a href="/bots/api#setmycommands">appropriate API method</a>). Selecting a command from the list immediately sends it.</li>
<li>Show a <a href="#menu-button">menu button</a> containing all or some of a bot’s commands (which you set via <a href="https://t.me/botfather">@BotFather</a>).</li>
</ul>
<p>Commands must always start with the <code>/</code> symbol and contain <strong>up to 32 characters</strong>. They can use <strong>Latin letters</strong>, <strong>numbers</strong> and <strong>underscores</strong>, though simple lowercase text is recommended for a cleaner look. </p>
<p>Here are a few examples:</p>
<ul>
<li>/next </li>
<li>/cancel </li>
<li>/newlocation </li>
<li>/newrule </li>
</ul>
<p>Commands should be <strong>as specific as possible</strong> – for example <code>/newlocation</code> or <code>/newrule</code> <strong>is better</strong> than a <code>/new</code> command that then requires an additional parameter from the user like &quot;<em>location</em>“ or ”<em>rule</em>&quot;.</p>
<div>
<a href="/file/464001775/10227/HCr0XgSUHrg.119089/c17ff5d34fe528361e" target="_blank"><img src="/file/464001775/10227/HCr0XgSUHrg.119089/c17ff5d34fe528361e" title="Commands" class="dev_page_image"
width=44% /></a>
</div>
<blockquote>
<p>We require <strong>all developers</strong> to support several <a href="#global-commands">Global Commands</a> to make sure Telegram bots offer a consistent and user-friendly experience.</p>
</blockquote>
<h5><a class="anchor" name="command-scopes" href="#command-scopes"><i class="anchor-icon"></i></a>Command Scopes</h5>
<p>Your bot is able to <strong>show different commands</strong> to different users and groups – you can control this using <a href="/bots/api#botcommandscope">scopes</a>. For example, your bot could show additional commands to group admins or translate the list based on the user’s <a href="https://core.telegram.org/bots/api#user">language_code</a>.</p>
<blockquote>
<p>Keep in mind that Bot API <a href="https://core.telegram.org/bots/api#update">updates</a> <strong>will not contain any information</strong> about the scope of a command sent by the user – in fact, they may contain commands that don’t exist at all in your bot. Your backend should <strong>always</strong> verify that received commands are valid and that the user was authorized to use them regardless of scope.</p>
<p>Bots with privacy mode enabled will only receive commands in groups under special conditions, <a href="#privacy-mode">see here</a>.</p>
</blockquote>
<h4><a class="anchor" name="keyboards" href="#keyboards"><i class="anchor-icon"></i></a>Keyboards</h4>
<p>Bots are able to interpret free text input from users, but offering <strong>specific suggestions</strong> is often more intuitive – this is where <strong>custom keyboards</strong> can be extremely useful.</p>
<p>Whenever your bot sends a message, it can <strong>display a special keyboard</strong> with predefined reply options (see <a href="api#replykeyboardmarkup">ReplyKeyboardMarkup</a>). Telegram apps that receive the message will display your keyboard to the user. Using any of the buttons will immediately send the respective text. This way you can drastically <strong>simplify</strong> and <strong>streamline</strong> user interaction with your bot.</p>
<div>
<a href="/file/464001950/1191a/2RwpmgU-swU.123554/b50478c124d5914c23" target="_blank"><img src="/file/464001950/1191a/2RwpmgU-swU.123554/b50478c124d5914c23" title="Keyboards" class="dev_page_image" width=44% /></a>
</div>
<blockquote>
<p>Check out the <a href="/bots/api#replykeyboardmarkup">one_time_keyboard</a> parameter to automatically hide your bot&#39;s keyboard as soon as it&#39;s been used.</p>
</blockquote>
<h4><a class="anchor" name="inline-keyboards" href="#inline-keyboards"><i class="anchor-icon"></i></a>Inline Keyboards</h4>
<p>There are times when you&#39;d prefer to do things <strong>without sending any messages</strong> to the chat – like when a user is changing settings, toggling options or navigating search results. In such cases, you can use <a href="/bots/api#inlinekeyboardmarkup">Inline Keyboards</a> that are shown directly below their relevant messages.</p>
<p>Unlike with custom reply keyboards, pressing buttons on inline keyboards <strong>doesn&#39;t send messages to the chat</strong>. Instead, inline keyboards support buttons that can work behind the scenes or open different interfaces: <a href="/bots/api#inlinekeyboardbutton">callback buttons</a>, <a href="/bots/api#inlinekeyboardbutton">URL buttons</a>, <a href="/bots/api#inlinekeyboardbutton">switch-to-inline buttons</a>, <a href="/bots/api#inlinekeyboardbutton">game buttons</a> and <a href="/bots/api#inlinekeyboardbutton">payment buttons</a>. </p>
<div>
<a href="/file/464001863/110f3/I47qTXAD9Z4.120010/e0ea04f66357b640ec" target="_blank"><img src="/file/464001863/110f3/I47qTXAD9Z4.120010/e0ea04f66357b640ec" title="Inline Keyboard" class="dev_page_image" width=44% /></a>
</div>
<blockquote>
<p>To provide a <strong>better user experience</strong>, consider <a href="api#editmessagereplymarkup">editing your keyboard</a> when the user toggles a setting button or navigates to a new page – this is both <strong>faster</strong> and <strong>smoother</strong> than sending a whole new message and deleting the previous one.</p>
</blockquote>
<h4><a class="anchor" name="menu-button" href="#menu-button"><i class="anchor-icon"></i></a>Menu Button</h4>
<p>In all bot chats, a menu button appears near the message field. By default, tapping this button <strong>opens a menu</strong> that can hold some or all of a bot&#39;s commands, including a short description for each. Users can then <strong>select a command from the menu</strong> without needing to type it out.</p>
<p>You can set different texts of the menu button and its command descriptions for various <strong>individual users</strong> or <strong>groups of users</strong> – for example, showing translated text based on the user’s language, as explained <a href="#commands">here</a>.</p>
<div class="blog_video_player_wrap" style="max-width: 400px; margin: 20px auto 20px;">
<video class="blog_video_player tl_blog_vid_autoplay" onclick="videoTogglePlay(this)" autoplay="" loop="" controls="" muted="" poster="/file/464001581/11d85/f42u9c5Wncg.133752/b5a95b7f1221032d7d" style="max-width: 400px;" title="Bot Menu Button" alt="Video: Bot Menu Button">
<source src="/file/464001555/10fbd/jvTuV2Ke7WQ.1916669.mp4/a056de323645db409d" type="video/mp4">
</video>
</div>
<blockquote>
<p>Remember that you can also customize the text placeholder in the input field by setting the <code>input_field_placeholder</code> parameter.</p>
</blockquote>
<p>The <strong>menu button</strong> can alternatively be used to launch a <a href="#web-apps">Web App</a>.</p>
<h4><a class="anchor" name="global-commands" href="#global-commands"><i class="anchor-icon"></i></a>Global Commands</h4>
<p>To make basic interactions more uniform, we ask all developers to support a few <strong>basic commands</strong>. Telegram apps will have interface shortcuts for these commands.</p>
<ul>
<li>/start - begins the interaction with the user, like sending an introductory message. This command can also be used to pass additional parameters to the bot (see <a href="deep-linking">Deep Linking</a>).</li>
<li>/help - returns a help message, like a short text about what your bot can do and a list of commands.</li>
<li>/settings - (if applicable) shows the bot&#39;s settings for this user and suggests commands to edit them.</li>
</ul>
<p>Users will see a <strong>Start</strong> button the first time they open a chat with your bot. <strong>Help</strong> and <strong>Settings</strong> links will be available in the menu on the bot&#39;s profile page if you add them in <a href="https://t.me/botfather">@BotFather</a>.</p>
<hr>
<h3><a class="anchor" name="interactions" href="#interactions"><i class="anchor-icon"></i></a>Interactions</h3>
<p>In addition to sending commands and messages to the chat with the bot, there are several ways of interacting with them without opening any specific chat or group.</p>
<ul>
<li><a href="#inline-requests"><strong>Inline mode</strong></a> allows sending requests to bots right from the input field – from any chat on Telegram.</li>
<li><a href="#deep-linking"><strong>Deep linking</strong></a> allows special links that send certain parameters to the bot when opened.</li>
<li><a href="#attachment-menu"><strong>Attachment menu</strong></a> integration makes it possible to use bots from the attachment menu in chats.</li>
</ul>
<h4><a class="anchor" name="inline-requests" href="#inline-requests"><i class="anchor-icon"></i></a>Inline Requests</h4>
<p>Users can interact with your bot via <strong>inline queries</strong> straight from the message field <strong>in any chat</strong>. All they need to do is start a message with your bot&#39;s <em>@username</em> and enter a keyword.</p>
<p>Having received the query, your bot can return some results. As soon as the user selects one, it is sent to the <strong>relevant chat</strong>. This way, people can request and send content from your bot in any of their chats, groups or channels.</p>
<p>Remember that inline functionality has to be enabled via <a href="https://t.me/botfather">@BotFather</a>, or your bot will not receive inline <a href="api#update">Updates</a>.</p>
<div>
<a href="/file/464001466/10e4a/r4FKyQ7gw5g.134366/f2606a53d683374703" target="_blank"><img src="/file/464001466/10e4a/r4FKyQ7gw5g.134366/f2606a53d683374703" title="Inline Mode" class="dev_page_image" width=51%/></a>
</div>
<blockquote>
<p>Examples of inline bots include <a href="https://t.me/gif">@gif</a>, <a href="https://t.me/bing">@bing</a> and <a href="https://t.me/wiki">@wiki</a>.</p>
</blockquote>
<h4><a class="anchor" name="deep-linking" href="#deep-linking"><i class="anchor-icon"></i></a>Deep Linking</h4>
<p>Telegram bots have a deep linking mechanism that allows <strong>additional parameters</strong> to be passed to the bot on startup. It could be a command that launches the bot – or an authentication token to connect the user&#39;s Telegram account to their account on another platform.</p>
<p>Each bot has a link that <strong>opens a conversation</strong> with it in Telegram – <code>https://t.me/&lt;bot_username&gt;</code>. Parameters can be added directly to this link to let your bot work with additional information on the fly, without any user input.</p>
<blockquote>
<p>A-Z, a-z, 0-9, _ and - are allowed. We recommend using base64url to encode parameters with binary and other types of content. The parameter can be up to 64 characters long.</p>
</blockquote>
<p><strong>Private Chats</strong><br>In private chats, you can use the <code>start</code> parameter to automatically pass any value to your bot whenever a user presses the link. For example, you could use:</p>
<pre><code>https://t.me/your_bot?start=airplane</code></pre>
<p>When someone opens a chat with your bot via this link, you will receive:</p>
<pre><code>/start airplane</code></pre>
<p><strong>Groups</strong><br>In groups, you can add the parameter <code>startgroup</code> to this link. For example:</p>
<pre><code>https://t.me/your_bot?startgroup=spaceship</code></pre>
<p>Following a link with this parameter prompts the user to select a group to add the bot to – the resulting update will contain text in the form:</p>
<pre><code>/start@your_bot spaceship</code></pre>
<blockquote>
<p><a href="#web-apps">Web Apps</a> also support deep linking, for more information check out our <a href="/bots/webapps#adding-bots-to-the-attachment-menu">dedicated guide</a>.</p>
</blockquote>
<h4><a class="anchor" name="attachment-menu" href="#attachment-menu"><i class="anchor-icon"></i></a>Attachment Menu</h4>
<p>Certain bots can be added directly to a user’s <strong>attachment menu</strong> – giving them easy access to the bot in any chat. Currently, this option is restricted to certain <a href="Web-Bot-Doc">approved bots</a>, but may be expanded later.</p>
<div class="blog_video_player_wrap" style="max-width: 400px; margin: 20px auto 20px;">
<video class="blog_video_player tl_blog_vid_autoplay" onclick="videoTogglePlay(this)" autoplay="" loop="" controls="" muted="" poster="/file/464001491/11651/uwMWNdO29NE.215169/1b37285bbd8fc81244" style="max-width: 400px;" title="Attachment Menu" alt="Video: Bot Attachment Menu">
<source src="/file/464001177/11b03/ruSbBLQiLJ8.928268.mp4/d9ad95048d23f3cc3f" type="video/mp4">
</video>
</div>
<blockquote>
<p>Try adding <a href="https://t.me/durgerkingbot?startattach">@DurgerKingBot</a> to your attachment menu.</p>
</blockquote>
<hr>
<h3><a class="anchor" name="integration" href="#integration"><i class="anchor-icon"></i></a>Integration</h3>
<p>There are various ways of futher integrating bots with Telegram and other services.</p>
<ul>
<li>Use <a href="#web-apps">Web Apps</a> to replace any website.</li>
<li>Accept <a href="#payments">Payments</a> via dozens of integrated third-party payment providers.</li>
<li>Connect to Telegram using the <a href="#web-login">Web Login</a> functionality.</li>
<li>Create gaming bots by integrating <a href="#html5-games">HTML5 Games</a>.</li>
<li>Help users create and manage <a href="#stickers">Telegram Stickers</a>.</li>
</ul>
<h3><a class="anchor" name="web-apps" href="#web-apps"><i class="anchor-icon"></i></a>Web Apps</h3>
<p>Bots can easily process <strong>complex inputs</strong> of any kind and <strong>dynamic interaction flows</strong> via <a href="webapps">Web Apps</a>. With this unique feature, you can develop any number of flexible, streamlined interfaces in <strong>JavaScript</strong>.</p>
<blockquote>
<p>Web Apps are covered in detail in our <a href="webapps">dedicated guide</a> – you should read it carefully to learn the wide variety of features they can offer.</p>
</blockquote>
<div class="blog_video_player_wrap" style="max-width: 400px; margin: 20px auto 20px;">
<video class="blog_video_player tl_blog_vid_autoplay" onclick="videoTogglePlay(this)" autoplay="" loop="" controls="" muted="" poster="/file/464001434/100bf/eWprjdgzEbE.100386/644bbea83084f44c8f" style="max-width: 400px;" title="Attachment Menu" alt="Video: Bot Attachment Menu">
<source src="/file/464001679/11aa9/KQx_BlPVXRo.4922145.mp4/c65433c8ac11a347a8" type="video/mp4">
</video>
</div>
<p>If you develop a <strong>Web App</strong>, be sure to follow our <a href="webapps#design-guidelines">design guidelines</a> – you&#39;ll want your custom interface to <strong>seamlessly integrate</strong> into the app to provide users the best possible experience.</p>
<h3><a class="anchor" name="payments" href="#payments"><i class="anchor-icon"></i></a>Payments</h3>
<p>Telegram bots can accept payments with a sleek, streamlined interface that collects all necessary data from the user. Telegram <strong>doesn&#39;t collect</strong> any payment data – like the user&#39;s credit card information – and sends it directly to one of the supported <a href="payments#supported-payment-providers">payment providers</a>.</p>
<p>Here is a <strong>quick start guide</strong> to implement payments:</p>
<ul>
<li>Pick a <a href="payments#supported-payment-providers">provider</a> and obtain the <a href="payments#getting-a-token">proper token</a> as well as a <strong>test token</strong> from the &quot;<strong>Stripe TEST MODE</strong>&quot; provider.</li>
<li>Implement payments via the <a href="api#payments">appropriate API methods</a>.</li>
<li>Test your implementation by using your <strong>test token</strong> along with a <a href="https://stripe.com/docs/testing#cards">test credit card</a>.</li>
</ul>
<p>Then, to issue an <strong>invoice</strong> and process the order flow:</p>
<ul>
<li><a href="api#sendinvoice">Send an invoice</a> to the user for the goods or services you are offering.</li>
<li>Validate the order and accept the checkout via <a href="api#answerprecheckoutquery">answerPreCheckoutQuery</a>.</li>
<li>Confirm the payment by checking for a <a href="api#successfulpayment">successful payment service message</a>.</li>
<li>Ship the goods or provide the services.</li>
</ul>
<p>A full and exhaustive guide, including live checklist, parameters and in-depth method descriptions is available <a href="bots/payments">here</a>. We <strong>strongly recommend</strong> that you read the full guide before going live.</p>
<div>
<a href="/file/464001393/101fc/SB_bFCLR0tg.130549/7ecf91aaa44737e8cb" target="_blank"><img src="/file/464001393/101fc/SB_bFCLR0tg.130549/7ecf91aaa44737e8cb" title="Payments" class="dev_page_image" width=50% /></a>
</div>
<blockquote>
<p>Telegram does not directly process the payments, does not store data about orders and does not collect any fees. Invoices are forwarded directly to the payment provider.<br>For this reason, disputes must be solved between the user, the bot developer and the payment provider. You can read more about this in the <a href="https://telegram.org/privacy#7-third-party-payment-services">Privacy Policy</a>.</p>
</blockquote>
<h3><a class="anchor" name="web-login" href="#web-login"><i class="anchor-icon"></i></a>Web Login</h3>
<p>Telegram offers a <strong>flexible</strong>, <strong>lightweight</strong> and <strong>free</strong> framework to authenticate users on any website and app. This can be used to bridge your platform with Telegram, providing a smooth experience to your users. You can also freely rely on this framework to implement a <strong>fast</strong> and <strong>signup-free</strong> login on your site, regardless of its connection to Telegram.</p>
<h4><a class="anchor" name="widgets" href="#widgets"><i class="anchor-icon"></i></a>Widgets</h4>
<p>The Telegram login widget is a <strong>simple and secure way to authorize users</strong> on your website.</p>
<ol>
<li>Choose a bot – ideally its name and profile pic <strong>should match</strong> the website title and logo.</li>
<li>Use the <code>/setdomain</code> command in <a href="https://t.me/botfather">@BotFather</a> to pair the bot with your website domain. </li>
<li>Configure your widget using <a href="/widgets/login#widget-configuration">our dedicated tool</a> and embed it on your website.</li>
</ol>
<h4><a class="anchor" name="inline-login" href="#inline-login"><i class="anchor-icon"></i></a>Inline Login</h4>
<p>When users open your website via an <strong>inline button</strong>, you can use the <a href="/bots/api#loginurl">login_url</a> parameter as an alternative to login widgets. This way, you&#39;ll be able to <a href="https://telegram.org/blog/privacy-discussions-web-bots#meet-seamless-web-bots">seamlessly authorize</a> them on your website or app before the page even loads.</p>
<div>
<a href="/file/464001287/105ea/23bO4ntH4tc.43741/c9624e36c3462b6540" target="_blank"><img src="/file/464001287/105ea/23bO4ntH4tc.43741/c9624e36c3462b6540" width=50% title="Login Widget" class="dev_page_image" /></a>
</div>
<blockquote>
<p>Make sure to review our <a href="/widgets/login#checking-authorization">guide</a> on authenticating the received data as well as our <a href="https://gist.github.com/anonymous/6516521b1fb3b464534fbc30ea3573c2">sample code</a>.</p>
</blockquote>
<h3><a class="anchor" name="html5-games" href="#html5-games"><i class="anchor-icon"></i></a>HTML5 Games</h3>
<p>Bots can serve as <strong>standalone gaming platforms</strong> – with our <a href="api#games">HTML5 Gaming API</a> you can develop multiplayer or single-player games and let your users have fun comparing <strong>ranks</strong>, <strong>scores</strong> and much more.</p>
<p>To get started, follow these simple steps:</p>
<ul>
<li>Send the <code>/newgame</code> command to <a href="https://t.me/botfather">@BotFather</a></li>
<li>Provide a <strong>description text</strong>, an <strong>image</strong> or an <strong>optional gif</strong> to showcase its gameplay</li>
<li>Send the game to users via the <a href="api#sendgame">sendGame</a> method or via an <a href="api#inlinequeryresultgame">inline query</a></li>
<li>When someone wants to play, you&#39;ll receive the appropriate <code>game_short_name</code> in a <a href="api#callbackquery">CallbackQuery</a></li>
<li>To launch the game, provide the <strong>HTML5 Game URL</strong> as the <code>url</code> param of <a href="api#answercallbackquery">answerCallbackQuery</a></li>
</ul>
<p>Then, to handle <strong>highscores</strong>:</p>
<ul>
<li>Use <a href="api#setgamescore">setGameScore</a> to post high scores in the chat with the game</li>
<li>Use <a href="api#getgamehighscores">getGameHighScores</a> to get in-game high score tables</li>
</ul>
<p>You can also <strong>embed a share button</strong> within your game, play around with <strong>custom inline buttons</strong>, <strong>URL parameters</strong> and much more. To get a better idea, make sure to check out:</p>
<ul>
<li><a href="games">HTML5 Games Manual</a></li>
<li><a href="api#games">HTML5 Games Bot API Docs</a></li>
</ul>
<div>
<a href="/file/464001558/11b92/y_Fu9QQWtj0.141959/dc9db48f66800bf271" target="_blank"><img src="/file/464001558/11b92/y_Fu9QQWtj0.141959/dc9db48f66800bf271" title="Games" width=50% class="dev_page_image" /></a>
</div>
<blockquote>
<p>Check out <a href="https://t.me/gamebot">@GameBot</a> and <a href="https://t.me/gamee">@gamee</a> for examples of what you can do using our Gaming Platform.</p>
</blockquote>
<h3><a class="anchor" name="stickers" href="#stickers"><i class="anchor-icon"></i></a>Stickers</h3>
<p><a href="https://core.telegram.org/stickers">Stickers</a> are a distinctive Telegram feature used by millions of users to share artwork every day. Stickers take many forms – ranging from <strong>basic images</strong> to smooth <strong>vector animations</strong> and high-detail <strong>.WEBM videos</strong>.</p>
<p>All these formats are supported by our <a href="api#stickers">Bot API</a>, which allows bots to <strong>create</strong>, <strong>edit</strong>, <strong>delete</strong> and <strong>share</strong> new sticker packs on the fly. Telegram&#39;s <a href="https://core.telegram.org/import-stickers">Import API</a> lets users <strong>migrate packs</strong> from other platforms and sticker apps.</p>
<p>To create a <strong>new sticker pack</strong>, follow these simple steps:</p>
<ul>
<li><strong>Upload</strong> a new sticker file via <a href="api#uploadstickerfile">uploadStickerFile</a>. Repeat for all the stickers in the set. You will use the returned <a href="api#file">files</a> in the next step, so keep them around.</li>
<li><strong>Create</strong> a new sticker pack via <a href="api#createnewstickerset">createStickerSet</a>. Attach the <a href="api#file">files</a> you collected in <strong>step 1</strong> and remember to only specify <strong>one</strong> of the three avaiable fields – <code>png_sticker</code>, <code>tgs_sticker</code> and <code>webm_sticker</code> – depending on which sticker format you uploaded.</li>
<li><strong>Complete</strong> the pack by adding each remaining sticker in sequence via <a href="api#addstickertoset">addStickerToSet</a>.</li>
</ul>
<blockquote>
<p>Once you&#39;re done, don&#39;t forget to check out our <a href="api#stickers">remaining sticker methods</a> to find out how to <a href="api#setstickersetthumb">edit</a>, <a href="api#deletestickerfromset">delete</a> and even <a href="api#setstickerpositioninset">reorder</a> your pack.<br>Note that these methods will only work on packs <strong>created by the bot that is calling them</strong>.</p>
</blockquote>
<h3><a class="anchor" name="language-support" href="#language-support"><i class="anchor-icon"></i></a>Language Support</h3>
<p>Bots can tailor their interfaces to <strong>support multiple languages</strong> – updating inputs and information on the fly. A user’s in-app <a href="/bots/api#user">language_code</a> is included in every relevant <a href="api#Update">update</a> as an <a href="https://en.wikipedia.org/wiki/IETF_language_tag">IETF language tag</a>, allowing bots to adapt accordingly. </p>
<p>We recommend that you follow our guidelines to provide <strong>the best user experience</strong>.</p>
<ul>
<li>Your interfaces, texts and <a href="api#answerinlinequery">inline results</a> should adapt seamlessly to the <em>language_code</em>, without user intervention.</li>
<li>Connected <a href="/bots/webapps">WebApps</a> will receive the user&#39;s <em>language_code</em> – your HTML page should account for it.</li>
<li><a href="html5-games">HTML5 Games</a> can obtain language information if you specify it as a <a href="games#using-url-parameters">URL parameter</a>. You can generate this parameter from the <em>language_code</em> field in the <a href="api#User">User</a> object served with the initial game <a href="api#callbackquery">CallbackQuery</a>.</li>
<li>Command lists can also be specified for individual languages – more on this <a href="#commands">here</a>.</li>
</ul>
<div class="blog_video_player_wrap" style="max-width: 400px; margin: 20px auto 20px;">
<video class="blog_video_player tl_blog_vid_autoplay" onclick="videoTogglePlay(this)" autoplay="" loop="" controls="" muted="" poster="/file/464001822/10cd0/EvtvjnhA-kA.132475/e285952b505535d85a" style="max-width: 400px;" title="Language Support" alt="Video: Language Support">
<source src="/file/464001083/105cd/NF4ViAHfTJc.3601652.mp4/0fd787953c11a6371d" type="video/mp4">
</video>
</div>
<blockquote>
<p>The <em>language_code</em> is an <strong>optional field</strong> – it could be empty.<br>If you target the general public, your code should always fall back to either the last recorded language tag or English (in this order) when the field is missing for a specific user. </p>
</blockquote>
<hr>
<h3><a class="anchor" name="bot-management" href="#bot-management"><i class="anchor-icon"></i></a>Bot Management</h3>
<h4><a class="anchor" name="privacy-mode" href="#privacy-mode"><i class="anchor-icon"></i></a>Privacy Mode</h4>
<p>Bots are frequently added to groups to perform basic tasks or assist moderators – like automatically posting company announcements or even celebrating birthdays. By default, <strong>all bots</strong> added to groups run in Privacy Mode and only see relevant messages and commands:</p>
<ul>
<li>Commands explicitly meant for them (e.g., <code>/command@this_bot</code>).</li>
<li>General commands (e.g. <code>/start</code>) if the bot was the last bot to send a message to the group.</li>
<li>Inline messages sent <a href="api#inline-mode">via</a> the bot.</li>
<li>Replies to any messages implicitly or explicitly meant for this bot.</li>
</ul>
<p>All bots will also receive, <strong>regardless of privacy mode</strong>:</p>
<ul>
<li>All service messages.</li>
<li>All messages from private chats.</li>
<li>All messages from channels where they are a member.</li>
</ul>
<p>Privacy mode is <strong>enabled by default</strong> for all bots, except bots that were added to a group as admins (bot admins always receive <strong>all messages</strong>). 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 <strong>absolutely necessary</strong> for your bot to work. In most cases, using the force reply option for the bot&#39;s messages should be more than enough.</p>
<div>
<a href="/file/464001338/107af/JdbERa0BATg.62371/28977e9a96aed3860a" target="_blank"><img src="/file/464001338/107af/JdbERa0BATg.62371/28977e9a96aed3860a" title="Privacy Mode" class="dev_page_image" width=50%/></a>
</div>
<blockquote>
<p>This mode not only increases user privacy, but also makes the bot more efficient by reducing the number of inputs it needs to process. Users can always see a bot’s current privacy setting in the list of group members.</p>
</blockquote>
<h4><a class="anchor" name="status-alerts" href="#status-alerts"><i class="anchor-icon"></i></a>Status alerts</h4>
<p>Millions choose Telegram for its speed. To best benefit users, your bot also <strong>needs to be responsive</strong>. In order to help developers keep their bots in shape, <a href="https://t.me/botfather">@BotFather</a> will send <strong>status alerts</strong> if it sees something is wrong.</p>
<p>We check the number of replies and the <em>request/response</em> conversion rate for popular bots (~300 requests per minute, this value may change in the future). If your bot returns an <strong>abnormally low number</strong>, you will receive a notification from <a href="https://t.me/botfather">@BotFather</a>.</p>
<h5><a class="anchor" name="responding-to-alerts" href="#responding-to-alerts"><i class="anchor-icon"></i></a>Responding to alerts</h5>
<p>By default, <strong>you will only get one alert per bot per hour</strong>. </p>
<p>Each alert has the following buttons:</p>
<ul>
<li><strong>Fixed</strong> - 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.</li>
<li><strong>Support</strong> - Use this to open a chat with <a href="https://t.me/botsupport">@BotSupport</a> if you don&#39;t see any issues with your bot or if you think the problem is on our side.</li>
<li><strong>Mute for 8h/1w</strong> - Use this if you can&#39;t fix your bot at the moment. This will disable all alerts for the bot in question for the specified period of time. <strong>We do not recommend</strong> using this option since your users may migrate to a more stable bot. You can unmute alerts in your bot&#39;s settings via <a href="https://t.me/botfather">@BotFather</a>.</li>
</ul>
<h5><a class="anchor" name="monitored-issues" href="#monitored-issues"><i class="anchor-icon"></i></a>Monitored issues</h5>
<p>We currently notify you about the following issues:</p>
<ul>
<li><p><strong>Too few private messages are sent.</strong> Value: <strong>{value}</strong> - Your bot is sending far fewer messages than it did in previous weeks. This is useful for newsletter-style bots that send messages without prompts from users. The larger the value, the more significant the difference.</p>
</li>
<li><p><strong>Too few replies to incoming private messages</strong>. Conversion rate: <strong>{value}</strong> - 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). </p>
</li>
</ul>
<blockquote>
<p>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. <a href="api#sendmessage">sendMessage</a>).</p>
</blockquote>
<ul>
<li><strong>Too few answers to inline queries</strong>. Conversion rate: <strong>{value}</strong> - Your bot is not replying to all inline queries that are being sent to it, calculated in the same way as above. Respond to <code>inline_query</code> updates by calling <a href="api#answerInlineQuery">answerInlineQuery</a>.</li>
</ul>
<ul>
<li><strong>Too few answers to callback queries</strong>. Conversion rate: <strong>{value}</strong></li>
<li><strong>Too few answers to callback game queries</strong>. Conversion rate: <strong>{value}</strong> - 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 <code>callback_query</code> updates by calling <a href="api#answerCallbackQuery">answerCallbackQuery</a>.</li>
</ul>
<h4><a class="anchor" name="local-bot-api" href="#local-bot-api"><i class="anchor-icon"></i></a>Local Bot API</h4>
<p>You can host and work with <strong>your own instance</strong> of our open-source <a href="api">Bot API</a>.<br>The <strong>source code</strong> is available <a href="https://github.com/tdlib/telegram-bot-api">here</a>, along with a quick <a href="https://github.com/tdlib/telegram-bot-api#installation">installation guide</a>.</p>
<p>After <strong>installing the server</strong>, remember to use the <a href="api#logout">logOut</a> method before <strong>redirecting requests</strong> to your new local API URL.</p>
<blockquote>
<p>Your local instance runs on port <code>8081</code> by default and will only accept HTTP requests, so a TLS termination proxy has to be used to handle remote HTTPS requests.</p>
</blockquote>
<p>By hosting our API locally you&#39;ll gain access to <strong>some upgrades</strong>, including:</p>
<table class="table">
<thead>
<tr>
<th>API</th>
<th>Max File Download</th>
<th>Max File Upload</th>
<th>WHook URL</th>
<th>WHook Port</th>
<th>WHook Max Connections</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="api#making-requests">Official</a></td>
<td>20MB</td>
<td>50MB</td>
<td>HTTPS</td>
<td>443,80,88,8443</td>
<td>1-100</td>
</tr>
<tr>
<td><a href="api#using-a-local-bot-api-server">Local</a></td>
<td>Unlimited</td>
<td>2000MB</td>
<td>HTTP</td>
<td>Any port</td>
<td>1-100000</td>
</tr>
</tbody>
</table>
<blockquote>
<p>You can find an exhaustive list <a href="/bots/api#using-a-local-bot-api-server">here</a>.<br>All limits may be subject to change in the future, so make sure to follow <a href="https://t.me/botnews">@BotNews</a>.</p>
</blockquote>
<hr>
<h3><a class="anchor" name="botfather" href="#botfather"><i class="anchor-icon"></i></a>BotFather</h3>
<p>Below is a detailed guide to using <a href="https://t.me/botfather">@BotFather</a>, Telegram’s tool for <strong>creating</strong> and <strong>managing</strong> bots.</p>
<h4><a class="anchor" name="creating-a-new-bot" href="#creating-a-new-bot"><i class="anchor-icon"></i></a>Creating a new bot</h4>
<p>Use the <code>/newbot</code> command to create a new bot. <a href="https://t.me/botfather">@BotFather</a> will ask you for a name and username, then generate an authentication token for your new bot.</p>
<ul>
<li><p>The <strong>name</strong> of your bot is displayed in contact details and elsewhere.</p>
</li>
<li><p>The <strong>username</strong> is a short name, used in search, mentions and t.me links. Usernames are 5-32 characters long and not case sensitive – but may only include Latin characters, numbers, and underscores. Your bot&#39;s username must end in &#39;bot’, like &#39;tetris_bot&#39; or &#39;TetrisBot&#39;.</p>
</li>
<li><p>The <strong>token</strong> is a string, like <code>110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>, which is required to authorize the bot and send requests to the Bot API. Keep your token secure and store it safely, it can be used by anyone to control your bot. </p>
</li>
</ul>
<blockquote>
<p>Unlike the bot’s name, the username cannot be changed later – so choose it carefully.<br>When sending a request to api.telegram.org, remember to prefix the word ‘bot’ to your token.</p>
</blockquote>
<h4><a class="anchor" name="about-text-description-and-profile-media" href="#about-text-description-and-profile-media"><i class="anchor-icon"></i></a>About text, description and profile media</h4>
<p>When new users open your bot, they will be met with a helpful description in a box titled “What can this bot do?”.</p>
<p>Properly <a href="#edit-bots">setting this field</a> in <a href="https://t.me/botfather">@BotFather</a> allows everyone to immediately get an idea of what your bot can do – your description should be <strong>brief</strong>, <strong>to the point</strong> and <strong>on topic</strong>.</p>
<blockquote>
<p>You can also add a photo or video to this field with <code>Edit Description Picture</code> in <a href="https://t.me/botfather">@BotFather</a>.</p>
</blockquote>
<p>Additionally, just like normal users, bots also come with a <strong>short bio</strong> available on their profile. If you didn&#39;t specify this field while first creating your bot, you can set it at any time with the <code>/setabouttext</code> command in <a href="https://t.me/botfather">@BotFather</a>. Users can interact with many bots and they won&#39;t have access to their description after starting them – having a quick reminder of the bot&#39;s purpose can be very useful.</p>
<p>Bots can also have a <strong>profile picture</strong> – you should pick something unique and original so that users can find it in their chat list at a glance.</p>
<blockquote>
<p>Once set, the description, about text and profile pic can be <strong>replaced</strong> but never fully <strong>removed</strong>.</p>
</blockquote>
<h4><a class="anchor" name="generating-an-authentication-token" href="#generating-an-authentication-token"><i class="anchor-icon"></i></a>Generating an authentication token</h4>
<p>If your existing token is <strong>compromised</strong> or <strong>you lost it</strong> for some reason, use the <code>/token</code> command to generate a new one.</p>
<h4><a class="anchor" name="transfer-ownership" href="#transfer-ownership"><i class="anchor-icon"></i></a>Transfer ownership</h4>
<p>You can transfer ownership of your bot <strong>to another user</strong>.<br>To do this, send <code>/mybots</code>, select your bot, then <em>transfer ownership</em>.<br>You can only transfer a bot to users who have interacted with it at least once.</p>
<blockquote>
<p>Transferring ownership will give full control of the bot to another user – they will be able to access the bot’s messages and even delete it. The transfer is permanent, so please consider it carefully.</p>
</blockquote>
<h4><a class="anchor" name="botfather-commands" href="#botfather-commands"><i class="anchor-icon"></i></a>BotFather commands</h4>
<p>The remaining commands are pretty self-explanatory:</p>
<ul>
<li>/mybots – returns a list of your bots with handy controls to edit their settings.</li>
<li>/mygames – does the same for your games.</li>
</ul>
<h4><a class="anchor" name="edit-bots" href="#edit-bots"><i class="anchor-icon"></i></a>Edit bots</h4>
<p>To edit your bot, you have two options.</p>
<p>You can use the available commands:</p>
<ul>
<li>/setname – change your bot&#39;s <strong>name</strong>.</li>
<li>/setdescription – change the bot&#39;s <strong>description</strong> (short text up to 512 characters). Users will see this text at the beginning of the conversation with the bot, titled &#39;<em>What can this bot do?</em>&#39;.</li>
<li>/setabouttext – change the bot&#39;s <strong>about info</strong>, a shorter text up to 120 characters. Users will see this text on the bot&#39;s profile page. When they share your bot with someone, this text is sent together with the link.</li>
<li>/setuserpic – change the bot&#39;s <strong>profile picture</strong>. </li>
<li>/setcommands – change the list of <strong>commands</strong> supported by your bot. Users will see these commands as suggestions when they type <code>/</code> in the chat with your bot. See <a href="#commands">commands</a> for more info.</li>
<li>/setdomain – link a <strong>website domain</strong> to your bot. See the <a href="#login-widget">login widget</a> section.</li>
<li>/deletebot – delete your bot and <strong>free its username</strong>. Cannot be undone.</li>
</ul>
<p>Or you can use the <code>/mybots</code> command, tap on your bot and use the modern inline interface to edit it.</p>
<h4><a class="anchor" name="edit-settings" href="#edit-settings"><i class="anchor-icon"></i></a>Edit settings</h4>
<ul>
<li>/setinline – toggle <strong>inline mode</strong> for your bot.</li>
<li>/setinlinegeo – request <strong>location data</strong> to provide location-based inline results.</li>
<li>/setjoingroups – toggle whether your bot can be <strong>added to groups</strong> or not. All bots must be able to process direct messages, but if your bot was not designed to work in groups, you can disable this.</li>
<li>/setinlinefeedback – toggle whether the API should <strong>send updates about the results</strong> chosen by users. See an in-depth explanation <a href="/bots/inline#collecting-feedback">here</a>.</li>
<li>/setprivacy – set which messages your bot will receive when added to a group. See <a href="#privacy-mode">privacy-mode</a> for more info.</li>
</ul>
<h4><a class="anchor" name="manage-games" href="#manage-games"><i class="anchor-icon"></i></a>Manage games</h4>
<ul>
<li>/newgame – create a new game.</li>
<li>/listgames – see a list of your games.</li>
<li>/editgame – edit a game.</li>
<li>/deletegame – delete an existing game.</li>
</ul>
<blockquote>
<p>Please note that it may take a few minutes for changes to take effect.</p>
</blockquote>
<hr>
<p>With this information, you are ready to proceed to our <a href="api">Full API Reference for Developers</a>.</p>
<ul>
<li>If you have any questions, check out our <a href="faq">Bot FAQ</a>.</li>
<li>If you&#39;re experiencing issues with our API, please contact <a href="https://t.me/botsupport">@BotSupport</a> on Telegram.</li>
</ul>
</div>
</div>
</div>
</div>
<div class="footer_wrap">
<div class="footer_columns_wrap footer_desktop">
<div class="footer_column footer_column_telegram">
<h5>Telegram</h5>
<div class="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
</div>
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
<ul>
<li><a href="//telegram.org/faq">FAQ</a></li>
<li><a href="//telegram.org/privacy">Privacy</a></li>
<li><a href="//telegram.org/press">Press</a></li>
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
<ul>
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
<li><a href="//telegram.org/android">Android</a></li>
<li><a href="//telegram.org/dl/web">Mobile Web</a></li>
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
<ul>
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
<li><a href="//macos.telegram.org/">macOS</a></li>
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
</ul>
</div>
<div class="footer_column footer_column_platform">
<h5><a href="/">Platform</a></h5>
<ul>
<li><a href="/api">API</a></li>
<li><a href="//translations.telegram.org/">Translations</a></li>
<li><a href="//instantview.telegram.org/">Instant View</a></li>
</ul>
</div>
</div>
<div class="footer_columns_wrap footer_mobile">
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/blog">Blog</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps">Apps</a></h5>
</div>
<div class="footer_column">
<h5><a href="/">Platform</a></h5>
</div>
<div class="footer_column">
<h5><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)">Twitter</a></h5>
</div>
</div>
</div>
</div>
<script src="/js/main.js?46"></script>
<script src="/js/jquery.min.js?1"></script>
<script src="/js/bootstrap.min.js?1"></script>
<script>window.initDevPageNav&&initDevPageNav();
backToTopInit("Go up");
removePreloadInit();
</script>
</body>
</html>

590
data/web/blogfork.telegram.org/bots/tutorial.html Normal file
View file

@ -0,0 +1,590 @@
<!DOCTYPE html>
<html class="">
<head>
<meta charset="utf-8">
<title>From BotFather to &#39;Hello World&#39;</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta property="description" content="Building your first bot">
<meta property="og:title" content="From BotFather to &#39;Hello World&#39;">
<meta property="og:image" content="">
<meta property="og:description" content="Building your first bot">
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
<link href="/css/telegram.css?232" rel="stylesheet" media="screen">
<style>
</style>
</head>
<body class="preload">
<div class="dev_page_wrap">
<div class="dev_page_head navbar navbar-static-top navbar-tg">
<div class="navbar-inner">
<div class="container clearfix">
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
<ul class="nav navbar-nav">
<li><a href="//telegram.org/">Home</a></li>
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
<li class=""><a href="/api">API</a></li>
<li class=""><a href="/mtproto">Protocol</a></li>
<li class=""><a href="/schema">Schema</a></li>
</ul>
</div>
</div>
</div>
<div class="container clearfix">
<div class="dev_page">
<div id="dev_page_content_wrap" class=" ">
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/bots" >Telegram Bots</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/bots/tutorial" >From BotFather to &#39;Hello World&#39;</a></li></ul></div>
<h1 id="dev_page_title">From BotFather to &#39;Hello World&#39;</h1>
<div id="dev_page_content"><!-- scroll_nav -->
<p>This guide will walk you through everything you need to know to build your first <strong>Telegram Bot</strong>.<br>If you already know your way around some of the basic steps, you can jump directly to the part you&#39;re missing. Equivalent examples are available in <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.cs">C#</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.py">Python</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.go">Go</a> and <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/tree/main/Nodejs">TypeScript</a> .</p>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#getting-ready"><strong>Basic Tutorial</strong></a></li>
</ul>
<div id="dev_page_content">
<ul style="padding-left: 30px;">
<li style="margin-top: -5px"><a href="#getting-ready">Environment</a></li>
<li><a href="#first-run">First Run</a></li>
<li><a href="#echo-bot">Echo Bot</a></li>
</ul>
</div>
<ul>
<li><a href="#executing-commands"><strong>Advanced Tutorial</strong></a></li>
</ul>
<div id="dev_page_content">
<ul style="padding-left: 30px;">
<li style="margin-top: -5px"><a href="#executing-commands">Commands</a></li>
<li><a href="#navigation">Navigation</a></li>
<li><a href="#database">Database</a></li>
<li><a href="#hosting">Hosting</a></li>
</ul>
</div>
<ul>
<li><a href="#further-reading">Further Reading</a></li>
</ul>
<hr>
<h3><a class="anchor" name="introduction" href="#introduction"><i class="anchor-icon"></i></a>Introduction</h3>
<p>At its core, you can think of the Telegram <a href="api">Bot API</a> as software that provides <a href="https://en.wikipedia.org/wiki/JSON">JSON-encoded</a> responses to your queries.</p>
<p>A bot, on the other hand, is essentially a routine, software or script that queries the API by means of an <a href="https://core.telegram.org/bots/api#making-requests">HTTPS request</a> and waits for a response. There are several types of <a href="api#available-methods">requests</a> you can make, as well as many different <a href="api#available-types">objects</a> that you can use and receive as responses.</p>
<p>Since <strong>your browser</strong> is capable of sending HTTPS requests, you can use it to quickly try out the API. After <a href="#obtain-your-bot-token">obtaining your token</a>, try pasting this string into your browser:</p>
<pre><code>https://api.telegram.org/bot&lt;YOUR_BOT_TOKEN&gt;/getMe</code></pre>
<p>In theory, you could interact with the API with <strong>basic requests</strong> like this, either via your browser or other tailor-made tools like <a href="https://curl.se/">cURL</a>. While this can work for simple requests like the example above, it&#39;s not practical for larger applications and doesn&#39;t scale well.<br>For that reason, this guide will show you how to use <a href="samples">libraries and frameworks</a>, along with some <strong>basic programming skills</strong>, to build a more robust and scalable project.</p>
<p>If you know how to code, you&#39;ll fly right through each step in no time – and if you&#39;re just starting out, this guide will show you everything you need to learn.</p>
<blockquote>
<p>We will use <a href="https://en.wikipedia.org/wiki/Java_%28programming_language%29">Java</a> throughout this guide as it&#39;s one of the most popular programming languages, however, you can follow along with any language as all the steps are fundamentally the same.<br>Since Java is fully cross-platform, each code example will work with any operating system.<br>If you pick another language, equivalent examples are available in <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.cs">C#</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.py">Python</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.go">Go</a> and <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/tree/main/Nodejs">TypeScript</a> .</p>
</blockquote>
<h3><a class="anchor" name="getting-ready" href="#getting-ready"><i class="anchor-icon"></i></a>Getting Ready</h3>
<p>First, we will briefly cover how to <strong>create your first project</strong>, obtain your <strong>API token</strong> and download all necessary <strong>dependencies and libraries</strong>.</p>
<h4><a class="anchor" name="obtain-your-bot-token" href="#obtain-your-bot-token"><i class="anchor-icon"></i></a>Obtain Your Bot Token</h4>
<p>In this context, a <strong>token</strong> is a string that authenticates your bot (not your account) on the bot API. Each bot has a unique token which can also be revoked at any time via <a href="https://t.me/botfather">@BotFater</a>.</p>
<p>Obtaining a token is as simple as contacting <a href="https://t.me/botfather">@BotFater</a>, issuing the <code>/newbot</code> command and following the steps until you&#39;re given a new token. You can find a step-by-step guide <a href="features#creating-a-new-bot">here</a>.</p>
<p>Your token will look something like this:</p>
<pre><code>4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc</code></pre>
<blockquote>
<p>Make sure to save your token in a secure place, treat it like a password and <strong>don&#39;t share it with anyone</strong>.</p>
</blockquote>
<h4><a class="anchor" name="download-an-ide" href="#download-an-ide"><i class="anchor-icon"></i></a>Download an IDE</h4>
<p>To program in Java you&#39;ll need an <a href="https://en.wikipedia.org/wiki/Integrated_development_environment">IDE</a> – a special text editor that will let you write, compile and run your code.<br>In this tutorial, we&#39;ll use IntelliJ – there are several free, open source alternatives like <a href="https://www.eclipse.org/ide/">Eclipse</a> or <a href="https://netbeans.apache.org/download/index.html">NetBeans</a> which work in the exact same way.</p>
<p>You will also need a <a href="https://en.wikipedia.org/wiki/Java_Development_Kit">JDK</a>, a software kit that allows your Java code to run.<br>Most IDEs don&#39;t include a JDK, so you should download a version compatible with your operating system separately. You can find a free, open source version <a href="https://adoptium.net/temurin/releases/">here</a>.</p>
<blockquote>
<p>If you use another language, the steps are identical. You will just have to download a different IDE and software development kit.</p>
</blockquote>
<h4><a class="anchor" name="pick-a-framework-or-library" href="#pick-a-framework-or-library"><i class="anchor-icon"></i></a>Pick a Framework or Library</h4>
<p>You can think of a framework as software that handles all the low-level logic for you, including the API calls, and lets you focus on your bot-specific logic.</p>
<p>In this tutorial, we&#39;ll use <a href="https://github.com/rubenlagus/TelegramBots">TelegramBots</a>, but you can follow along with any equivalent implementation, since all the underlying methods are either similar or exactly the same.</p>
<blockquote>
<p>You can find many frameworks, along with code examples, in <a href="samples">our dedicated list</a>.</p>
</blockquote>
<h4><a class="anchor" name="create-your-project" href="#create-your-project"><i class="anchor-icon"></i></a>Create Your Project</h4>
<p>In IntelliJ, go to <code>File &gt; New &gt; Project</code>.</p>
<p>Fill in the fields accordingly:</p>
<ul>
<li><strong>Name</strong> - The name of your project. For example, <em>BotTutorial</em>.</li>
<li><strong>Location</strong> - Where to store your project. You can use the default value.</li>
<li><strong>Language</strong> - Java</li>
<li><strong>Build System</strong> - The framework that will handle your dependencies. Pick <em>Maven</em>.</li>
<li><strong>JDK</strong> - Pick whichever version you downloaded. We&#39;ll be using version <em>17</em>.</li>
<li><strong>Add Sample Code</strong> - Leave this <strong>selected</strong>, it will generate some needed files for you.</li>
<li><strong>Advanced Settings &gt; GroupId</strong> - We suggest <em>tutorial</em>.</li>
<li><strong>Advanced Settings &gt; ArtifactId</strong> - You can use the default value.</li>
</ul>
<p>After hitting <em>Create</em>, if you did everything correctly, your <strong>Project</strong> view in the top left should show a <strong>project structure</strong> along these lines:</p>
<pre><code>BotTutorial
├─ .idea
├─ src
│ └─ main
│ └─ java
│ └─ tutorial
│ └─ Main
└─ pom.xml</code></pre>
<blockquote>
<p>Other IDEs will follow a similar pattern. Your dependency management system will have a different name (or no name at all if it&#39;s built-in) depending on the language you chose.</p>
</blockquote>
<p>If this looks scary, don&#39;t worry. We will only be using the <code>Main</code> file and the <code>pom.xml</code> file.<br>In fact, to check that everything is working so far, double click on <em>Main</em> and click on the small green arrow on the left of <em>public class Main</em>, then select the first option.<br>If you followed the steps correctly, <em>Hello world!</em> should appear in the console below.</p>
<h4><a class="anchor" name="add-framework-dependency" href="#add-framework-dependency"><i class="anchor-icon"></i></a>Add Framework Dependency</h4>
<p>We will now instruct the IDE to download and configure everything needed to work with the API.<br>This is very easy and happens automatically behind the scenes.</p>
<p>First, locate your <code>pom.xml</code> file on the left side of the screen.<br>Open it by double-clicking and simply add:</p>
<pre><code>&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.telegram&lt;/groupId&gt;
&lt;artifactId&gt;telegrambots&lt;/artifactId&gt;
&lt;version&gt;6.0.1&lt;/version&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;</code></pre>
<p>right after the <code>&lt;/properties&gt;</code> tag.</p>
<p>When you&#39;re done, your <code>pom.xml</code> should look something like <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/pom.xml">this</a>.</p>
<h3><a class="anchor" name="start-coding" href="#start-coding"><i class="anchor-icon"></i></a>Start Coding</h3>
<p>We are ready to start coding. If you&#39;re a beginner, consider that being familiar with your language of choice will greatly help. With this tutorial, you&#39;ll be able to teach your bot basic behaviors, though more advanced features will require some coding experience.</p>
<h4><a class="anchor" name="creating-a-bot-class" href="#creating-a-bot-class"><i class="anchor-icon"></i></a>Creating a Bot Class</h4>
<p>If you&#39;re familiar with <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>, you&#39;ll know what a class is.<br>If you&#39;ve never heard of it before, consider a class as a file where you write some logic.</p>
<p>To <strong>create the class</strong> that will contain the bot logic, right click on <em>tutorial</em> from the project tree on the left and select <em>New &gt; Java Class</em>. Name it <em>Bot</em> and hit enter.</p>
<p>Now we have to connect this class to the bot framework. In other words, we must make sure it extends <code>TelegramLongPollingBot</code>. To do that, just add <em>extends TelegramLongPollingBot</em> right after <em>Bot</em>.<br>A red line will appear – it simply means we&#39;re missing some important methods.</p>
<p>To fix this, hover over the red line, click on <em>implement methods</em>, then hit OK.<br>Depending on the IDE, this option may be called <em>implement missing methods</em> or something similar.</p>
<p>You should end up with this – if something went wrong, feel free to copy it from here and paste it in your class:</p>
<pre><code>package tutorial;
import org.telegram.telegrambots.bots.TelegramLongPollingBot;
import org.telegram.telegrambots.meta.api.objects.Update;
public class Bot extends TelegramLongPollingBot {
@Override
public String getBotUsername() {
return null;
}
@Override
public String getBotToken() {
return null;
}
@Override
public void onUpdateReceived(Update update) {}
}</code></pre>
<blockquote>
<p>If you get a red line under TelegramLongPollingBot, it means you didn&#39;t set up your pom.xml correctly. If this is the case, restart from <a href="#add-framework-dependency">here</a>.</p>
</blockquote>
<h4><a class="anchor" name="available-methods" href="#available-methods"><i class="anchor-icon"></i></a>Available Methods</h4>
<p>Let&#39;s look into these 3 methods one by one.</p>
<ul>
<li><strong>getBotUsername</strong> - This method must be edited to always return your bot&#39;s username. You should replace the <em>null</em> return value with it.</li>
<li><strong>getBotToken</strong> - This method will be used by the framework to retrieve your bot token. You should replace the <em>null</em> return value with the token.</li>
<li><strong>onUpdateReceived</strong> - This is the most important method. It will be called automatically whenever a new Update is available. Let&#39;s add a <code>System.out.println(update);</code> call in there to quickly show what we are getting.</li>
</ul>
<p>After you&#39;ve replaced all the strings, you should end up with this:</p>
<pre><code>@Override
public String getBotUsername() {
return &quot;TutorialBot&quot;;
}
@Override
public String getBotToken() {
return &quot;4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc&quot;;
}
@Override
public void onUpdateReceived(Update update) {
System.out.println(update);
}</code></pre>
<p>At this point, the bot is configured and ready to go – time to register it on the API and start processing updates.</p>
<blockquote>
<p>In the future, you should consider storing your token in a dedicated settings file or in <a href="https://en.wikipedia.org/wiki/Environment_variable">environment variables</a>. Keeping it in the code is fine for the scope of this tutorial, however, it&#39;s not very versatile and is generally considered bad practice. </p>
</blockquote>
<h4><a class="anchor" name="registering-the-bot" href="#registering-the-bot"><i class="anchor-icon"></i></a>Registering the Bot</h4>
<p>To <strong>register the bot</strong> on the API, simply add a couple of lines <strong>in the main method</strong> that will launch the application. If you named your class <code>Bot</code>, this is what your main method should look like:</p>
<pre><code>public static void main(String[] args) throws TelegramApiException {
TelegramBotsApi botsApi = new TelegramBotsApi(DefaultBotSession.class);
botsApi.registerBot(new Bot());
}</code></pre>
<blockquote>
<p>You can place this method in any class. Since we have an auto-generated <code>main</code> method in the Main class, we&#39;ll be using that one for this tutorial.</p>
</blockquote>
<h3><a class="anchor" name="first-run" href="#first-run"><i class="anchor-icon"></i></a>First Run</h3>
<p>It&#39;s time to <strong>run your bot</strong> for the first time.<br>Hit the green arrow to the left of <code>public static void main</code> and select the first option.</p>
<p><em>And then there was nothing</em>. Yes, a bit anticlimactic.<br>This is because your bot <strong>has nothing to print</strong> – there are <strong>no new updates</strong> because nobody messaged it yet.</p>
<p>If you try messaging the bot on Telegram, you&#39;ll then see <strong>new updates</strong> pop up in the console. At this point, you have your very own Telegram Bot – quite the achievement. Now, on to making it a bit more intelligent.</p>
<blockquote>
<p>If nothing pops up, make sure you messaged the right bot and that the token you pasted in the code is correct.</p>
</blockquote>
<h3><a class="anchor" name="receiving-messages" href="#receiving-messages"><i class="anchor-icon"></i></a>Receiving Messages</h3>
<p>Every time someone sends a <strong>private message</strong> to your bot, your <code>onUpdateReceived</code> method will be called automatically and you&#39;ll be able to handle the <code>update</code> parameter, which contains the <strong>message</strong>, along with a great deal of other info which you can see detailed <a href="api#update">here</a>.</p>
<p>Let&#39;s focus on two values for now:</p>
<ul>
<li><strong>The user</strong> - Who sent the message. Access it via <code>update.getMessage().getFrom()</code>.</li>
<li><strong>The message</strong> - What was sent. Access it via <code>update.getMessage()</code>.</li>
</ul>
<p>Knowing this, we can make it a bit more clear in the <strong>console output</strong>.</p>
<pre><code>@Override
public void onUpdateReceived(Update update) {
var msg = update.getMessage();
var user = msg.getFrom();
System.out.println(user.getFirstName() + &quot; wrote &quot; + msg.getText());
}</code></pre>
<p>This is just a basic example – you can now play around with all the methods to see everything you can pull out of these objects. You can try <code>getUsername</code>, <code>getLanguageCode</code>, and dozens more.</p>
<p>Knowing how to receive, process and print <strong>incoming messages</strong>, now it&#39;s time to learn how to <strong>answer them</strong>.</p>
<blockquote>
<p>Remember to stop and re-launch your bot after each change to the code.</p>
</blockquote>
<h3><a class="anchor" name="sending-messages" href="#sending-messages"><i class="anchor-icon"></i></a>Sending Messages</h3>
<p>To send a private text message, you generally need <strong>three things</strong>:</p>
<ul>
<li>The user <strong>must</strong> have contacted your bot first. (Unless the user sent a join request to a group where your bot is an admin, but that&#39;s a more advanced scenario).</li>
<li>You <strong>must</strong> have previously saved the <strong>User ID</strong> (<code>user.getId()</code>)</li>
<li>A <code>String</code> object containing the message text, 1-4096 characters.</li>
</ul>
<p>With that out of the way, let&#39;s create a <strong>new method</strong> to send the first message:</p>
<pre><code>public void sendText(Long who, String what){
SendMessage sm = SendMessage.builder()
.chatId(who.toString()) //Who are we sending a message to
.text(what).build(); //Message content
try {
execute(sm); //Actually sending the message
} catch (TelegramApiException e) {
throw new RuntimeException(e); //Any error will be printed here
}
}</code></pre>
<p>And proceed to run this in the <code>main</code> method, right after registering the bot.<br>For this example, we&#39;ll assume your User ID is <code>1234</code>.</p>
<pre><code>public static void main(String[] args) throws TelegramApiException {
TelegramBotsApi botsApi = new TelegramBotsApi(DefaultBotSession.class);
Bot bot = new Bot(); //We moved this line out of the register method, to access it later
botsApi.registerBot(bot);
bot.sendText(1234L, &quot;Hello World!&quot;); //The L just turns the Integer into a Long
}</code></pre>
<p>If you did everything correctly, your bot should text you <em>Hello World!</em> every time you launch your code. Sending messages to groups or channels – assuming you have the relevant permissions – is as simple as replacing <code>1234</code> with the ID of the respective chat.</p>
<blockquote>
<p>Try experimenting with other types of messages, like SendPhoto, SendSticker, SendDice…<br>A full list is available starting <a href="https://core.telegram.org/bots/api#sendmessage">here</a>.</p>
</blockquote>
<h3><a class="anchor" name="echo-bot" href="#echo-bot"><i class="anchor-icon"></i></a>Echo Bot</h3>
<p>Let&#39;s practice everything we tried so far by coding an <strong>Echo Bot</strong>.<br>Its functionality will be rather simple: every text message it receives will be sent right back to the user.</p>
<h4><a class="anchor" name="copying-text" href="#copying-text"><i class="anchor-icon"></i></a>Copying Text</h4>
<p>The most intuitive way of coding this is saving the User ID and calling <code>sendText</code> right after each update.</p>
<p>In other words:</p>
<pre><code>@Override
public void onUpdateReceived(Update update) {
var msg = update.getMessage();
var user = msg.getFrom();
var id = user.getId();
sendText(id, msg.getText());
}</code></pre>
<p>This works for text but can be extended to stickers, media and files.</p>
<h4><a class="anchor" name="copying-everything" href="#copying-everything"><i class="anchor-icon"></i></a>Copying Everything</h4>
<p>There are more specific functions that can be used to copy messages and send them back.<br>Let&#39;s build a method to do just that:</p>
<pre><code>public void copyMessage(Long who, Integer msgId){
CopyMessage cm = CopyMessage.builder()
.fromChatId(who.toString()) //We copy from the user
.chatId(who.toString()) //And send it back to him
.messageId(msgId) //Specifying what message
.build();
try {
execute(cm);
} catch (TelegramApiException e) {
throw new RuntimeException(e);
}
}</code></pre>
<p>After replacing the method call in<code>onUpdateReceived</code>, running the code will result in a fully functional <strong>Echo Bot</strong>.</p>
<blockquote>
<p>This tutorial assumes that updates always contain messages for the sake of simplicity. This may not always be true – be sure to implement all the proper checks in your code to handle every type of update with the appropriate methods.</p>
</blockquote>
<h3><a class="anchor" name="executing-commands" href="#executing-commands"><i class="anchor-icon"></i></a>Executing Commands</h3>
<p>To learn what a command is and how it works, we recommend reading this <a href="features#commands">dedicated summary</a>.<br>In this guide, we&#39;ll focus on the technical side of things.</p>
<h4><a class="anchor" name="creating-your-command" href="#creating-your-command"><i class="anchor-icon"></i></a>Creating Your Command</h4>
<p>Begin by opening <a href="https://t.me/botfather">@BotFater</a>.<br>Type <code>/mybots</code> &gt; <em>Your_Bot_Name</em> &gt; Edit Bot &gt; Edit Commands.</p>
<p>Now send a new command, followed by a brief description.<br>For the purpose of this tutorial, we&#39;ll implement two simple commands:</p>
<pre><code>scream - Speak, I&#39;ll scream right back
whisper - Shhhhhhh</code></pre>
<h4><a class="anchor" name="command-logic" href="#command-logic"><i class="anchor-icon"></i></a>Command Logic</h4>
<p>We want the <strong>Echo Bot</strong> to reply in uppercase when it&#39;s in <strong>scream mode</strong> and normally otherwise.</p>
<p>First, let&#39;s <strong>create a variable</strong> to store the current mode.</p>
<pre><code>public class Bot extends TelegramLongPollingBot {
private boolean screaming = false;
[...]
}</code></pre>
<p>Then, let&#39;s change some logic to <strong>account for this mode</strong>.</p>
<pre><code>public void onUpdateReceived(Update update) {
[...] //Same variables as the previous versions
if(screaming) //If we are screaming
scream(id, update.getMessage()); //Call a custom method
else
copyMessage(id, msg.getMessageId()); //Else proceed normally
}
private void scream(Long id, Message msg) {
if(msg.hasText())
sendText(id, msg.getText().toUpperCase());
else
copyMessage(id, msg.getMessageId()); //We can&#39;t really scream a sticker
}</code></pre>
<p>Finally, let&#39;s add a couple more lines to the <code>onUpdateReceived</code> method to process each command before replying.</p>
<pre><code>if(msg.isCommand()){
if(msg.getText().equals(&quot;/scream&quot;)) //If the command was /scream, we switch gears
screaming = true;
else if (msg.getText().equals(&quot;/whisper&quot;)) //Otherwise, we return to normal
screaming = false;
return; //We don&#39;t want to echo commands, so we exit
}</code></pre>
<p>As you can see, it checks if the message <strong>is a command</strong>. If it is, the bot enters <strong>scream mode</strong>.<br>In the update method, we check <strong>which mode we are in</strong> and either copy the message or convert it to upper case before <strong>sending it back</strong>.</p>
<p>And that&#39;s it. Now the bot can <strong>execute commands</strong> and change its behavior accordingly.</p>
<p>Naturally, this simplified logic will change the bot&#39;s behavior for <strong>everyone</strong> – not just the person who sent the command. This can be fun for this tutorial but <strong>won&#39;t work in a production environment</strong> – consider using a Map, dictionary or equivalent data structure to assign settings for individual users.</p>
<blockquote>
<p>Remember to always implement a few basic <a href="features#global-commands">global commands</a>.<br>You can practice by implementing a simple feedback to the <code>/start</code> command, which we intentionally left out.</p>
</blockquote>
<h3><a class="anchor" name="buttons-and-keyboards" href="#buttons-and-keyboards"><i class="anchor-icon"></i></a>Buttons and Keyboards</h3>
<p>To streamline and simplify user interaction with your bot, you can replace many text-based exchanges with handy buttons. These buttons can perform a wide variety of actions and can be customized for each user.</p>
<h4><a class="anchor" name="button-types" href="#button-types"><i class="anchor-icon"></i></a>Button Types</h4>
<p>There are two main types of buttons:</p>
<ul>
<li><strong>Reply Buttons</strong> - used to provide a list of predefined text <a href="features#keyboards">reply options</a>.</li>
<li><strong>Inline Buttons</strong> - used to offer quick navigation, shortcuts, URLs, games and <a href="features##inline-keyboards">so much more</a>.</li>
</ul>
<p>Using these buttons is as easy as attaching a <code>ReplyKeyboardMarkup</code> or an <code>InlineKeyboardMarkup</code> to your <code>SendMessage</code> object.</p>
<p>This guide will focus on <strong>inline buttons</strong> since they only require a few extra lines of code.</p>
<h4><a class="anchor" name="creating-buttons" href="#creating-buttons"><i class="anchor-icon"></i></a>Creating Buttons</h4>
<p>First of all, let&#39;s create some buttons.</p>
<pre><code> var next = InlineKeyboardButton.builder()
.text(&quot;Next&quot;).callbackData(&quot;next&quot;)
.build();
var back = InlineKeyboardButton.builder()
.text(&quot;Back&quot;).callbackData(&quot;back&quot;)
.build();
var url = InlineKeyboardButton.builder()
.text(&quot;Tutorial&quot;)
.url(&quot;https://core.telegram.org/bots/api&quot;)
.build();</code></pre>
<p>Let&#39;s go back through the fields we specified:</p>
<ul>
<li><strong>Text</strong> - This is what the user will see, the text that appears on the button</li>
<li><strong>Callback Data</strong> - This will be sent back to the code instance as part of a new <code>Update</code>, so we can quickly identify what button was clicked.</li>
<li><strong>Url</strong> - A button that specifies a URL doesn&#39;t specify callbackdata since its behavior is predefined – it will open the given link when tapped.</li>
</ul>
<h4><a class="anchor" name="creating-keyboards" href="#creating-keyboards"><i class="anchor-icon"></i></a>Creating Keyboards</h4>
<p>The <strong>buttons</strong> we created can be assembled into two <strong>keyboards</strong>, which will then be used to navigate back and forth between two <strong>sample menus</strong>.</p>
<p>First, <strong>add two fields</strong> to store the necessary keyboards.</p>
<pre><code>private boolean screaming = false;
private InlineKeyboardMarkup keyboardM1;
private InlineKeyboardMarkup keyboardM2;</code></pre>
<p>Then, <strong>build</strong> and <strong>assign</strong> them.</p>
<pre><code>keyboardM1 = InlineKeyboardMarkup.builder()
.keyboardRow(List.of(next)).build();
//Buttons are wrapped in lists since each keyboard is a set of button rows
keyboardM2 = InlineKeyboardMarkup.builder()
.keyboardRow(List.of(back))
.keyboardRow(List.of(url))
.build();</code></pre>
<blockquote>
<p>You can place this code wherever you prefer, the important thing is making sure that keyboard variables are accessible from the method call that will send the new menu. If you&#39;re confused by this concept and don&#39;t know where to put them, just paste them above the command processing flow.</p>
</blockquote>
<h4><a class="anchor" name="sending-keyboards" href="#sending-keyboards"><i class="anchor-icon"></i></a>Sending Keyboards</h4>
<p>Sending a keyboard only requires specifying a reply markup for the message.</p>
<pre><code>public void sendMenu(Long who, String txt, InlineKeyboardMarkup kb){
SendMessage sm = SendMessage.builder().chatId(who.toString())
.parseMode(&quot;HTML&quot;).text(txt)
.replyMarkup(kb).build();
try {
execute(sm);
} catch (TelegramApiException e) {
throw new RuntimeException(e);
}
}</code></pre>
<blockquote>
<p>You may have noticed that we also added a new parameter, <code>HTML</code>.<br>This is called a <a href="api#formatting-options">formatting option</a> and will allow us to use HTML tags and add formatting to the text later on.</p>
</blockquote>
<h4><a class="anchor" name="menu-trigger" href="#menu-trigger"><i class="anchor-icon"></i></a>Menu Trigger</h4>
<p>We could send a new menu for each new user, but for simplicity let&#39;s add a new command that will spawn a menu. We can achieve this by adding a new <strong>else clause</strong> to the previous command flow.</p>
<pre><code> var txt = msg.getText();
if(msg.isCommand()) {
if (txt.equals(&quot;/scream&quot;))
screaming = true;
else if (txt.equals(&quot;/whisper&quot;))
screaming = false;
else if (txt.equals(&quot;/menu&quot;))
sendMenu(id, &quot;&lt;b&gt;Menu 1&lt;/b&gt;&quot;, keyboard1);
return;
}</code></pre>
<p>Try sending <code>/menu</code> to your bot now. If you did everything correctly, you should see a brand new menu pop up.</p>
<blockquote>
<p>In a production environment, commands should be handled with an appropriate design pattern that isolates them into different executor classes – modular and separated from the main logic.</p>
</blockquote>
<h3><a class="anchor" name="navigation" href="#navigation"><i class="anchor-icon"></i></a>Navigation</h3>
<p>When building complex bots, navigation is essential. Your users must be able to move seamlessly from one menu to the next. </p>
<p>In this example, we want the <code>Next</code> button to lead the user to the second menu.<br>The <code>Back</code> button will send us back.<br>To do that, we will start processing incoming <code>CallbackQueries</code>, which are the results we get after the user taps on a button.</p>
<p>A <code>CallbackQuery</code> is essentially composed of three main parameters:</p>
<ul>
<li><strong>queryId</strong> - Needed to close the query. You <strong>must always</strong> close new queries after processing them – if you don&#39;t, a loading symbol will keep showing on the user&#39;s side on top of each button.</li>
<li><strong>data</strong> - This identifies which button was pressed.</li>
<li><strong>from</strong> - The user who pressed the button.</li>
</ul>
<p>Processing in this context just means <strong>executing the action</strong> uniquely identified by the button, then <strong>closing the query</strong>.</p>
<p>A very basic button handler could look something like:</p>
<pre><code>private void buttonTap(Long id, String queryId, String data, int msgId) {
EditMessageText newTxt = EditMessageText.builder()
.chatId(id.toString())
.messageId(msgId).text(&quot;&quot;).build();
EditMessageReplyMarkup newKb = EditMessageReplyMarkup.builder()
.chatId(id.toString()).messageId(msgId).build();
if(data.equals(&quot;next&quot;)) {
newTxt.setText(&quot;MENU 2&quot;);
newKb.setReplyMarkup(keyboardM2);
} else if(data.equals(&quot;back&quot;)) {
newTxt.setText(&quot;MENU 1&quot;);
newKb.setReplyMarkup(keyboardM1);
}
AnswerCallbackQuery close = AnswerCallbackQuery.builder()
.callbackQueryId(queryId).build();
execute(close);
execute(newTxt);
execute(newKb);
}</code></pre>
<p>With this handler, whenever a button is tapped, your bot will automatically navigate between inline menus.<br>Expanding on this concept allows for endless combinations of navigable submenus, settings and dynamic pages.</p>
<h3><a class="anchor" name="database" href="#database"><i class="anchor-icon"></i></a>Database</h3>
<p>Telegram <strong>does not</strong> host an update database for you – once you process and consume an update, it will no longer be available. This means that features like user lists, message lists, current user inline menu, settings, etc. <strong>have to be implemented and maintained</strong> by bot developers.</p>
<p>If your bot needs one of these features and you want to get started on <strong>data persistence</strong>, we recommend that you look into <a href="https://en.wikipedia.org/wiki/Serialization">serialization</a> practices and libraries for your language of choice, as well as available databases.</p>
<p>Implementing a database is out of scope for this guide, however, several guides are available online for simple embedded <strong>open source</strong> software solutions like <a href="https://www.sqlite.org/index.html">SQLite</a>, <a href="https://hsqldb.org/">HyperSQL</a>, <a href="https://db.apache.org/derby/">Derby</a> and many more.</p>
<blockquote>
<p>Your language of choice will also influence which databases are available and supported – the list above assumes you followed this Java tutorial.</p>
</blockquote>
<h3><a class="anchor" name="hosting" href="#hosting"><i class="anchor-icon"></i></a>Hosting</h3>
<p>So far, your bot has been running on your <strong>local machine</strong> – your PC. While this may be good for <strong>developing</strong>, <strong>testing</strong> and <strong>debugging</strong>, it is not ideal for a production environment.<br>You&#39;ll want your bot to be available and responsive at all times, but your computer might not always be online.</p>
<p>This can be done in four steps:</p>
<ul>
<li><p><strong>Package your code</strong><br>Making your bot <strong>easy to move</strong> and <strong>runnable</strong> outside of an IDE is essential to <strong>host it elsewhere</strong>.<br>If you followed this tutorial, this <a href="https://www.jetbrains.com/help/idea/compiling-applications.html#run_packaged_jar">standard guide</a> will work for you. If you didn&#39;t, look into <strong>export or packaging guides</strong> for your IDE and language of choice – procedures may vary but the end result is the same.</p>
</li>
<li><p><strong>Purchase a VPS or equivalent service</strong><br>A server is essentially a machine that is always online and running, without you having to worry about anything. To host your bot, you can opt for a <a href="https://en.wikipedia.org/wiki/Virtual_private_server">VPS</a> which serves this purpose and can be rented from several different providers.<br>Another option would be to purchase a network-capable <a href="https://en.wikipedia.org/wiki/Microcontroller">microcontroller</a>, which come in all different specs and sizes depending on your needs.</p>
</li>
</ul>
<blockquote>
<p>You should ensure that all user data remains <strong>heavily encrypted at all times</strong> in your database to guarantee the privacy of your users. The same concept applies to your local instance, however, this becomes especially important once you transfer your database to a remote server.</p>
</blockquote>
<ul>
<li><strong>Upload your executable/package</strong></li>
</ul>
<p>Once you have a working <a href="https://en.wikipedia.org/wiki/Secure_Shell">ssh</a> connection between your machine and your new server, you should upload your executable and all associated files.<br>We will assume the runnable jar <code>TutorialBot.jar</code> and its database <code>dbase.db</code> are currently in the <code>/TBot</code> folder.</p>
<pre><code>$ scp -r /TBot/ username@server_ip:/bots/TBotRemote/</code></pre>
<ul>
<li><strong>Run your application</strong></li>
</ul>
<p>Depending on which language you chose, you might have to configure your server environment differently. If you chose Java, you just need to install a compatible JDK.</p>
<pre><code>$ apt install openjdk-17-jre
$ java -version</code></pre>
<p>If you did everything correctly, you should see a Java version as the output, along with a few other values. This means you&#39;re ready to run your application.</p>
<p>Now, to run the executable:</p>
<pre><code>$ cd /bots/TBotRemote/
$ java -jar TutorialBot.jar</code></pre>
<p>Your bot is now online and users can interact with it at any time.</p>
<blockquote>
<p>To streamline and modularize this process, you could employ a specialized <a href="https://www.docker.com/resources/what-container/">docker container</a> or equivalent service.<br>If you followed along in one of the equivalent examples (<a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.cs">C#</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.py">Python</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.go">Go</a> and <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/tree/main/Nodejs">TypeScript</a>) you can find a detailed set of instructions to export and run your code <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/tree/main/">here</a>.</p>
</blockquote>
<h3><a class="anchor" name="further-reading" href="#further-reading"><i class="anchor-icon"></i></a>Further Reading</h3>
<p>If you got this far, you might be interested in these additional guides and docs:</p>
<ul>
<li><a href="/bots">General Bot Platform Overview</a></li>
<li><a href="/bots/features">Detailed List of Bot Features</a></li>
<li><a href="/bots/api">Full API Reference</a></li>
</ul>
<p>If you encounter any issues while following this guide, you can contact us on Telegram at <a href="https://t.me/botsupport">@BotSupport</a>.</p>
</div>
</div>
</div>
</div>
<div class="footer_wrap">
<div class="footer_columns_wrap footer_desktop">
<div class="footer_column footer_column_telegram">
<h5>Telegram</h5>
<div class="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
</div>
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
<ul>
<li><a href="//telegram.org/faq">FAQ</a></li>
<li><a href="//telegram.org/privacy">Privacy</a></li>
<li><a href="//telegram.org/press">Press</a></li>
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
<ul>
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
<li><a href="//telegram.org/android">Android</a></li>
<li><a href="//telegram.org/dl/web">Mobile Web</a></li>
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
<ul>
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
<li><a href="//macos.telegram.org/">macOS</a></li>
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
</ul>
</div>
<div class="footer_column footer_column_platform">
<h5><a href="/">Platform</a></h5>
<ul>
<li><a href="/api">API</a></li>
<li><a href="//translations.telegram.org/">Translations</a></li>
<li><a href="//instantview.telegram.org/">Instant View</a></li>
</ul>
</div>
</div>
<div class="footer_columns_wrap footer_mobile">
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/blog">Blog</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps">Apps</a></h5>
</div>
<div class="footer_column">
<h5><a href="/">Platform</a></h5>
</div>
<div class="footer_column">
<h5><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)">Twitter</a></h5>
</div>
</div>
</div>
</div>
<script src="/js/main.js?46"></script>
<script src="/js/jquery.min.js?1"></script>
<script src="/js/bootstrap.min.js?1"></script>
<script>window.initDevPageNav&&initDevPageNav();
backToTopInit("Go up");
removePreloadInit();
</script>
</body>
</html>

583
data/web/core.telegram.org/bots/features.html Normal file
View file

@ -0,0 +1,583 @@
<!DOCTYPE html>
<html class="">
<head>
<meta charset="utf-8">
<title>Telegram Bot Features</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta property="description" content="This page describes individual bot elements in greater detail. For a general overview of bots, read the introduction to bots first.">
<meta property="og:title" content="Telegram Bot Features">
<meta property="og:image" content="https://core.telegram.org/file/464001858/11318/ahAJjwERIX8.164875/ce1372cbf73e3ea94e">
<meta property="og:description" content="This page describes individual bot elements in greater detail. For a general overview of bots, read the introduction to bots first.">
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
<link href="/css/telegram.css?232" rel="stylesheet" media="screen">
<style>
</style>
</head>
<body class="preload">
<div class="dev_page_wrap">
<div class="dev_page_head navbar navbar-static-top navbar-tg">
<div class="navbar-inner">
<div class="container clearfix">
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
<ul class="nav navbar-nav">
<li><a href="//telegram.org/">Home</a></li>
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
<li class=""><a href="/api">API</a></li>
<li class=""><a href="/mtproto">Protocol</a></li>
<li class=""><a href="/schema">Schema</a></li>
</ul>
</div>
</div>
</div>
<div class="container clearfix">
<div class="dev_page">
<div id="dev_page_content_wrap" class=" ">
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/bots" >Telegram Bots</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/bots/features" >Telegram Bot Features</a></li></ul></div>
<h1 id="dev_page_title">Telegram Bot Features</h1>
<div id="dev_page_content"><!-- scroll_nav -->
<p>This page describes individual <strong>bot elements</strong> and <strong>features</strong> in detail. See also:</p>
<ul>
<li><a href="/bots">A General Bot Platform Overview</a></li>
<li><a href="/bots/api">Full API Reference for Developers</a></li>
</ul>
<h3><a class="anchor" name="what-features-do-bots-have" href="#what-features-do-bots-have"><i class="anchor-icon"></i></a>What features do bots have?</h3>
<ul>
<li><a href="#inputs"><strong>Inputs</strong></a><ul>
<li><a href="#inputs">Text</a></li>
<li><a href="#commands">Commands</a></li>
<li><a href="#keyboards">Buttons</a> </li>
</ul>
</li>
<li><a href="#interactions"><strong>Interactions</strong></a><ul>
<li><a href="#inline-requests">Inline</a></li>
<li><a href="#deep-linking">Deep Linking</a></li>
<li><a href="#attachment-menu">Attachment Menu</a></li>
</ul>
</li>
<li><a href="#payments"><strong>Integration</strong></a><ul>
<li><a href="#web-apps">Web Apps</a></li>
<li><a href="#payments">Payments</a></li>
<li><a href="#web-login">Web Login</a></li>
<li><a href="#html5-games">HTML5 Games</a></li>
<li><a href="#stickers">Stickers</a> </li>
</ul>
</li>
<li><a href="#language-support"><strong>Language Support</strong></a></li>
<li><a href="#bot-management"><strong>Bot Management</strong></a><ul>
<li><a href="#privacy-mode">Privacy Mode</a></li>
<li><a href="#status-alerts">Status Alerts</a></li>
<li><a href="#local-bot-api">Local API</a></li>
</ul>
</li>
<li><a href="#botfather"><strong>BotFather, creating and managing bots</strong></a></li>
</ul>
<hr>
<h3><a class="anchor" name="inputs" href="#inputs"><i class="anchor-icon"></i></a>Inputs</h3>
<p>Users can send <strong>messages of all types</strong> to bots, including text, files, locations, stickers, voice messages and even <a href="/bots/api#dice">dice</a> if they&#39;re feeling lucky. However, Telegram bots offer many other tools for building flexible interfaces tailored to your specific needs:</p>
<ul>
<li><a href="#commands">Commands</a> that are highlighted in messages and can be selected from a list after typing <code>/</code>.</li>
<li><a href="#keyboards">Keyboards</a> that replace the user&#39;s keyboard with predefined answer options.</li>
<li><a href="#inline-keyboards">Buttons</a> that are shown next to messages from the bot.</li>
</ul>
<p>For even more flexibility, <a href="#web-apps">Web Apps</a> support 100% custom interfaces with Javascript. </p>
<div>
<a href="/file/464001858/11318/ahAJjwERIX8.164875/ce1372cbf73e3ea94e" target="_blank"><img src="/file/464001858/11318/ahAJjwERIX8.164875/ce1372cbf73e3ea94e" title="Inputs" class="dev_page_image" width=70% /></a>
</div>
<blockquote>
<p><strong>Note:</strong> Telegram bots can support <a href="#language-support">multiple languages</a> that adapt to the users&#39; language settings in the app.</p>
</blockquote>
<h4><a class="anchor" name="commands" href="#commands"><i class="anchor-icon"></i></a>Commands</h4>
<p>A command is a simple <code>/keyword</code> that tells the bot what to do. Telegram apps will:</p>
<ul>
<li><strong>Highlight</strong> commands in messages. When the user taps a highlighted command, that command is immediately sent again.</li>
<li>Suggest a <strong>list of supported commands</strong> with descriptions when the user enters a <code>/</code> (for this to work, you need to have provided a list of commands to <a href="https://t.me/botfather">@BotFather</a> or via the <a href="/bots/api#setmycommands">appropriate API method</a>). Selecting a command from the list immediately sends it.</li>
<li>Show a <a href="#menu-button">menu button</a> containing all or some of a bot’s commands (which you set via <a href="https://t.me/botfather">@BotFather</a>).</li>
</ul>
<p>Commands must always start with the <code>/</code> symbol and contain <strong>up to 32 characters</strong>. They can use <strong>Latin letters</strong>, <strong>numbers</strong> and <strong>underscores</strong>, though simple lowercase text is recommended for a cleaner look. </p>
<p>Here are a few examples:</p>
<ul>
<li>/next </li>
<li>/cancel </li>
<li>/newlocation </li>
<li>/newrule </li>
</ul>
<p>Commands should be <strong>as specific as possible</strong> – for example <code>/newlocation</code> or <code>/newrule</code> <strong>is better</strong> than a <code>/new</code> command that then requires an additional parameter from the user like &quot;<em>location</em>“ or ”<em>rule</em>&quot;.</p>
<div>
<a href="/file/464001775/10227/HCr0XgSUHrg.119089/c17ff5d34fe528361e" target="_blank"><img src="/file/464001775/10227/HCr0XgSUHrg.119089/c17ff5d34fe528361e" title="Commands" class="dev_page_image"
width=44% /></a>
</div>
<blockquote>
<p>We require <strong>all developers</strong> to support several <a href="#global-commands">Global Commands</a> to make sure Telegram bots offer a consistent and user-friendly experience.</p>
</blockquote>
<h5><a class="anchor" name="command-scopes" href="#command-scopes"><i class="anchor-icon"></i></a>Command Scopes</h5>
<p>Your bot is able to <strong>show different commands</strong> to different users and groups – you can control this using <a href="/bots/api#botcommandscope">scopes</a>. For example, your bot could show additional commands to group admins or translate the list based on the user’s <a href="https://core.telegram.org/bots/api#user">language_code</a>.</p>
<blockquote>
<p>Keep in mind that Bot API <a href="https://core.telegram.org/bots/api#update">updates</a> <strong>will not contain any information</strong> about the scope of a command sent by the user – in fact, they may contain commands that don’t exist at all in your bot. Your backend should <strong>always</strong> verify that received commands are valid and that the user was authorized to use them regardless of scope.</p>
<p>Bots with privacy mode enabled will only receive commands in groups under special conditions, <a href="#privacy-mode">see here</a>.</p>
</blockquote>
<h4><a class="anchor" name="keyboards" href="#keyboards"><i class="anchor-icon"></i></a>Keyboards</h4>
<p>Bots are able to interpret free text input from users, but offering <strong>specific suggestions</strong> is often more intuitive – this is where <strong>custom keyboards</strong> can be extremely useful.</p>
<p>Whenever your bot sends a message, it can <strong>display a special keyboard</strong> with predefined reply options (see <a href="api#replykeyboardmarkup">ReplyKeyboardMarkup</a>). Telegram apps that receive the message will display your keyboard to the user. Using any of the buttons will immediately send the respective text. This way you can drastically <strong>simplify</strong> and <strong>streamline</strong> user interaction with your bot.</p>
<div>
<a href="/file/464001950/1191a/2RwpmgU-swU.123554/b50478c124d5914c23" target="_blank"><img src="/file/464001950/1191a/2RwpmgU-swU.123554/b50478c124d5914c23" title="Keyboards" class="dev_page_image" width=44% /></a>
</div>
<blockquote>
<p>Check out the <a href="/bots/api#replykeyboardmarkup">one_time_keyboard</a> parameter to automatically hide your bot&#39;s keyboard as soon as it&#39;s been used.</p>
</blockquote>
<h4><a class="anchor" name="inline-keyboards" href="#inline-keyboards"><i class="anchor-icon"></i></a>Inline Keyboards</h4>
<p>There are times when you&#39;d prefer to do things <strong>without sending any messages</strong> to the chat – like when a user is changing settings, toggling options or navigating search results. In such cases, you can use <a href="/bots/api#inlinekeyboardmarkup">Inline Keyboards</a> that are shown directly below their relevant messages.</p>
<p>Unlike with custom reply keyboards, pressing buttons on inline keyboards <strong>doesn&#39;t send messages to the chat</strong>. Instead, inline keyboards support buttons that can work behind the scenes or open different interfaces: <a href="/bots/api#inlinekeyboardbutton">callback buttons</a>, <a href="/bots/api#inlinekeyboardbutton">URL buttons</a>, <a href="/bots/api#inlinekeyboardbutton">switch-to-inline buttons</a>, <a href="/bots/api#inlinekeyboardbutton">game buttons</a> and <a href="/bots/api#inlinekeyboardbutton">payment buttons</a>. </p>
<div>
<a href="/file/464001863/110f3/I47qTXAD9Z4.120010/e0ea04f66357b640ec" target="_blank"><img src="/file/464001863/110f3/I47qTXAD9Z4.120010/e0ea04f66357b640ec" title="Inline Keyboard" class="dev_page_image" width=44% /></a>
</div>
<blockquote>
<p>To provide a <strong>better user experience</strong>, consider <a href="api#editmessagereplymarkup">editing your keyboard</a> when the user toggles a setting button or navigates to a new page – this is both <strong>faster</strong> and <strong>smoother</strong> than sending a whole new message and deleting the previous one.</p>
</blockquote>
<h4><a class="anchor" name="menu-button" href="#menu-button"><i class="anchor-icon"></i></a>Menu Button</h4>
<p>In all bot chats, a menu button appears near the message field. By default, tapping this button <strong>opens a menu</strong> that can hold some or all of a bot&#39;s commands, including a short description for each. Users can then <strong>select a command from the menu</strong> without needing to type it out.</p>
<p>You can set different texts of the menu button and its command descriptions for various <strong>individual users</strong> or <strong>groups of users</strong> – for example, showing translated text based on the user’s language, as explained <a href="#commands">here</a>.</p>
<div class="blog_video_player_wrap" style="max-width: 400px; margin: 20px auto 20px;">
<video class="blog_video_player tl_blog_vid_autoplay" onclick="videoTogglePlay(this)" autoplay="" loop="" controls="" muted="" poster="/file/464001581/11d85/f42u9c5Wncg.133752/b5a95b7f1221032d7d" style="max-width: 400px;" title="Bot Menu Button" alt="Video: Bot Menu Button">
<source src="/file/464001555/10fbd/jvTuV2Ke7WQ.1916669.mp4/a056de323645db409d" type="video/mp4">
</video>
</div>
<blockquote>
<p>Remember that you can also customize the text placeholder in the input field by setting the <code>input_field_placeholder</code> parameter.</p>
</blockquote>
<p>The <strong>menu button</strong> can alternatively be used to launch a <a href="#web-apps">Web App</a>.</p>
<h4><a class="anchor" name="global-commands" href="#global-commands"><i class="anchor-icon"></i></a>Global Commands</h4>
<p>To make basic interactions more uniform, we ask all developers to support a few <strong>basic commands</strong>. Telegram apps will have interface shortcuts for these commands.</p>
<ul>
<li>/start - begins the interaction with the user, like sending an introductory message. This command can also be used to pass additional parameters to the bot (see <a href="deep-linking">Deep Linking</a>).</li>
<li>/help - returns a help message, like a short text about what your bot can do and a list of commands.</li>
<li>/settings - (if applicable) shows the bot&#39;s settings for this user and suggests commands to edit them.</li>
</ul>
<p>Users will see a <strong>Start</strong> button the first time they open a chat with your bot. <strong>Help</strong> and <strong>Settings</strong> links will be available in the menu on the bot&#39;s profile page if you add them in <a href="https://t.me/botfather">@BotFather</a>.</p>
<hr>
<h3><a class="anchor" name="interactions" href="#interactions"><i class="anchor-icon"></i></a>Interactions</h3>
<p>In addition to sending commands and messages to the chat with the bot, there are several ways of interacting with them without opening any specific chat or group.</p>
<ul>
<li><a href="#inline-requests"><strong>Inline mode</strong></a> allows sending requests to bots right from the input field – from any chat on Telegram.</li>
<li><a href="#deep-linking"><strong>Deep linking</strong></a> allows special links that send certain parameters to the bot when opened.</li>
<li><a href="#attachment-menu"><strong>Attachment menu</strong></a> integration makes it possible to use bots from the attachment menu in chats.</li>
</ul>
<h4><a class="anchor" name="inline-requests" href="#inline-requests"><i class="anchor-icon"></i></a>Inline Requests</h4>
<p>Users can interact with your bot via <strong>inline queries</strong> straight from the message field <strong>in any chat</strong>. All they need to do is start a message with your bot&#39;s <em>@username</em> and enter a keyword.</p>
<p>Having received the query, your bot can return some results. As soon as the user selects one, it is sent to the <strong>relevant chat</strong>. This way, people can request and send content from your bot in any of their chats, groups or channels.</p>
<p>Remember that inline functionality has to be enabled via <a href="https://t.me/botfather">@BotFather</a>, or your bot will not receive inline <a href="api#update">Updates</a>.</p>
<div>
<a href="/file/464001466/10e4a/r4FKyQ7gw5g.134366/f2606a53d683374703" target="_blank"><img src="/file/464001466/10e4a/r4FKyQ7gw5g.134366/f2606a53d683374703" title="Inline Mode" class="dev_page_image" width=51%/></a>
</div>
<blockquote>
<p>Examples of inline bots include <a href="https://t.me/gif">@gif</a>, <a href="https://t.me/bing">@bing</a> and <a href="https://t.me/wiki">@wiki</a>.</p>
</blockquote>
<h4><a class="anchor" name="deep-linking" href="#deep-linking"><i class="anchor-icon"></i></a>Deep Linking</h4>
<p>Telegram bots have a deep linking mechanism that allows <strong>additional parameters</strong> to be passed to the bot on startup. It could be a command that launches the bot – or an authentication token to connect the user&#39;s Telegram account to their account on another platform.</p>
<p>Each bot has a link that <strong>opens a conversation</strong> with it in Telegram – <code>https://t.me/&lt;bot_username&gt;</code>. Parameters can be added directly to this link to let your bot work with additional information on the fly, without any user input.</p>
<blockquote>
<p>A-Z, a-z, 0-9, _ and - are allowed. We recommend using base64url to encode parameters with binary and other types of content. The parameter can be up to 64 characters long.</p>
</blockquote>
<p><strong>Private Chats</strong><br>In private chats, you can use the <code>start</code> parameter to automatically pass any value to your bot whenever a user presses the link. For example, you could use:</p>
<pre><code>https://t.me/your_bot?start=airplane</code></pre>
<p>When someone opens a chat with your bot via this link, you will receive:</p>
<pre><code>/start airplane</code></pre>
<p><strong>Groups</strong><br>In groups, you can add the parameter <code>startgroup</code> to this link. For example:</p>
<pre><code>https://t.me/your_bot?startgroup=spaceship</code></pre>
<p>Following a link with this parameter prompts the user to select a group to add the bot to – the resulting update will contain text in the form:</p>
<pre><code>/start@your_bot spaceship</code></pre>
<blockquote>
<p><a href="#web-apps">Web Apps</a> also support deep linking, for more information check out our <a href="/bots/webapps#adding-bots-to-the-attachment-menu">dedicated guide</a>.</p>
</blockquote>
<h4><a class="anchor" name="attachment-menu" href="#attachment-menu"><i class="anchor-icon"></i></a>Attachment Menu</h4>
<p>Certain bots can be added directly to a user’s <strong>attachment menu</strong> – giving them easy access to the bot in any chat. Currently, this option is restricted to certain <a href="Web-Bot-Doc">approved bots</a>, but may be expanded later.</p>
<div class="blog_video_player_wrap" style="max-width: 400px; margin: 20px auto 20px;">
<video class="blog_video_player tl_blog_vid_autoplay" onclick="videoTogglePlay(this)" autoplay="" loop="" controls="" muted="" poster="/file/464001491/11651/uwMWNdO29NE.215169/1b37285bbd8fc81244" style="max-width: 400px;" title="Attachment Menu" alt="Video: Bot Attachment Menu">
<source src="/file/464001177/11b03/ruSbBLQiLJ8.928268.mp4/d9ad95048d23f3cc3f" type="video/mp4">
</video>
</div>
<blockquote>
<p>Try adding <a href="https://t.me/durgerkingbot?startattach">@DurgerKingBot</a> to your attachment menu.</p>
</blockquote>
<hr>
<h3><a class="anchor" name="integration" href="#integration"><i class="anchor-icon"></i></a>Integration</h3>
<p>There are various ways of futher integrating bots with Telegram and other services.</p>
<ul>
<li>Use <a href="#web-apps">Web Apps</a> to replace any website.</li>
<li>Accept <a href="#payments">Payments</a> via dozens of integrated third-party payment providers.</li>
<li>Connect to Telegram using the <a href="#web-login">Web Login</a> functionality.</li>
<li>Create gaming bots by integrating <a href="#html5-games">HTML5 Games</a>.</li>
<li>Help users create and manage <a href="#stickers">Telegram Stickers</a>.</li>
</ul>
<h3><a class="anchor" name="web-apps" href="#web-apps"><i class="anchor-icon"></i></a>Web Apps</h3>
<p>Bots can easily process <strong>complex inputs</strong> of any kind and <strong>dynamic interaction flows</strong> via <a href="webapps">Web Apps</a>. With this unique feature, you can develop any number of flexible, streamlined interfaces in <strong>JavaScript</strong>.</p>
<blockquote>
<p>Web Apps are covered in detail in our <a href="webapps">dedicated guide</a> – you should read it carefully to learn the wide variety of features they can offer.</p>
</blockquote>
<div class="blog_video_player_wrap" style="max-width: 400px; margin: 20px auto 20px;">
<video class="blog_video_player tl_blog_vid_autoplay" onclick="videoTogglePlay(this)" autoplay="" loop="" controls="" muted="" poster="/file/464001434/100bf/eWprjdgzEbE.100386/644bbea83084f44c8f" style="max-width: 400px;" title="Attachment Menu" alt="Video: Bot Attachment Menu">
<source src="/file/464001679/11aa9/KQx_BlPVXRo.4922145.mp4/c65433c8ac11a347a8" type="video/mp4">
</video>
</div>
<p>If you develop a <strong>Web App</strong>, be sure to follow our <a href="webapps#design-guidelines">design guidelines</a> – you&#39;ll want your custom interface to <strong>seamlessly integrate</strong> into the app to provide users the best possible experience.</p>
<h3><a class="anchor" name="payments" href="#payments"><i class="anchor-icon"></i></a>Payments</h3>
<p>Telegram bots can accept payments with a sleek, streamlined interface that collects all necessary data from the user. Telegram <strong>doesn&#39;t collect</strong> any payment data – like the user&#39;s credit card information – and sends it directly to one of the supported <a href="payments#supported-payment-providers">payment providers</a>.</p>
<p>Here is a <strong>quick start guide</strong> to implement payments:</p>
<ul>
<li>Pick a <a href="payments#supported-payment-providers">provider</a> and obtain the <a href="payments#getting-a-token">proper token</a> as well as a <strong>test token</strong> from the &quot;<strong>Stripe TEST MODE</strong>&quot; provider.</li>
<li>Implement payments via the <a href="api#payments">appropriate API methods</a>.</li>
<li>Test your implementation by using your <strong>test token</strong> along with a <a href="https://stripe.com/docs/testing#cards">test credit card</a>.</li>
</ul>
<p>Then, to issue an <strong>invoice</strong> and process the order flow:</p>
<ul>
<li><a href="api#sendinvoice">Send an invoice</a> to the user for the goods or services you are offering.</li>
<li>Validate the order and accept the checkout via <a href="api#answerprecheckoutquery">answerPreCheckoutQuery</a>.</li>
<li>Confirm the payment by checking for a <a href="api#successfulpayment">successful payment service message</a>.</li>
<li>Ship the goods or provide the services.</li>
</ul>
<p>A full and exhaustive guide, including live checklist, parameters and in-depth method descriptions is available <a href="bots/payments">here</a>. We <strong>strongly recommend</strong> that you read the full guide before going live.</p>
<div>
<a href="/file/464001393/101fc/SB_bFCLR0tg.130549/7ecf91aaa44737e8cb" target="_blank"><img src="/file/464001393/101fc/SB_bFCLR0tg.130549/7ecf91aaa44737e8cb" title="Payments" class="dev_page_image" width=50% /></a>
</div>
<blockquote>
<p>Telegram does not directly process the payments, does not store data about orders and does not collect any fees. Invoices are forwarded directly to the payment provider.<br>For this reason, disputes must be solved between the user, the bot developer and the payment provider. You can read more about this in the <a href="https://telegram.org/privacy#7-third-party-payment-services">Privacy Policy</a>.</p>
</blockquote>
<h3><a class="anchor" name="web-login" href="#web-login"><i class="anchor-icon"></i></a>Web Login</h3>
<p>Telegram offers a <strong>flexible</strong>, <strong>lightweight</strong> and <strong>free</strong> framework to authenticate users on any website and app. This can be used to bridge your platform with Telegram, providing a smooth experience to your users. You can also freely rely on this framework to implement a <strong>fast</strong> and <strong>signup-free</strong> login on your site, regardless of its connection to Telegram.</p>
<h4><a class="anchor" name="widgets" href="#widgets"><i class="anchor-icon"></i></a>Widgets</h4>
<p>The Telegram login widget is a <strong>simple and secure way to authorize users</strong> on your website.</p>
<ol>
<li>Choose a bot – ideally its name and profile pic <strong>should match</strong> the website title and logo.</li>
<li>Use the <code>/setdomain</code> command in <a href="https://t.me/botfather">@BotFather</a> to pair the bot with your website domain. </li>
<li>Configure your widget using <a href="/widgets/login#widget-configuration">our dedicated tool</a> and embed it on your website.</li>
</ol>
<h4><a class="anchor" name="inline-login" href="#inline-login"><i class="anchor-icon"></i></a>Inline Login</h4>
<p>When users open your website via an <strong>inline button</strong>, you can use the <a href="/bots/api#loginurl">login_url</a> parameter as an alternative to login widgets. This way, you&#39;ll be able to <a href="https://telegram.org/blog/privacy-discussions-web-bots#meet-seamless-web-bots">seamlessly authorize</a> them on your website or app before the page even loads.</p>
<div>
<a href="/file/464001287/105ea/23bO4ntH4tc.43741/c9624e36c3462b6540" target="_blank"><img src="/file/464001287/105ea/23bO4ntH4tc.43741/c9624e36c3462b6540" width=50% title="Login Widget" class="dev_page_image" /></a>
</div>
<blockquote>
<p>Make sure to review our <a href="/widgets/login#checking-authorization">guide</a> on authenticating the received data as well as our <a href="https://gist.github.com/anonymous/6516521b1fb3b464534fbc30ea3573c2">sample code</a>.</p>
</blockquote>
<h3><a class="anchor" name="html5-games" href="#html5-games"><i class="anchor-icon"></i></a>HTML5 Games</h3>
<p>Bots can serve as <strong>standalone gaming platforms</strong> – with our <a href="api#games">HTML5 Gaming API</a> you can develop multiplayer or single-player games and let your users have fun comparing <strong>ranks</strong>, <strong>scores</strong> and much more.</p>
<p>To get started, follow these simple steps:</p>
<ul>
<li>Send the <code>/newgame</code> command to <a href="https://t.me/botfather">@BotFather</a></li>
<li>Provide a <strong>description text</strong>, an <strong>image</strong> or an <strong>optional gif</strong> to showcase its gameplay</li>
<li>Send the game to users via the <a href="api#sendgame">sendGame</a> method or via an <a href="api#inlinequeryresultgame">inline query</a></li>
<li>When someone wants to play, you&#39;ll receive the appropriate <code>game_short_name</code> in a <a href="api#callbackquery">CallbackQuery</a></li>
<li>To launch the game, provide the <strong>HTML5 Game URL</strong> as the <code>url</code> param of <a href="api#answercallbackquery">answerCallbackQuery</a></li>
</ul>
<p>Then, to handle <strong>highscores</strong>:</p>
<ul>
<li>Use <a href="api#setgamescore">setGameScore</a> to post high scores in the chat with the game</li>
<li>Use <a href="api#getgamehighscores">getGameHighScores</a> to get in-game high score tables</li>
</ul>
<p>You can also <strong>embed a share button</strong> within your game, play around with <strong>custom inline buttons</strong>, <strong>URL parameters</strong> and much more. To get a better idea, make sure to check out:</p>
<ul>
<li><a href="games">HTML5 Games Manual</a></li>
<li><a href="api#games">HTML5 Games Bot API Docs</a></li>
</ul>
<div>
<a href="/file/464001558/11b92/y_Fu9QQWtj0.141959/dc9db48f66800bf271" target="_blank"><img src="/file/464001558/11b92/y_Fu9QQWtj0.141959/dc9db48f66800bf271" title="Games" width=50% class="dev_page_image" /></a>
</div>
<blockquote>
<p>Check out <a href="https://t.me/gamebot">@GameBot</a> and <a href="https://t.me/gamee">@gamee</a> for examples of what you can do using our Gaming Platform.</p>
</blockquote>
<h3><a class="anchor" name="stickers" href="#stickers"><i class="anchor-icon"></i></a>Stickers</h3>
<p><a href="https://core.telegram.org/stickers">Stickers</a> are a distinctive Telegram feature used by millions of users to share artwork every day. Stickers take many forms – ranging from <strong>basic images</strong> to smooth <strong>vector animations</strong> and high-detail <strong>.WEBM videos</strong>.</p>
<p>All these formats are supported by our <a href="api#stickers">Bot API</a>, which allows bots to <strong>create</strong>, <strong>edit</strong>, <strong>delete</strong> and <strong>share</strong> new sticker packs on the fly. Telegram&#39;s <a href="https://core.telegram.org/import-stickers">Import API</a> lets users <strong>migrate packs</strong> from other platforms and sticker apps.</p>
<p>To create a <strong>new sticker pack</strong>, follow these simple steps:</p>
<ul>
<li><strong>Upload</strong> a new sticker file via <a href="api#uploadstickerfile">uploadStickerFile</a>. Repeat for all the stickers in the set. You will use the returned <a href="api#file">files</a> in the next step, so keep them around.</li>
<li><strong>Create</strong> a new sticker pack via <a href="api#createnewstickerset">createStickerSet</a>. Attach the <a href="api#file">files</a> you collected in <strong>step 1</strong> and remember to only specify <strong>one</strong> of the three avaiable fields – <code>png_sticker</code>, <code>tgs_sticker</code> and <code>webm_sticker</code> – depending on which sticker format you uploaded.</li>
<li><strong>Complete</strong> the pack by adding each remaining sticker in sequence via <a href="api#addstickertoset">addStickerToSet</a>.</li>
</ul>
<blockquote>
<p>Once you&#39;re done, don&#39;t forget to check out our <a href="api#stickers">remaining sticker methods</a> to find out how to <a href="api#setstickersetthumb">edit</a>, <a href="api#deletestickerfromset">delete</a> and even <a href="api#setstickerpositioninset">reorder</a> your pack.<br>Note that these methods will only work on packs <strong>created by the bot that is calling them</strong>.</p>
</blockquote>
<h3><a class="anchor" name="language-support" href="#language-support"><i class="anchor-icon"></i></a>Language Support</h3>
<p>Bots can tailor their interfaces to <strong>support multiple languages</strong> – updating inputs and information on the fly. A user’s in-app <a href="/bots/api#user">language_code</a> is included in every relevant <a href="api#Update">update</a> as an <a href="https://en.wikipedia.org/wiki/IETF_language_tag">IETF language tag</a>, allowing bots to adapt accordingly. </p>
<p>We recommend that you follow our guidelines to provide <strong>the best user experience</strong>.</p>
<ul>
<li>Your interfaces, texts and <a href="api#answerinlinequery">inline results</a> should adapt seamlessly to the <em>language_code</em>, without user intervention.</li>
<li>Connected <a href="/bots/webapps">WebApps</a> will receive the user&#39;s <em>language_code</em> – your HTML page should account for it.</li>
<li><a href="html5-games">HTML5 Games</a> can obtain language information if you specify it as a <a href="games#using-url-parameters">URL parameter</a>. You can generate this parameter from the <em>language_code</em> field in the <a href="api#User">User</a> object served with the initial game <a href="api#callbackquery">CallbackQuery</a>.</li>
<li>Command lists can also be specified for individual languages – more on this <a href="#commands">here</a>.</li>
</ul>
<div class="blog_video_player_wrap" style="max-width: 400px; margin: 20px auto 20px;">
<video class="blog_video_player tl_blog_vid_autoplay" onclick="videoTogglePlay(this)" autoplay="" loop="" controls="" muted="" poster="/file/464001822/10cd0/EvtvjnhA-kA.132475/e285952b505535d85a" style="max-width: 400px;" title="Language Support" alt="Video: Language Support">
<source src="/file/464001083/105cd/NF4ViAHfTJc.3601652.mp4/0fd787953c11a6371d" type="video/mp4">
</video>
</div>
<blockquote>
<p>The <em>language_code</em> is an <strong>optional field</strong> – it could be empty.<br>If you target the general public, your code should always fall back to either the last recorded language tag or English (in this order) when the field is missing for a specific user. </p>
</blockquote>
<hr>
<h3><a class="anchor" name="bot-management" href="#bot-management"><i class="anchor-icon"></i></a>Bot Management</h3>
<h4><a class="anchor" name="privacy-mode" href="#privacy-mode"><i class="anchor-icon"></i></a>Privacy Mode</h4>
<p>Bots are frequently added to groups to perform basic tasks or assist moderators – like automatically posting company announcements or even celebrating birthdays. By default, <strong>all bots</strong> added to groups run in Privacy Mode and only see relevant messages and commands:</p>
<ul>
<li>Commands explicitly meant for them (e.g., <code>/command@this_bot</code>).</li>
<li>General commands (e.g. <code>/start</code>) if the bot was the last bot to send a message to the group.</li>
<li>Inline messages sent <a href="api#inline-mode">via</a> the bot.</li>
<li>Replies to any messages implicitly or explicitly meant for this bot.</li>
</ul>
<p>All bots will also receive, <strong>regardless of privacy mode</strong>:</p>
<ul>
<li>All service messages.</li>
<li>All messages from private chats.</li>
<li>All messages from channels where they are a member.</li>
</ul>
<p>Privacy mode is <strong>enabled by default</strong> for all bots, except bots that were added to a group as admins (bot admins always receive <strong>all messages</strong>). 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 <strong>absolutely necessary</strong> for your bot to work. In most cases, using the force reply option for the bot&#39;s messages should be more than enough.</p>
<div>
<a href="/file/464001338/107af/JdbERa0BATg.62371/28977e9a96aed3860a" target="_blank"><img src="/file/464001338/107af/JdbERa0BATg.62371/28977e9a96aed3860a" title="Privacy Mode" class="dev_page_image" width=50%/></a>
</div>
<blockquote>
<p>This mode not only increases user privacy, but also makes the bot more efficient by reducing the number of inputs it needs to process. Users can always see a bot’s current privacy setting in the list of group members.</p>
</blockquote>
<h4><a class="anchor" name="status-alerts" href="#status-alerts"><i class="anchor-icon"></i></a>Status alerts</h4>
<p>Millions choose Telegram for its speed. To best benefit users, your bot also <strong>needs to be responsive</strong>. In order to help developers keep their bots in shape, <a href="https://t.me/botfather">@BotFather</a> will send <strong>status alerts</strong> if it sees something is wrong.</p>
<p>We check the number of replies and the <em>request/response</em> conversion rate for popular bots (~300 requests per minute, this value may change in the future). If your bot returns an <strong>abnormally low number</strong>, you will receive a notification from <a href="https://t.me/botfather">@BotFather</a>.</p>
<h5><a class="anchor" name="responding-to-alerts" href="#responding-to-alerts"><i class="anchor-icon"></i></a>Responding to alerts</h5>
<p>By default, <strong>you will only get one alert per bot per hour</strong>. </p>
<p>Each alert has the following buttons:</p>
<ul>
<li><strong>Fixed</strong> - 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.</li>
<li><strong>Support</strong> - Use this to open a chat with <a href="https://t.me/botsupport">@BotSupport</a> if you don&#39;t see any issues with your bot or if you think the problem is on our side.</li>
<li><strong>Mute for 8h/1w</strong> - Use this if you can&#39;t fix your bot at the moment. This will disable all alerts for the bot in question for the specified period of time. <strong>We do not recommend</strong> using this option since your users may migrate to a more stable bot. You can unmute alerts in your bot&#39;s settings via <a href="https://t.me/botfather">@BotFather</a>.</li>
</ul>
<h5><a class="anchor" name="monitored-issues" href="#monitored-issues"><i class="anchor-icon"></i></a>Monitored issues</h5>
<p>We currently notify you about the following issues:</p>
<ul>
<li><p><strong>Too few private messages are sent.</strong> Value: <strong>{value}</strong> - Your bot is sending far fewer messages than it did in previous weeks. This is useful for newsletter-style bots that send messages without prompts from users. The larger the value, the more significant the difference.</p>
</li>
<li><p><strong>Too few replies to incoming private messages</strong>. Conversion rate: <strong>{value}</strong> - 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). </p>
</li>
</ul>
<blockquote>
<p>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. <a href="api#sendmessage">sendMessage</a>).</p>
</blockquote>
<ul>
<li><strong>Too few answers to inline queries</strong>. Conversion rate: <strong>{value}</strong> - Your bot is not replying to all inline queries that are being sent to it, calculated in the same way as above. Respond to <code>inline_query</code> updates by calling <a href="api#answerInlineQuery">answerInlineQuery</a>.</li>
</ul>
<ul>
<li><strong>Too few answers to callback queries</strong>. Conversion rate: <strong>{value}</strong></li>
<li><strong>Too few answers to callback game queries</strong>. Conversion rate: <strong>{value}</strong> - 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 <code>callback_query</code> updates by calling <a href="api#answerCallbackQuery">answerCallbackQuery</a>.</li>
</ul>
<h4><a class="anchor" name="local-bot-api" href="#local-bot-api"><i class="anchor-icon"></i></a>Local Bot API</h4>
<p>You can host and work with <strong>your own instance</strong> of our open-source <a href="api">Bot API</a>.<br>The <strong>source code</strong> is available <a href="https://github.com/tdlib/telegram-bot-api">here</a>, along with a quick <a href="https://github.com/tdlib/telegram-bot-api#installation">installation guide</a>.</p>
<p>After <strong>installing the server</strong>, remember to use the <a href="api#logout">logOut</a> method before <strong>redirecting requests</strong> to your new local API URL.</p>
<blockquote>
<p>Your local instance runs on port <code>8081</code> by default and will only accept HTTP requests, so a TLS termination proxy has to be used to handle remote HTTPS requests.</p>
</blockquote>
<p>By hosting our API locally you&#39;ll gain access to <strong>some upgrades</strong>, including:</p>
<table class="table">
<thead>
<tr>
<th>API</th>
<th>Max File Download</th>
<th>Max File Upload</th>
<th>WHook URL</th>
<th>WHook Port</th>
<th>WHook Max Connections</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="api#making-requests">Official</a></td>
<td>20MB</td>
<td>50MB</td>
<td>HTTPS</td>
<td>443,80,88,8443</td>
<td>1-100</td>
</tr>
<tr>
<td><a href="api#using-a-local-bot-api-server">Local</a></td>
<td>Unlimited</td>
<td>2000MB</td>
<td>HTTP</td>
<td>Any port</td>
<td>1-100000</td>
</tr>
</tbody>
</table>
<blockquote>
<p>You can find an exhaustive list <a href="/bots/api#using-a-local-bot-api-server">here</a>.<br>All limits may be subject to change in the future, so make sure to follow <a href="https://t.me/botnews">@BotNews</a>.</p>
</blockquote>
<hr>
<h3><a class="anchor" name="botfather" href="#botfather"><i class="anchor-icon"></i></a>BotFather</h3>
<p>Below is a detailed guide to using <a href="https://t.me/botfather">@BotFather</a>, Telegram’s tool for <strong>creating</strong> and <strong>managing</strong> bots.</p>
<h4><a class="anchor" name="creating-a-new-bot" href="#creating-a-new-bot"><i class="anchor-icon"></i></a>Creating a new bot</h4>
<p>Use the <code>/newbot</code> command to create a new bot. <a href="https://t.me/botfather">@BotFather</a> will ask you for a name and username, then generate an authentication token for your new bot.</p>
<ul>
<li><p>The <strong>name</strong> of your bot is displayed in contact details and elsewhere.</p>
</li>
<li><p>The <strong>username</strong> is a short name, used in search, mentions and t.me links. Usernames are 5-32 characters long and not case sensitive – but may only include Latin characters, numbers, and underscores. Your bot&#39;s username must end in &#39;bot’, like &#39;tetris_bot&#39; or &#39;TetrisBot&#39;.</p>
</li>
<li><p>The <strong>token</strong> is a string, like <code>110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>, which is required to authorize the bot and send requests to the Bot API. Keep your token secure and store it safely, it can be used by anyone to control your bot. </p>
</li>
</ul>
<blockquote>
<p>Unlike the bot’s name, the username cannot be changed later – so choose it carefully.<br>When sending a request to api.telegram.org, remember to prefix the word ‘bot’ to your token.</p>
</blockquote>
<h4><a class="anchor" name="about-text-description-and-profile-media" href="#about-text-description-and-profile-media"><i class="anchor-icon"></i></a>About text, description and profile media</h4>
<p>When new users open your bot, they will be met with a helpful description in a box titled “What can this bot do?”.</p>
<p>Properly <a href="#edit-bots">setting this field</a> in <a href="https://t.me/botfather">@BotFather</a> allows everyone to immediately get an idea of what your bot can do – your description should be <strong>brief</strong>, <strong>to the point</strong> and <strong>on topic</strong>.</p>
<blockquote>
<p>You can also add a photo or video to this field with <code>Edit Description Picture</code> in <a href="https://t.me/botfather">@BotFather</a>.</p>
</blockquote>
<p>Additionally, just like normal users, bots also come with a <strong>short bio</strong> available on their profile. If you didn&#39;t specify this field while first creating your bot, you can set it at any time with the <code>/setabouttext</code> command in <a href="https://t.me/botfather">@BotFather</a>. Users can interact with many bots and they won&#39;t have access to their description after starting them – having a quick reminder of the bot&#39;s purpose can be very useful.</p>
<p>Bots can also have a <strong>profile picture</strong> – you should pick something unique and original so that users can find it in their chat list at a glance.</p>
<blockquote>
<p>Once set, the description, about text and profile pic can be <strong>replaced</strong> but never fully <strong>removed</strong>.</p>
</blockquote>
<h4><a class="anchor" name="generating-an-authentication-token" href="#generating-an-authentication-token"><i class="anchor-icon"></i></a>Generating an authentication token</h4>
<p>If your existing token is <strong>compromised</strong> or <strong>you lost it</strong> for some reason, use the <code>/token</code> command to generate a new one.</p>
<h4><a class="anchor" name="transfer-ownership" href="#transfer-ownership"><i class="anchor-icon"></i></a>Transfer ownership</h4>
<p>You can transfer ownership of your bot <strong>to another user</strong>.<br>To do this, send <code>/mybots</code>, select your bot, then <em>transfer ownership</em>.<br>You can only transfer a bot to users who have interacted with it at least once.</p>
<blockquote>
<p>Transferring ownership will give full control of the bot to another user – they will be able to access the bot’s messages and even delete it. The transfer is permanent, so please consider it carefully.</p>
</blockquote>
<h4><a class="anchor" name="botfather-commands" href="#botfather-commands"><i class="anchor-icon"></i></a>BotFather commands</h4>
<p>The remaining commands are pretty self-explanatory:</p>
<ul>
<li>/mybots – returns a list of your bots with handy controls to edit their settings.</li>
<li>/mygames – does the same for your games.</li>
</ul>
<h4><a class="anchor" name="edit-bots" href="#edit-bots"><i class="anchor-icon"></i></a>Edit bots</h4>
<p>To edit your bot, you have two options.</p>
<p>You can use the available commands:</p>
<ul>
<li>/setname – change your bot&#39;s <strong>name</strong>.</li>
<li>/setdescription – change the bot&#39;s <strong>description</strong> (short text up to 512 characters). Users will see this text at the beginning of the conversation with the bot, titled &#39;<em>What can this bot do?</em>&#39;.</li>
<li>/setabouttext – change the bot&#39;s <strong>about info</strong>, a shorter text up to 120 characters. Users will see this text on the bot&#39;s profile page. When they share your bot with someone, this text is sent together with the link.</li>
<li>/setuserpic – change the bot&#39;s <strong>profile picture</strong>. </li>
<li>/setcommands – change the list of <strong>commands</strong> supported by your bot. Users will see these commands as suggestions when they type <code>/</code> in the chat with your bot. See <a href="#commands">commands</a> for more info.</li>
<li>/setdomain – link a <strong>website domain</strong> to your bot. See the <a href="#login-widget">login widget</a> section.</li>
<li>/deletebot – delete your bot and <strong>free its username</strong>. Cannot be undone.</li>
</ul>
<p>Or you can use the <code>/mybots</code> command, tap on your bot and use the modern inline interface to edit it.</p>
<h4><a class="anchor" name="edit-settings" href="#edit-settings"><i class="anchor-icon"></i></a>Edit settings</h4>
<ul>
<li>/setinline – toggle <strong>inline mode</strong> for your bot.</li>
<li>/setinlinegeo – request <strong>location data</strong> to provide location-based inline results.</li>
<li>/setjoingroups – toggle whether your bot can be <strong>added to groups</strong> or not. All bots must be able to process direct messages, but if your bot was not designed to work in groups, you can disable this.</li>
<li>/setinlinefeedback – toggle whether the API should <strong>send updates about the results</strong> chosen by users. See an in-depth explanation <a href="/bots/inline#collecting-feedback">here</a>.</li>
<li>/setprivacy – set which messages your bot will receive when added to a group. See <a href="#privacy-mode">privacy-mode</a> for more info.</li>
</ul>
<h4><a class="anchor" name="manage-games" href="#manage-games"><i class="anchor-icon"></i></a>Manage games</h4>
<ul>
<li>/newgame – create a new game.</li>
<li>/listgames – see a list of your games.</li>
<li>/editgame – edit a game.</li>
<li>/deletegame – delete an existing game.</li>
</ul>
<blockquote>
<p>Please note that it may take a few minutes for changes to take effect.</p>
</blockquote>
<hr>
<p>With this information, you are ready to proceed to our <a href="api">Full API Reference for Developers</a>.</p>
<ul>
<li>If you have any questions, check out our <a href="faq">Bot FAQ</a>.</li>
<li>If you&#39;re experiencing issues with our API, please contact <a href="https://t.me/botsupport">@BotSupport</a> on Telegram.</li>
</ul>
</div>
</div>
</div>
</div>
<div class="footer_wrap">
<div class="footer_columns_wrap footer_desktop">
<div class="footer_column footer_column_telegram">
<h5>Telegram</h5>
<div class="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
</div>
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
<ul>
<li><a href="//telegram.org/faq">FAQ</a></li>
<li><a href="//telegram.org/privacy">Privacy</a></li>
<li><a href="//telegram.org/press">Press</a></li>
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
<ul>
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
<li><a href="//telegram.org/android">Android</a></li>
<li><a href="//telegram.org/dl/web">Mobile Web</a></li>
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
<ul>
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
<li><a href="//macos.telegram.org/">macOS</a></li>
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
</ul>
</div>
<div class="footer_column footer_column_platform">
<h5><a href="/">Platform</a></h5>
<ul>
<li><a href="/api">API</a></li>
<li><a href="//translations.telegram.org/">Translations</a></li>
<li><a href="//instantview.telegram.org/">Instant View</a></li>
</ul>
</div>
</div>
<div class="footer_columns_wrap footer_mobile">
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/blog">Blog</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps">Apps</a></h5>
</div>
<div class="footer_column">
<h5><a href="/">Platform</a></h5>
</div>
<div class="footer_column">
<h5><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)">Twitter</a></h5>
</div>
</div>
</div>
</div>
<script src="/js/main.js?46"></script>
<script src="/js/jquery.min.js?1"></script>
<script src="/js/bootstrap.min.js?1"></script>
<script>window.initDevPageNav&&initDevPageNav();
backToTopInit("Go up");
removePreloadInit();
</script>
</body>
</html>

590
data/web/core.telegram.org/bots/tutorial.html Normal file
View file

@ -0,0 +1,590 @@
<!DOCTYPE html>
<html class="">
<head>
<meta charset="utf-8">
<title>From BotFather to &#39;Hello World&#39;</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta property="description" content="Building your first bot">
<meta property="og:title" content="From BotFather to &#39;Hello World&#39;">
<meta property="og:image" content="">
<meta property="og:description" content="Building your first bot">
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
<link href="/css/telegram.css?232" rel="stylesheet" media="screen">
<style>
</style>
</head>
<body class="preload">
<div class="dev_page_wrap">
<div class="dev_page_head navbar navbar-static-top navbar-tg">
<div class="navbar-inner">
<div class="container clearfix">
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
<ul class="nav navbar-nav">
<li><a href="//telegram.org/">Home</a></li>
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
<li class=""><a href="/api">API</a></li>
<li class=""><a href="/mtproto">Protocol</a></li>
<li class=""><a href="/schema">Schema</a></li>
</ul>
</div>
</div>
</div>
<div class="container clearfix">
<div class="dev_page">
<div id="dev_page_content_wrap" class=" ">
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/bots" >Telegram Bots</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/bots/tutorial" >From BotFather to &#39;Hello World&#39;</a></li></ul></div>
<h1 id="dev_page_title">From BotFather to &#39;Hello World&#39;</h1>
<div id="dev_page_content"><!-- scroll_nav -->
<p>This guide will walk you through everything you need to know to build your first <strong>Telegram Bot</strong>.<br>If you already know your way around some of the basic steps, you can jump directly to the part you&#39;re missing. Equivalent examples are available in <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.cs">C#</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.py">Python</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.go">Go</a> and <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/tree/main/Nodejs">TypeScript</a> .</p>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#getting-ready"><strong>Basic Tutorial</strong></a></li>
</ul>
<div id="dev_page_content">
<ul style="padding-left: 30px;">
<li style="margin-top: -5px"><a href="#getting-ready">Environment</a></li>
<li><a href="#first-run">First Run</a></li>
<li><a href="#echo-bot">Echo Bot</a></li>
</ul>
</div>
<ul>
<li><a href="#executing-commands"><strong>Advanced Tutorial</strong></a></li>
</ul>
<div id="dev_page_content">
<ul style="padding-left: 30px;">
<li style="margin-top: -5px"><a href="#executing-commands">Commands</a></li>
<li><a href="#navigation">Navigation</a></li>
<li><a href="#database">Database</a></li>
<li><a href="#hosting">Hosting</a></li>
</ul>
</div>
<ul>
<li><a href="#further-reading">Further Reading</a></li>
</ul>
<hr>
<h3><a class="anchor" name="introduction" href="#introduction"><i class="anchor-icon"></i></a>Introduction</h3>
<p>At its core, you can think of the Telegram <a href="api">Bot API</a> as software that provides <a href="https://en.wikipedia.org/wiki/JSON">JSON-encoded</a> responses to your queries.</p>
<p>A bot, on the other hand, is essentially a routine, software or script that queries the API by means of an <a href="https://core.telegram.org/bots/api#making-requests">HTTPS request</a> and waits for a response. There are several types of <a href="api#available-methods">requests</a> you can make, as well as many different <a href="api#available-types">objects</a> that you can use and receive as responses.</p>
<p>Since <strong>your browser</strong> is capable of sending HTTPS requests, you can use it to quickly try out the API. After <a href="#obtain-your-bot-token">obtaining your token</a>, try pasting this string into your browser:</p>
<pre><code>https://api.telegram.org/bot&lt;YOUR_BOT_TOKEN&gt;/getMe</code></pre>
<p>In theory, you could interact with the API with <strong>basic requests</strong> like this, either via your browser or other tailor-made tools like <a href="https://curl.se/">cURL</a>. While this can work for simple requests like the example above, it&#39;s not practical for larger applications and doesn&#39;t scale well.<br>For that reason, this guide will show you how to use <a href="samples">libraries and frameworks</a>, along with some <strong>basic programming skills</strong>, to build a more robust and scalable project.</p>
<p>If you know how to code, you&#39;ll fly right through each step in no time – and if you&#39;re just starting out, this guide will show you everything you need to learn.</p>
<blockquote>
<p>We will use <a href="https://en.wikipedia.org/wiki/Java_%28programming_language%29">Java</a> throughout this guide as it&#39;s one of the most popular programming languages, however, you can follow along with any language as all the steps are fundamentally the same.<br>Since Java is fully cross-platform, each code example will work with any operating system.<br>If you pick another language, equivalent examples are available in <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.cs">C#</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.py">Python</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.go">Go</a> and <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/tree/main/Nodejs">TypeScript</a> .</p>
</blockquote>
<h3><a class="anchor" name="getting-ready" href="#getting-ready"><i class="anchor-icon"></i></a>Getting Ready</h3>
<p>First, we will briefly cover how to <strong>create your first project</strong>, obtain your <strong>API token</strong> and download all necessary <strong>dependencies and libraries</strong>.</p>
<h4><a class="anchor" name="obtain-your-bot-token" href="#obtain-your-bot-token"><i class="anchor-icon"></i></a>Obtain Your Bot Token</h4>
<p>In this context, a <strong>token</strong> is a string that authenticates your bot (not your account) on the bot API. Each bot has a unique token which can also be revoked at any time via <a href="https://t.me/botfather">@BotFater</a>.</p>
<p>Obtaining a token is as simple as contacting <a href="https://t.me/botfather">@BotFater</a>, issuing the <code>/newbot</code> command and following the steps until you&#39;re given a new token. You can find a step-by-step guide <a href="features#creating-a-new-bot">here</a>.</p>
<p>Your token will look something like this:</p>
<pre><code>4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc</code></pre>
<blockquote>
<p>Make sure to save your token in a secure place, treat it like a password and <strong>don&#39;t share it with anyone</strong>.</p>
</blockquote>
<h4><a class="anchor" name="download-an-ide" href="#download-an-ide"><i class="anchor-icon"></i></a>Download an IDE</h4>
<p>To program in Java you&#39;ll need an <a href="https://en.wikipedia.org/wiki/Integrated_development_environment">IDE</a> – a special text editor that will let you write, compile and run your code.<br>In this tutorial, we&#39;ll use IntelliJ – there are several free, open source alternatives like <a href="https://www.eclipse.org/ide/">Eclipse</a> or <a href="https://netbeans.apache.org/download/index.html">NetBeans</a> which work in the exact same way.</p>
<p>You will also need a <a href="https://en.wikipedia.org/wiki/Java_Development_Kit">JDK</a>, a software kit that allows your Java code to run.<br>Most IDEs don&#39;t include a JDK, so you should download a version compatible with your operating system separately. You can find a free, open source version <a href="https://adoptium.net/temurin/releases/">here</a>.</p>
<blockquote>
<p>If you use another language, the steps are identical. You will just have to download a different IDE and software development kit.</p>
</blockquote>
<h4><a class="anchor" name="pick-a-framework-or-library" href="#pick-a-framework-or-library"><i class="anchor-icon"></i></a>Pick a Framework or Library</h4>
<p>You can think of a framework as software that handles all the low-level logic for you, including the API calls, and lets you focus on your bot-specific logic.</p>
<p>In this tutorial, we&#39;ll use <a href="https://github.com/rubenlagus/TelegramBots">TelegramBots</a>, but you can follow along with any equivalent implementation, since all the underlying methods are either similar or exactly the same.</p>
<blockquote>
<p>You can find many frameworks, along with code examples, in <a href="samples">our dedicated list</a>.</p>
</blockquote>
<h4><a class="anchor" name="create-your-project" href="#create-your-project"><i class="anchor-icon"></i></a>Create Your Project</h4>
<p>In IntelliJ, go to <code>File &gt; New &gt; Project</code>.</p>
<p>Fill in the fields accordingly:</p>
<ul>
<li><strong>Name</strong> - The name of your project. For example, <em>BotTutorial</em>.</li>
<li><strong>Location</strong> - Where to store your project. You can use the default value.</li>
<li><strong>Language</strong> - Java</li>
<li><strong>Build System</strong> - The framework that will handle your dependencies. Pick <em>Maven</em>.</li>
<li><strong>JDK</strong> - Pick whichever version you downloaded. We&#39;ll be using version <em>17</em>.</li>
<li><strong>Add Sample Code</strong> - Leave this <strong>selected</strong>, it will generate some needed files for you.</li>
<li><strong>Advanced Settings &gt; GroupId</strong> - We suggest <em>tutorial</em>.</li>
<li><strong>Advanced Settings &gt; ArtifactId</strong> - You can use the default value.</li>
</ul>
<p>After hitting <em>Create</em>, if you did everything correctly, your <strong>Project</strong> view in the top left should show a <strong>project structure</strong> along these lines:</p>
<pre><code>BotTutorial
├─ .idea
├─ src
│ └─ main
│ └─ java
│ └─ tutorial
│ └─ Main
└─ pom.xml</code></pre>
<blockquote>
<p>Other IDEs will follow a similar pattern. Your dependency management system will have a different name (or no name at all if it&#39;s built-in) depending on the language you chose.</p>
</blockquote>
<p>If this looks scary, don&#39;t worry. We will only be using the <code>Main</code> file and the <code>pom.xml</code> file.<br>In fact, to check that everything is working so far, double click on <em>Main</em> and click on the small green arrow on the left of <em>public class Main</em>, then select the first option.<br>If you followed the steps correctly, <em>Hello world!</em> should appear in the console below.</p>
<h4><a class="anchor" name="add-framework-dependency" href="#add-framework-dependency"><i class="anchor-icon"></i></a>Add Framework Dependency</h4>
<p>We will now instruct the IDE to download and configure everything needed to work with the API.<br>This is very easy and happens automatically behind the scenes.</p>
<p>First, locate your <code>pom.xml</code> file on the left side of the screen.<br>Open it by double-clicking and simply add:</p>
<pre><code>&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.telegram&lt;/groupId&gt;
&lt;artifactId&gt;telegrambots&lt;/artifactId&gt;
&lt;version&gt;6.0.1&lt;/version&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;</code></pre>
<p>right after the <code>&lt;/properties&gt;</code> tag.</p>
<p>When you&#39;re done, your <code>pom.xml</code> should look something like <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/pom.xml">this</a>.</p>
<h3><a class="anchor" name="start-coding" href="#start-coding"><i class="anchor-icon"></i></a>Start Coding</h3>
<p>We are ready to start coding. If you&#39;re a beginner, consider that being familiar with your language of choice will greatly help. With this tutorial, you&#39;ll be able to teach your bot basic behaviors, though more advanced features will require some coding experience.</p>
<h4><a class="anchor" name="creating-a-bot-class" href="#creating-a-bot-class"><i class="anchor-icon"></i></a>Creating a Bot Class</h4>
<p>If you&#39;re familiar with <a href="https://en.wikipedia.org/wiki/Object-oriented_programming">object-oriented programming</a>, you&#39;ll know what a class is.<br>If you&#39;ve never heard of it before, consider a class as a file where you write some logic.</p>
<p>To <strong>create the class</strong> that will contain the bot logic, right click on <em>tutorial</em> from the project tree on the left and select <em>New &gt; Java Class</em>. Name it <em>Bot</em> and hit enter.</p>
<p>Now we have to connect this class to the bot framework. In other words, we must make sure it extends <code>TelegramLongPollingBot</code>. To do that, just add <em>extends TelegramLongPollingBot</em> right after <em>Bot</em>.<br>A red line will appear – it simply means we&#39;re missing some important methods.</p>
<p>To fix this, hover over the red line, click on <em>implement methods</em>, then hit OK.<br>Depending on the IDE, this option may be called <em>implement missing methods</em> or something similar.</p>
<p>You should end up with this – if something went wrong, feel free to copy it from here and paste it in your class:</p>
<pre><code>package tutorial;
import org.telegram.telegrambots.bots.TelegramLongPollingBot;
import org.telegram.telegrambots.meta.api.objects.Update;
public class Bot extends TelegramLongPollingBot {
@Override
public String getBotUsername() {
return null;
}
@Override
public String getBotToken() {
return null;
}
@Override
public void onUpdateReceived(Update update) {}
}</code></pre>
<blockquote>
<p>If you get a red line under TelegramLongPollingBot, it means you didn&#39;t set up your pom.xml correctly. If this is the case, restart from <a href="#add-framework-dependency">here</a>.</p>
</blockquote>
<h4><a class="anchor" name="available-methods" href="#available-methods"><i class="anchor-icon"></i></a>Available Methods</h4>
<p>Let&#39;s look into these 3 methods one by one.</p>
<ul>
<li><strong>getBotUsername</strong> - This method must be edited to always return your bot&#39;s username. You should replace the <em>null</em> return value with it.</li>
<li><strong>getBotToken</strong> - This method will be used by the framework to retrieve your bot token. You should replace the <em>null</em> return value with the token.</li>
<li><strong>onUpdateReceived</strong> - This is the most important method. It will be called automatically whenever a new Update is available. Let&#39;s add a <code>System.out.println(update);</code> call in there to quickly show what we are getting.</li>
</ul>
<p>After you&#39;ve replaced all the strings, you should end up with this:</p>
<pre><code>@Override
public String getBotUsername() {
return &quot;TutorialBot&quot;;
}
@Override
public String getBotToken() {
return &quot;4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc&quot;;
}
@Override
public void onUpdateReceived(Update update) {
System.out.println(update);
}</code></pre>
<p>At this point, the bot is configured and ready to go – time to register it on the API and start processing updates.</p>
<blockquote>
<p>In the future, you should consider storing your token in a dedicated settings file or in <a href="https://en.wikipedia.org/wiki/Environment_variable">environment variables</a>. Keeping it in the code is fine for the scope of this tutorial, however, it&#39;s not very versatile and is generally considered bad practice. </p>
</blockquote>
<h4><a class="anchor" name="registering-the-bot" href="#registering-the-bot"><i class="anchor-icon"></i></a>Registering the Bot</h4>
<p>To <strong>register the bot</strong> on the API, simply add a couple of lines <strong>in the main method</strong> that will launch the application. If you named your class <code>Bot</code>, this is what your main method should look like:</p>
<pre><code>public static void main(String[] args) throws TelegramApiException {
TelegramBotsApi botsApi = new TelegramBotsApi(DefaultBotSession.class);
botsApi.registerBot(new Bot());
}</code></pre>
<blockquote>
<p>You can place this method in any class. Since we have an auto-generated <code>main</code> method in the Main class, we&#39;ll be using that one for this tutorial.</p>
</blockquote>
<h3><a class="anchor" name="first-run" href="#first-run"><i class="anchor-icon"></i></a>First Run</h3>
<p>It&#39;s time to <strong>run your bot</strong> for the first time.<br>Hit the green arrow to the left of <code>public static void main</code> and select the first option.</p>
<p><em>And then there was nothing</em>. Yes, a bit anticlimactic.<br>This is because your bot <strong>has nothing to print</strong> – there are <strong>no new updates</strong> because nobody messaged it yet.</p>
<p>If you try messaging the bot on Telegram, you&#39;ll then see <strong>new updates</strong> pop up in the console. At this point, you have your very own Telegram Bot – quite the achievement. Now, on to making it a bit more intelligent.</p>
<blockquote>
<p>If nothing pops up, make sure you messaged the right bot and that the token you pasted in the code is correct.</p>
</blockquote>
<h3><a class="anchor" name="receiving-messages" href="#receiving-messages"><i class="anchor-icon"></i></a>Receiving Messages</h3>
<p>Every time someone sends a <strong>private message</strong> to your bot, your <code>onUpdateReceived</code> method will be called automatically and you&#39;ll be able to handle the <code>update</code> parameter, which contains the <strong>message</strong>, along with a great deal of other info which you can see detailed <a href="api#update">here</a>.</p>
<p>Let&#39;s focus on two values for now:</p>
<ul>
<li><strong>The user</strong> - Who sent the message. Access it via <code>update.getMessage().getFrom()</code>.</li>
<li><strong>The message</strong> - What was sent. Access it via <code>update.getMessage()</code>.</li>
</ul>
<p>Knowing this, we can make it a bit more clear in the <strong>console output</strong>.</p>
<pre><code>@Override
public void onUpdateReceived(Update update) {
var msg = update.getMessage();
var user = msg.getFrom();
System.out.println(user.getFirstName() + &quot; wrote &quot; + msg.getText());
}</code></pre>
<p>This is just a basic example – you can now play around with all the methods to see everything you can pull out of these objects. You can try <code>getUsername</code>, <code>getLanguageCode</code>, and dozens more.</p>
<p>Knowing how to receive, process and print <strong>incoming messages</strong>, now it&#39;s time to learn how to <strong>answer them</strong>.</p>
<blockquote>
<p>Remember to stop and re-launch your bot after each change to the code.</p>
</blockquote>
<h3><a class="anchor" name="sending-messages" href="#sending-messages"><i class="anchor-icon"></i></a>Sending Messages</h3>
<p>To send a private text message, you generally need <strong>three things</strong>:</p>
<ul>
<li>The user <strong>must</strong> have contacted your bot first. (Unless the user sent a join request to a group where your bot is an admin, but that&#39;s a more advanced scenario).</li>
<li>You <strong>must</strong> have previously saved the <strong>User ID</strong> (<code>user.getId()</code>)</li>
<li>A <code>String</code> object containing the message text, 1-4096 characters.</li>
</ul>
<p>With that out of the way, let&#39;s create a <strong>new method</strong> to send the first message:</p>
<pre><code>public void sendText(Long who, String what){
SendMessage sm = SendMessage.builder()
.chatId(who.toString()) //Who are we sending a message to
.text(what).build(); //Message content
try {
execute(sm); //Actually sending the message
} catch (TelegramApiException e) {
throw new RuntimeException(e); //Any error will be printed here
}
}</code></pre>
<p>And proceed to run this in the <code>main</code> method, right after registering the bot.<br>For this example, we&#39;ll assume your User ID is <code>1234</code>.</p>
<pre><code>public static void main(String[] args) throws TelegramApiException {
TelegramBotsApi botsApi = new TelegramBotsApi(DefaultBotSession.class);
Bot bot = new Bot(); //We moved this line out of the register method, to access it later
botsApi.registerBot(bot);
bot.sendText(1234L, &quot;Hello World!&quot;); //The L just turns the Integer into a Long
}</code></pre>
<p>If you did everything correctly, your bot should text you <em>Hello World!</em> every time you launch your code. Sending messages to groups or channels – assuming you have the relevant permissions – is as simple as replacing <code>1234</code> with the ID of the respective chat.</p>
<blockquote>
<p>Try experimenting with other types of messages, like SendPhoto, SendSticker, SendDice…<br>A full list is available starting <a href="https://core.telegram.org/bots/api#sendmessage">here</a>.</p>
</blockquote>
<h3><a class="anchor" name="echo-bot" href="#echo-bot"><i class="anchor-icon"></i></a>Echo Bot</h3>
<p>Let&#39;s practice everything we tried so far by coding an <strong>Echo Bot</strong>.<br>Its functionality will be rather simple: every text message it receives will be sent right back to the user.</p>
<h4><a class="anchor" name="copying-text" href="#copying-text"><i class="anchor-icon"></i></a>Copying Text</h4>
<p>The most intuitive way of coding this is saving the User ID and calling <code>sendText</code> right after each update.</p>
<p>In other words:</p>
<pre><code>@Override
public void onUpdateReceived(Update update) {
var msg = update.getMessage();
var user = msg.getFrom();
var id = user.getId();
sendText(id, msg.getText());
}</code></pre>
<p>This works for text but can be extended to stickers, media and files.</p>
<h4><a class="anchor" name="copying-everything" href="#copying-everything"><i class="anchor-icon"></i></a>Copying Everything</h4>
<p>There are more specific functions that can be used to copy messages and send them back.<br>Let&#39;s build a method to do just that:</p>
<pre><code>public void copyMessage(Long who, Integer msgId){
CopyMessage cm = CopyMessage.builder()
.fromChatId(who.toString()) //We copy from the user
.chatId(who.toString()) //And send it back to him
.messageId(msgId) //Specifying what message
.build();
try {
execute(cm);
} catch (TelegramApiException e) {
throw new RuntimeException(e);
}
}</code></pre>
<p>After replacing the method call in<code>onUpdateReceived</code>, running the code will result in a fully functional <strong>Echo Bot</strong>.</p>
<blockquote>
<p>This tutorial assumes that updates always contain messages for the sake of simplicity. This may not always be true – be sure to implement all the proper checks in your code to handle every type of update with the appropriate methods.</p>
</blockquote>
<h3><a class="anchor" name="executing-commands" href="#executing-commands"><i class="anchor-icon"></i></a>Executing Commands</h3>
<p>To learn what a command is and how it works, we recommend reading this <a href="features#commands">dedicated summary</a>.<br>In this guide, we&#39;ll focus on the technical side of things.</p>
<h4><a class="anchor" name="creating-your-command" href="#creating-your-command"><i class="anchor-icon"></i></a>Creating Your Command</h4>
<p>Begin by opening <a href="https://t.me/botfather">@BotFater</a>.<br>Type <code>/mybots</code> &gt; <em>Your_Bot_Name</em> &gt; Edit Bot &gt; Edit Commands.</p>
<p>Now send a new command, followed by a brief description.<br>For the purpose of this tutorial, we&#39;ll implement two simple commands:</p>
<pre><code>scream - Speak, I&#39;ll scream right back
whisper - Shhhhhhh</code></pre>
<h4><a class="anchor" name="command-logic" href="#command-logic"><i class="anchor-icon"></i></a>Command Logic</h4>
<p>We want the <strong>Echo Bot</strong> to reply in uppercase when it&#39;s in <strong>scream mode</strong> and normally otherwise.</p>
<p>First, let&#39;s <strong>create a variable</strong> to store the current mode.</p>
<pre><code>public class Bot extends TelegramLongPollingBot {
private boolean screaming = false;
[...]
}</code></pre>
<p>Then, let&#39;s change some logic to <strong>account for this mode</strong>.</p>
<pre><code>public void onUpdateReceived(Update update) {
[...] //Same variables as the previous versions
if(screaming) //If we are screaming
scream(id, update.getMessage()); //Call a custom method
else
copyMessage(id, msg.getMessageId()); //Else proceed normally
}
private void scream(Long id, Message msg) {
if(msg.hasText())
sendText(id, msg.getText().toUpperCase());
else
copyMessage(id, msg.getMessageId()); //We can&#39;t really scream a sticker
}</code></pre>
<p>Finally, let&#39;s add a couple more lines to the <code>onUpdateReceived</code> method to process each command before replying.</p>
<pre><code>if(msg.isCommand()){
if(msg.getText().equals(&quot;/scream&quot;)) //If the command was /scream, we switch gears
screaming = true;
else if (msg.getText().equals(&quot;/whisper&quot;)) //Otherwise, we return to normal
screaming = false;
return; //We don&#39;t want to echo commands, so we exit
}</code></pre>
<p>As you can see, it checks if the message <strong>is a command</strong>. If it is, the bot enters <strong>scream mode</strong>.<br>In the update method, we check <strong>which mode we are in</strong> and either copy the message or convert it to upper case before <strong>sending it back</strong>.</p>
<p>And that&#39;s it. Now the bot can <strong>execute commands</strong> and change its behavior accordingly.</p>
<p>Naturally, this simplified logic will change the bot&#39;s behavior for <strong>everyone</strong> – not just the person who sent the command. This can be fun for this tutorial but <strong>won&#39;t work in a production environment</strong> – consider using a Map, dictionary or equivalent data structure to assign settings for individual users.</p>
<blockquote>
<p>Remember to always implement a few basic <a href="features#global-commands">global commands</a>.<br>You can practice by implementing a simple feedback to the <code>/start</code> command, which we intentionally left out.</p>
</blockquote>
<h3><a class="anchor" name="buttons-and-keyboards" href="#buttons-and-keyboards"><i class="anchor-icon"></i></a>Buttons and Keyboards</h3>
<p>To streamline and simplify user interaction with your bot, you can replace many text-based exchanges with handy buttons. These buttons can perform a wide variety of actions and can be customized for each user.</p>
<h4><a class="anchor" name="button-types" href="#button-types"><i class="anchor-icon"></i></a>Button Types</h4>
<p>There are two main types of buttons:</p>
<ul>
<li><strong>Reply Buttons</strong> - used to provide a list of predefined text <a href="features#keyboards">reply options</a>.</li>
<li><strong>Inline Buttons</strong> - used to offer quick navigation, shortcuts, URLs, games and <a href="features##inline-keyboards">so much more</a>.</li>
</ul>
<p>Using these buttons is as easy as attaching a <code>ReplyKeyboardMarkup</code> or an <code>InlineKeyboardMarkup</code> to your <code>SendMessage</code> object.</p>
<p>This guide will focus on <strong>inline buttons</strong> since they only require a few extra lines of code.</p>
<h4><a class="anchor" name="creating-buttons" href="#creating-buttons"><i class="anchor-icon"></i></a>Creating Buttons</h4>
<p>First of all, let&#39;s create some buttons.</p>
<pre><code> var next = InlineKeyboardButton.builder()
.text(&quot;Next&quot;).callbackData(&quot;next&quot;)
.build();
var back = InlineKeyboardButton.builder()
.text(&quot;Back&quot;).callbackData(&quot;back&quot;)
.build();
var url = InlineKeyboardButton.builder()
.text(&quot;Tutorial&quot;)
.url(&quot;https://core.telegram.org/bots/api&quot;)
.build();</code></pre>
<p>Let&#39;s go back through the fields we specified:</p>
<ul>
<li><strong>Text</strong> - This is what the user will see, the text that appears on the button</li>
<li><strong>Callback Data</strong> - This will be sent back to the code instance as part of a new <code>Update</code>, so we can quickly identify what button was clicked.</li>
<li><strong>Url</strong> - A button that specifies a URL doesn&#39;t specify callbackdata since its behavior is predefined – it will open the given link when tapped.</li>
</ul>
<h4><a class="anchor" name="creating-keyboards" href="#creating-keyboards"><i class="anchor-icon"></i></a>Creating Keyboards</h4>
<p>The <strong>buttons</strong> we created can be assembled into two <strong>keyboards</strong>, which will then be used to navigate back and forth between two <strong>sample menus</strong>.</p>
<p>First, <strong>add two fields</strong> to store the necessary keyboards.</p>
<pre><code>private boolean screaming = false;
private InlineKeyboardMarkup keyboardM1;
private InlineKeyboardMarkup keyboardM2;</code></pre>
<p>Then, <strong>build</strong> and <strong>assign</strong> them.</p>
<pre><code>keyboardM1 = InlineKeyboardMarkup.builder()
.keyboardRow(List.of(next)).build();
//Buttons are wrapped in lists since each keyboard is a set of button rows
keyboardM2 = InlineKeyboardMarkup.builder()
.keyboardRow(List.of(back))
.keyboardRow(List.of(url))
.build();</code></pre>
<blockquote>
<p>You can place this code wherever you prefer, the important thing is making sure that keyboard variables are accessible from the method call that will send the new menu. If you&#39;re confused by this concept and don&#39;t know where to put them, just paste them above the command processing flow.</p>
</blockquote>
<h4><a class="anchor" name="sending-keyboards" href="#sending-keyboards"><i class="anchor-icon"></i></a>Sending Keyboards</h4>
<p>Sending a keyboard only requires specifying a reply markup for the message.</p>
<pre><code>public void sendMenu(Long who, String txt, InlineKeyboardMarkup kb){
SendMessage sm = SendMessage.builder().chatId(who.toString())
.parseMode(&quot;HTML&quot;).text(txt)
.replyMarkup(kb).build();
try {
execute(sm);
} catch (TelegramApiException e) {
throw new RuntimeException(e);
}
}</code></pre>
<blockquote>
<p>You may have noticed that we also added a new parameter, <code>HTML</code>.<br>This is called a <a href="api#formatting-options">formatting option</a> and will allow us to use HTML tags and add formatting to the text later on.</p>
</blockquote>
<h4><a class="anchor" name="menu-trigger" href="#menu-trigger"><i class="anchor-icon"></i></a>Menu Trigger</h4>
<p>We could send a new menu for each new user, but for simplicity let&#39;s add a new command that will spawn a menu. We can achieve this by adding a new <strong>else clause</strong> to the previous command flow.</p>
<pre><code> var txt = msg.getText();
if(msg.isCommand()) {
if (txt.equals(&quot;/scream&quot;))
screaming = true;
else if (txt.equals(&quot;/whisper&quot;))
screaming = false;
else if (txt.equals(&quot;/menu&quot;))
sendMenu(id, &quot;&lt;b&gt;Menu 1&lt;/b&gt;&quot;, keyboard1);
return;
}</code></pre>
<p>Try sending <code>/menu</code> to your bot now. If you did everything correctly, you should see a brand new menu pop up.</p>
<blockquote>
<p>In a production environment, commands should be handled with an appropriate design pattern that isolates them into different executor classes – modular and separated from the main logic.</p>
</blockquote>
<h3><a class="anchor" name="navigation" href="#navigation"><i class="anchor-icon"></i></a>Navigation</h3>
<p>When building complex bots, navigation is essential. Your users must be able to move seamlessly from one menu to the next. </p>
<p>In this example, we want the <code>Next</code> button to lead the user to the second menu.<br>The <code>Back</code> button will send us back.<br>To do that, we will start processing incoming <code>CallbackQueries</code>, which are the results we get after the user taps on a button.</p>
<p>A <code>CallbackQuery</code> is essentially composed of three main parameters:</p>
<ul>
<li><strong>queryId</strong> - Needed to close the query. You <strong>must always</strong> close new queries after processing them – if you don&#39;t, a loading symbol will keep showing on the user&#39;s side on top of each button.</li>
<li><strong>data</strong> - This identifies which button was pressed.</li>
<li><strong>from</strong> - The user who pressed the button.</li>
</ul>
<p>Processing in this context just means <strong>executing the action</strong> uniquely identified by the button, then <strong>closing the query</strong>.</p>
<p>A very basic button handler could look something like:</p>
<pre><code>private void buttonTap(Long id, String queryId, String data, int msgId) {
EditMessageText newTxt = EditMessageText.builder()
.chatId(id.toString())
.messageId(msgId).text(&quot;&quot;).build();
EditMessageReplyMarkup newKb = EditMessageReplyMarkup.builder()
.chatId(id.toString()).messageId(msgId).build();
if(data.equals(&quot;next&quot;)) {
newTxt.setText(&quot;MENU 2&quot;);
newKb.setReplyMarkup(keyboardM2);
} else if(data.equals(&quot;back&quot;)) {
newTxt.setText(&quot;MENU 1&quot;);
newKb.setReplyMarkup(keyboardM1);
}
AnswerCallbackQuery close = AnswerCallbackQuery.builder()
.callbackQueryId(queryId).build();
execute(close);
execute(newTxt);
execute(newKb);
}</code></pre>
<p>With this handler, whenever a button is tapped, your bot will automatically navigate between inline menus.<br>Expanding on this concept allows for endless combinations of navigable submenus, settings and dynamic pages.</p>
<h3><a class="anchor" name="database" href="#database"><i class="anchor-icon"></i></a>Database</h3>
<p>Telegram <strong>does not</strong> host an update database for you – once you process and consume an update, it will no longer be available. This means that features like user lists, message lists, current user inline menu, settings, etc. <strong>have to be implemented and maintained</strong> by bot developers.</p>
<p>If your bot needs one of these features and you want to get started on <strong>data persistence</strong>, we recommend that you look into <a href="https://en.wikipedia.org/wiki/Serialization">serialization</a> practices and libraries for your language of choice, as well as available databases.</p>
<p>Implementing a database is out of scope for this guide, however, several guides are available online for simple embedded <strong>open source</strong> software solutions like <a href="https://www.sqlite.org/index.html">SQLite</a>, <a href="https://hsqldb.org/">HyperSQL</a>, <a href="https://db.apache.org/derby/">Derby</a> and many more.</p>
<blockquote>
<p>Your language of choice will also influence which databases are available and supported – the list above assumes you followed this Java tutorial.</p>
</blockquote>
<h3><a class="anchor" name="hosting" href="#hosting"><i class="anchor-icon"></i></a>Hosting</h3>
<p>So far, your bot has been running on your <strong>local machine</strong> – your PC. While this may be good for <strong>developing</strong>, <strong>testing</strong> and <strong>debugging</strong>, it is not ideal for a production environment.<br>You&#39;ll want your bot to be available and responsive at all times, but your computer might not always be online.</p>
<p>This can be done in four steps:</p>
<ul>
<li><p><strong>Package your code</strong><br>Making your bot <strong>easy to move</strong> and <strong>runnable</strong> outside of an IDE is essential to <strong>host it elsewhere</strong>.<br>If you followed this tutorial, this <a href="https://www.jetbrains.com/help/idea/compiling-applications.html#run_packaged_jar">standard guide</a> will work for you. If you didn&#39;t, look into <strong>export or packaging guides</strong> for your IDE and language of choice – procedures may vary but the end result is the same.</p>
</li>
<li><p><strong>Purchase a VPS or equivalent service</strong><br>A server is essentially a machine that is always online and running, without you having to worry about anything. To host your bot, you can opt for a <a href="https://en.wikipedia.org/wiki/Virtual_private_server">VPS</a> which serves this purpose and can be rented from several different providers.<br>Another option would be to purchase a network-capable <a href="https://en.wikipedia.org/wiki/Microcontroller">microcontroller</a>, which come in all different specs and sizes depending on your needs.</p>
</li>
</ul>
<blockquote>
<p>You should ensure that all user data remains <strong>heavily encrypted at all times</strong> in your database to guarantee the privacy of your users. The same concept applies to your local instance, however, this becomes especially important once you transfer your database to a remote server.</p>
</blockquote>
<ul>
<li><strong>Upload your executable/package</strong></li>
</ul>
<p>Once you have a working <a href="https://en.wikipedia.org/wiki/Secure_Shell">ssh</a> connection between your machine and your new server, you should upload your executable and all associated files.<br>We will assume the runnable jar <code>TutorialBot.jar</code> and its database <code>dbase.db</code> are currently in the <code>/TBot</code> folder.</p>
<pre><code>$ scp -r /TBot/ username@server_ip:/bots/TBotRemote/</code></pre>
<ul>
<li><strong>Run your application</strong></li>
</ul>
<p>Depending on which language you chose, you might have to configure your server environment differently. If you chose Java, you just need to install a compatible JDK.</p>
<pre><code>$ apt install openjdk-17-jre
$ java -version</code></pre>
<p>If you did everything correctly, you should see a Java version as the output, along with a few other values. This means you&#39;re ready to run your application.</p>
<p>Now, to run the executable:</p>
<pre><code>$ cd /bots/TBotRemote/
$ java -jar TutorialBot.jar</code></pre>
<p>Your bot is now online and users can interact with it at any time.</p>
<blockquote>
<p>To streamline and modularize this process, you could employ a specialized <a href="https://www.docker.com/resources/what-container/">docker container</a> or equivalent service.<br>If you followed along in one of the equivalent examples (<a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.cs">C#</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.py">Python</a>, <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/blob/main/TutorialBot.go">Go</a> and <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/tree/main/Nodejs">TypeScript</a>) you can find a detailed set of instructions to export and run your code <a href="https://gitlab.com/Athamaxy/telegram-bot-tutorial/-/tree/main/">here</a>.</p>
</blockquote>
<h3><a class="anchor" name="further-reading" href="#further-reading"><i class="anchor-icon"></i></a>Further Reading</h3>
<p>If you got this far, you might be interested in these additional guides and docs:</p>
<ul>
<li><a href="/bots">General Bot Platform Overview</a></li>
<li><a href="/bots/features">Detailed List of Bot Features</a></li>
<li><a href="/bots/api">Full API Reference</a></li>
</ul>
<p>If you encounter any issues while following this guide, you can contact us on Telegram at <a href="https://t.me/botsupport">@BotSupport</a>.</p>
</div>
</div>
</div>
</div>
<div class="footer_wrap">
<div class="footer_columns_wrap footer_desktop">
<div class="footer_column footer_column_telegram">
<h5>Telegram</h5>
<div class="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
</div>
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
<ul>
<li><a href="//telegram.org/faq">FAQ</a></li>
<li><a href="//telegram.org/privacy">Privacy</a></li>
<li><a href="//telegram.org/press">Press</a></li>
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
<ul>
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
<li><a href="//telegram.org/android">Android</a></li>
<li><a href="//telegram.org/dl/web">Mobile Web</a></li>
</ul>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
<ul>
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
<li><a href="//macos.telegram.org/">macOS</a></li>
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
</ul>
</div>
<div class="footer_column footer_column_platform">
<h5><a href="/">Platform</a></h5>
<ul>
<li><a href="/api">API</a></li>
<li><a href="//translations.telegram.org/">Translations</a></li>
<li><a href="//instantview.telegram.org/">Instant View</a></li>
</ul>
</div>
</div>
<div class="footer_columns_wrap footer_mobile">
<div class="footer_column">
<h5><a href="//telegram.org/faq">About</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/blog">Blog</a></h5>
</div>
<div class="footer_column">
<h5><a href="//telegram.org/apps">Apps</a></h5>
</div>
<div class="footer_column">
<h5><a href="/">Platform</a></h5>
</div>
<div class="footer_column">
<h5><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)">Twitter</a></h5>
</div>
</div>
</div>
</div>
<script src="/js/main.js?46"></script>
<script src="/js/jquery.min.js?1"></script>
<script src="/js/bootstrap.min.js?1"></script>
<script>window.initDevPageNav&&initDevPageNav();
backToTopInit("Go up");
removePreloadInit();
</script>
</body>
</html>