mirror of
https://github.com/MarshalX/telegram-crawler.git
synced 2024-12-04 22:15:07 +01:00
437 lines
39 KiB
HTML
437 lines
39 KiB
HTML
<!DOCTYPE html>
|
||
<html class="">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<title>Bots: An introduction for developers</title>
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta property="description" content="Bots are third-party applications that run inside Telegram. Users can interact with bots by sending them messages, commands…">
|
||
<meta property="og:title" content="Bots: An introduction for developers">
|
||
<meta property="og:image" content="75f7c457f2561cbf84">
|
||
<meta property="og:description" content="Bots are third-party applications that run inside Telegram. Users can interact with bots by sending them messages, commands…">
|
||
<link rel="shortcut icon" href="/favicon.ico?4" type="image/x-icon" />
|
||
|
||
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
|
||
|
||
<link href="/css/telegram.css?226" 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"></div>
|
||
<h1 id="dev_page_title">Bots: An introduction for developers</h1>
|
||
|
||
<div id="dev_page_content"><!-- scroll_nav -->
|
||
|
||
<p>Bots are third-party applications that run inside Telegram. Users can interact with bots by sending them messages, commands and <a href="#inline-mode">inline requests</a>. You control your bots using HTTPS requests to Telegram's <a href="/bots/api">Bot API</a>.</p>
|
||
<blockquote>
|
||
<p>The <a href="/bots/api">full API reference</a> for <strong>developers</strong> is available <a href="/bots/api">here</a>.</p>
|
||
</blockquote>
|
||
<h3><a class="anchor" name="1-what-can-i-do-with-bots" href="#1-what-can-i-do-with-bots"><i class="anchor-icon"></i></a>1. What can I do with bots?</h3>
|
||
<div class="dev_side_image">
|
||
<a href="/file/811140081/1/VldnlW70g2I/a140b0216e7d156ebc" target="_blank"><img src="/file/811140663/1/uHVzwsRJz3Y/a499733c59840694ca" title="A chat with a bot also showing search results from the @gif inline-bot"/></a>
|
||
</div>
|
||
|
||
<p>To name just a few things, you could use bots to:</p>
|
||
<ul>
|
||
<li><p><strong>Get customized notifications and news</strong>. A bot can act as a smart newspaper, sending you relevant content as soon as it's published.</p>
|
||
</li>
|
||
<li><p><strong>Integrate with other services</strong>. A bot can enrich Telegram chats with content from external services.<br><a href="https://t.me/gmailbot"><strong>Gmail Bot</strong></a>, <a href="https://t.me/gif"><strong>GIF bot</strong></a>, <a href="https://t.me/imdb"><strong>IMDB bot</strong></a>, <a href="https://t.me/wiki"><strong>Wiki bot</strong></a>, <a href="https://t.me/music"><strong>Music bot</strong></a>, <a href="https://t.me/youtube"><strong>Youtube bot</strong></a>, <a href="https://t.me/githubbot"><strong>GitHubBot</strong></a></p>
|
||
</li>
|
||
<li><p><strong>Accept payments from Telegram users</strong>. A bot can offer paid services or work as a virtual storefront. <a href="/bots/payments">Read more »</a><br><a href="https://t.me/shopbot"><strong>Demo Shop Bot</strong></a>, <a href="https://t.me/teststore"><strong>Demo Store</strong></a></p>
|
||
</li>
|
||
<li><p><strong>Create custom tools</strong>. A bot may provide you with alerts, weather forecasts, translations, formatting or other services.<br><a href="https://t.me/Bold"><strong>Markdown bot</strong></a>, <a href="https://t.me/sticker"><strong>Sticker bot</strong></a>, <a href="https://t.me/vote"><strong>Vote bot</strong></a>, <a href="https://t.me/like"><strong>Like bot</strong></a></p>
|
||
</li>
|
||
<li><p><strong>Build single- and multiplayer games</strong>. A bot can offer rich <a href="/bots/games">HTML5 experiences</a>, from simple arcades and puzzles to 3D-shooters and real-time strategy games.<br><a href="https://t.me/gamebot"><strong>GameBot</strong></a>, <a href="https://t.me/gamee"><strong>Gamee</strong></a></p>
|
||
</li>
|
||
<li><p><strong>Build social services</strong>. A bot could connect people looking for conversation partners based on common interests or proximity.</p>
|
||
</li>
|
||
<li><p><strong>Do virtually anything else</strong>. Except for dishes — bots are terrible at doing the dishes.</p>
|
||
</li>
|
||
</ul>
|
||
<h3><a class="anchor" name="2-how-do-bots-work" href="#2-how-do-bots-work"><i class="anchor-icon"></i></a>2. How do bots work?</h3>
|
||
<p>At the core, Telegram Bots are special accounts that do not require an additional phone number to set up. Users can interact with bots in two ways:</p>
|
||
<ul>
|
||
<li>Send messages and <a href="#commands">commands</a> to bots by opening a chat with them or by adding them to groups.</li>
|
||
<li>Send requests directly from the input field by typing the bot's @username and a query. This allows sending content from <a href="/bots/inline">inline bots</a> directly into any chat, group or channel.</li>
|
||
</ul>
|
||
<p>Messages, commands and requests sent by users are passed to the software running on your servers. Our intermediary server handles all encryption and communication with the Telegram API for you. You communicate with this server via a simple HTTPS-interface that offers a simplified version of the Telegram API. We call that interface our <a href="/bots/api">Bot API</a>.</p>
|
||
<blockquote>
|
||
<p>A detailed description of the Bot API is available on <a href="/bots/api">this page »</a></p>
|
||
</blockquote>
|
||
<h3><a class="anchor" name="3-how-do-i-create-a-bot" href="#3-how-do-i-create-a-bot"><i class="anchor-icon"></i></a>3. How do I create a bot?</h3>
|
||
<div class="dev_side_image">
|
||
<a href="/file/811140327/1/zlN4goPTupk/9ff2f2f01c4bd1b013" target="_blank"><img src="/file/811140763/1/PihKNbjT8UE/03b57814e13713da37" title="The Botfather. Click for hi-res picture"/></a>
|
||
</div>
|
||
|
||
<p>There's a… bot for that. Just talk to <a href="https://t.me/botfather">BotFather</a> (described <a href="#6-botfather">below</a>) and follow a few simple steps. Once you've created a bot and received your authentication token, head down to the <a href="/bots/api">Bot API manual</a> to see what you can teach your bot to do.</p>
|
||
<blockquote>
|
||
<p>You may also like to check out some <strong>code examples</strong> <a href="/bots/samples">here »</a></p>
|
||
</blockquote>
|
||
<h3><a class="anchor" name="4-how-are-bots-different-from-humans" href="#4-how-are-bots-different-from-humans"><i class="anchor-icon"></i></a>4. How are bots different from humans?</h3>
|
||
<ul>
|
||
<li>Bots have no online status and no last seen timestamps, the interface shows the label <strong>'bot'</strong> instead.</li>
|
||
<li>Bots have limited cloud storage — older messages may be removed by the server shortly after they have been processed.</li>
|
||
<li>Bots can't initiate conversations with users. A user <strong>must</strong> either add them to a group or send them a message first. People can use <code>t.me/<bot_username></code> links or username search to find your bot.</li>
|
||
<li>Bot usernames always end in 'bot' (e.g. <a href="https://t.me/triviabot">@TriviaBot</a>, <a href="https://t.me/githubbot">@GitHub_bot</a>).</li>
|
||
<li>When added to a group, bots do not receive all messages by default (see <a href="#privacy-mode">Privacy mode</a>).</li>
|
||
<li>Bots never eat, sleep or complain (unless expressly programmed otherwise).</li>
|
||
</ul>
|
||
<hr>
|
||
<h3><a class="anchor" name="5-bot-perks" href="#5-bot-perks"><i class="anchor-icon"></i></a>5. Bot perks</h3>
|
||
<p>Telegram bots are unique in many ways — we offer <a href="#keyboards">two</a> <a href="#inline-keyboards-and-on-the-fly-updating">kinds</a> of keyboards, additional interfaces for <a href="#global-commands">default commands</a> and <a href="#deep-linking">deep linking</a> as well as <a href="/bots/api#formatting-options">text formatting</a>, <a href="#payment-platform">integrated payments</a> and more.</p>
|
||
<h4><a class="anchor" name="inline-mode" href="#inline-mode"><i class="anchor-icon"></i></a>Inline mode</h4>
|
||
<!--<div class="dev_side_image">
|
||
<a href="/file/811140221/1/fW9vnLya4Fg/e2b5c530c7b0e019c4" target="_blank"><img src="/file/811140530/1/h-eMmPp2vp4/cd4a109f75e6561305" title="Inline bots. Click for hi-res picture">
|
||
</a></div>-->
|
||
|
||
<p>Users can interact with your bot via <a href="/bots/api#inline-mode"><strong>inline queries</strong></a> straight from the <strong>text input field</strong> in <strong>any</strong> chat. All they need to do is start a message with your bot's username and then type a query.</p>
|
||
<p>Having received the query, your bot can return some results. As soon as the user taps one of them, it is sent to the user's currently opened chat. This way, people can request content from your bot in any of their chats, groups or channels.</p>
|
||
<p>Check out this <a href="https://telegram.org/blog/inline-bots">blog</a> to see a sample inline bot in action. You can also try the <a href="https://t.me/sticker">@sticker</a> and <a href="https://t.me/music">@music</a> bots to see for yourself.</p>
|
||
<div><center>
|
||
<a href="/file/811140558/1/POjp00-nHqE/50d0312845a05e6da9" target="_blank"><img src="/file/811140558/1/POjp00-nHqE/50d0312845a05e6da9" title="New input field" style="width: 295px; padding: 10px 0px;" /></a></center>
|
||
|
||
</div>
|
||
|
||
<p>We've also implemented an easy way for your bot to <a href="/bots/inline#switching-inline-pm-modes">switch between inline and PM modes</a>.</p>
|
||
<blockquote>
|
||
<p><a href="/bots/inline">Read more about the Inline Mode »</a></p>
|
||
</blockquote>
|
||
<h4><a class="anchor" name="payment-platform" href="#payment-platform"><i class="anchor-icon"></i></a>Payment platform</h4>
|
||
<!--<div class="dev_side_image">
|
||
<a href="/file/811140227/2/ZTXUngAbELM.193805/ba6aa233d1d4206207" target="_blank"><img src="/file/811140095/1/lfTvDVqVS8M.43169/1a191248e6cf027581" title="Payments API. Click for hi-res picture">
|
||
</a></div>-->
|
||
|
||
<p>You can use bots to <strong>accept payments</strong> from Telegram users around the world.</p>
|
||
<ul>
|
||
<li>Send invoices to <strong>any chat</strong>, including to groups and channels.</li>
|
||
<li>Create invoices that can be <strong>forwarded</strong> and used by <strong>multiple buyers</strong> to order things.</li>
|
||
<li>Use <a href="/bots/inline">inline mode</a> to help users show your goods and services to their friends and communities.</li>
|
||
<li>Allow <strong>tips</strong> from users with preset and custom amounts.</li>
|
||
<li>Accept payments from users on mobile or <strong>desktop apps</strong>.</li>
|
||
<li>Try <a href="https://t.me/shopbot">@ShopBot</a> to create a test invoice – or start a message with <code>@ShopBot ...</code> in any chat for an <strong>inline invoice</strong>.</li>
|
||
<li>Check out <a href="https://telegram.org/teststore">Demo Shop</a> for an example of a <a href="https://telegram.org/tour/channels">Telegram Channel</a> used as <strong>virtual storefront</strong>.</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/464001377/1/0o3vSvY22g8.123356/deb4ed6951d780f7b7" style="max-width: 400px;" title="If your pizza place can't deliver a clone army, you're buying pizza from the wrong shop." alt="Video: Ordering a pizza through a Telegram channel">
|
||
<source src="/file/464001705/2/Hg-klQnZ_n4.4889245.mp4/d324511ffdab7b4668" type="video/mp4">
|
||
</video>
|
||
</div>
|
||
|
||
<blockquote>
|
||
<p><a href="/bots/payments">Read more about the Payments Platform »</a></p>
|
||
</blockquote>
|
||
<h4><a class="anchor" name="gaming-platform" href="#gaming-platform"><i class="anchor-icon"></i></a>Gaming platform</h4>
|
||
<p>Bots can offer their users <strong>HTML5 games</strong> to play solo or to compete against each other in groups and one-on-one chats. The platform allows your bot to keep track of <strong>high scores</strong> for every game played in every chat. Whenever there’s a new leader in the game, other playing members in the chat are notified that they need to step it up. </p>
|
||
<div><center>
|
||
<a href="/file/811140306/1/dkciuEDbpxU.193188/8a0a21b6e9d111be4c" target="_blank"><img src="/file/811140306/1/dkciuEDbpxU.193188/8a0a21b6e9d111be4c" title="Game in a chat" style="width: 250px; padding: 10px 5px" /></a>
|
||
<a href="/file/811140426/1/ZCw3vu_v8s0.109692/04efd9e88644939a4f" target="_blank"><img src="/file/811140426/1/ZCw3vu_v8s0.109692/04efd9e88644939a4f" title="In-game scoreboard and sharing button" style="width: 250px; padding: 10px 5px" /></a>
|
||
</center>
|
||
</div>
|
||
|
||
<p>Since the underlying technology is HTML5, the games can be anything from simple arcades and puzzles to multiplayer 3D-shooters and real-time strategy games. Our team has created a couple of simple demos for you to try out:</p>
|
||
<ul>
|
||
<li><a href="https://t.me/gamebot?game=MathBattle">Math Battle</a></li>
|
||
<li><a href="https://t.me/gamebot?game=Lumberjack">Lumberjack</a></li>
|
||
<li><a href="https://t.me/gamebot?game=Corsairs">Corsairs</a></li>
|
||
</ul>
|
||
<p>You can also check out the <a href="https://t.me/gamee"><strong>@gamee</strong></a> bot that has more than 20 games.</p>
|
||
<blockquote>
|
||
<p><a href="https://telegram.org/blog/games">Read more about the Gaming Platform »</a></p>
|
||
</blockquote>
|
||
<h4><a class="anchor" name="keyboards" href="#keyboards"><i class="anchor-icon"></i></a>Keyboards</h4>
|
||
<p>Traditional chat bots can of course be taught to understand human language. But sometimes you want some more formal input from the user — and this is where <strong>custom keyboards</strong> can become extremely useful.</p>
|
||
<p>Whenever your bot sends a message, it can pass along a special keyboard with predefined reply options (see <a href="/bots/api/#replykeyboardmarkup">ReplyKeyboardMarkup</a>). Telegram apps that receive the message will display your keyboard to the user. Tapping any of the buttons will immediately send the respective command. This way you can drastically simplify user interaction with your bot.</p>
|
||
<p>We currently support text and emoji for your buttons. Here are some custom keyboard examples:</p>
|
||
<center>
|
||
<div>
|
||
<a href="/file/811140184/1/5YJxx-rostA/ad3f74094485fb97bd" target="_blank"><img src="/file/811140184/1/5YJxx-rostA/ad3f74094485fb97bd" title="Keyboard for a poll bot" style="max-height: 300px; padding: 10px 5px" /></a>
|
||
|
||
<a href="/file/811140880/1/jS-YSVkDCNQ/b397dfcefc6da0dc70" target="_blank"><img src="/file/811140880/1/jS-YSVkDCNQ/b397dfcefc6da0dc70" title="Keyboard for a calculator bot. Because you can." style="max-height: 300px; padding: 10px 5px" /></a>
|
||
|
||
<a href="/file/811140733/2/KoysqJKQ_kI/a1ee46a377796c3961" target="_blank"><img src="/file/811140733/2/KoysqJKQ_kI/a1ee46a377796c3961" title="Keyboard for a trivia bot" style="max-height: 300px; padding: 10px 5px" /></a>
|
||
|
||
|
||
</div></center>
|
||
|
||
<blockquote>
|
||
<p>For more technical information on custom keyboards, please consult the <a href="/bots/api">Bot API manual</a> (see <a href="/bots/api#sendmessage">sendMessage</a>).</p>
|
||
</blockquote>
|
||
<h4><a class="anchor" name="inline-keyboards-and-on-the-fly-updating" href="#inline-keyboards-and-on-the-fly-updating"><i class="anchor-icon"></i></a>Inline keyboards and on-the-fly updating</h4>
|
||
<p>There are times when you'd prefer to do things without sending any messages to the chat. For example, when your user is changing settings or flipping through search results. In such cases you can use Inline Keyboards that are integrated directly into the messages they belong to. </p>
|
||
<p>Unlike with custom reply keyboards, pressing buttons on inline keyboards doesn't result in messages sent to the chat. Instead, inline keyboards support buttons that work behind the scenes: <a href="/bots/2-0-intro#callback-buttons">callback buttons</a>, <a href="/bots/2-0-intro#url-buttons">URL buttons</a> and <a href="/bots/2-0-intro#switch-to-inline-buttons">switch to inline buttons</a>.</p>
|
||
<div><center>
|
||
<a href="/file/811140217/1/NkRCCLeQZVc/17a804837802700ea4" target="_blank"><img src="/file/811140217/1/NkRCCLeQZVc/17a804837802700ea4" title="Callback buttons in @music" style="width: 240px; padding: 10px 5px;" /></a>
|
||
<a href="/file/811140659/1/RRJyulbtLBY/ea6163411c7eb4f4dc" target="_blank"><img src="/file/811140659/1/RRJyulbtLBY/ea6163411c7eb4f4dc" title="More callback buttons in @music" style="width: 240px; padding: 10px 5px;" /></a>
|
||
<a href="/file/811140999/1/2JSoUVlWKa0/4fad2e2743dc8eda04" target="_blank"><img src="/file/811140999/1/2JSoUVlWKa0/4fad2e2743dc8eda04" title="A URL button" style="width:240px; padding:10px 5px"/></a>
|
||
|
||
</center>
|
||
|
||
</div>
|
||
|
||
<p>When callback buttons are used, your bot can update its existing messages (or just their keyboards) so that the chat remains tidy. Check out these sample bots to see inline keyboards in action: <a href="https://t.me/music">@music</a>, <a href="https://t.me/vote">@vote</a>, <a href="https://t.me/like">@like</a>.</p>
|
||
<blockquote>
|
||
<p><a href="/bots/2-0-intro#new-inline-keyboards">Read more about inline keyboards and on-the-fly editing »</a></p>
|
||
</blockquote>
|
||
<h4><a class="anchor" name="commands" href="#commands"><i class="anchor-icon"></i></a>Commands</h4>
|
||
<p>Commands present a more flexible way to communicate with your bot. The following syntax may be used:</p>
|
||
<pre><code>/command</code></pre>
|
||
<p>A command must always start with the '/' symbol and may not be longer than 32 characters. Commands can use latin letters, numbers and underscores. Here are a few examples:</p>
|
||
<pre><code>/get_messages_stats
|
||
/set_timer 10min Alarm!
|
||
/get_timezone London, UK</code></pre>
|
||
<p>Messages that start with a slash are always passed to the bot (along with replies to its messages and messages that @mention the bot by username). Telegram apps will:</p>
|
||
<ul>
|
||
<li>Suggest a list of supported commands with descriptions when the user enters a '/' (for this to work, you need to have provided a list of commands to the <a href="#6-botfather">BotFather</a>). Tapping on a command in the list immediately sends the command.</li>
|
||
<li>Show an additional <strong>(/)</strong> button in the input field in all chats with bots. Tapping it types a '/' and shows the list of commands.</li>
|
||
<li>Highlight <strong>/commands</strong> in messages. When the user taps a highlighted command, the command is sent at once.</li>
|
||
</ul>
|
||
<center><div>
|
||
<a href="/file/811140845/2/rNUxpcGDeQU/05eaaf20b0dbaf9cb3" target="_blank"><img src="/file/811140845/2/rNUxpcGDeQU/05eaaf20b0dbaf9cb3" title="Suggested commands" style="width: 230px; padding: 10px 5px" /></a>
|
||
|
||
<a href="/file/811140315/2/gf7_D2HbeyM/e3ca2de4de7918f826" target="_blank"><img src="/file/811140315/2/gf7_D2HbeyM/e3ca2de4de7918f826" title="Notice the new button in the input field, right next to the sticker button" style="width: 230px; padding: 10px 5px" /></a>
|
||
|
||
|
||
<a href="/file/811140029/1/s5zv4fbWdhw/a04aefa0ee0557f16a" target="_blank"><img src="/file/811140029/1/s5zv4fbWdhw/a04aefa0ee0557f16a" title="Suggested commands for multiple bots" style="width: 230px; padding: 10px 5px" /></a>
|
||
|
||
</div></center>
|
||
|
||
|
||
<p>If multiple bots are in a group, it is possible to add bot usernames to commands in order to avoid confusion:</p>
|
||
<pre><code>/start@TriviaBot
|
||
/start@ApocalypseBot</code></pre>
|
||
<p>This is done automatically when commands are selected via the list of suggestions. Please remember that your bot needs to be able to process commands that are followed by its username.</p>
|
||
<h5><a class="anchor" name="global-commands" href="#global-commands"><i class="anchor-icon"></i></a>Global commands</h5>
|
||
<p>In order to make it easier for users to navigate the bot multiverse, we ask all developers to support a few basic commands. Telegram apps will have <strong>interface shortcuts</strong> for these commands.</p>
|
||
<ul>
|
||
<li><strong>/start</strong> - begins interaction with the user, e.g., by sending a greeting message. This command can also be used to pass additional parameters to the bot (see <a href="#deep-linking">Deep linking</a>)</li>
|
||
<li><strong>/help</strong> - returns a help message. It can be a short text about what your bot can do and a list of commands.</li>
|
||
<li><strong>/settings</strong> - (if applicable) returns the bot's settings for this user and suggests commands to edit these settings.</li>
|
||
</ul>
|
||
<p>Users will see a <strong>Start</strong> button when they first open a conversation with your bot. <strong>Help</strong> and <strong>Settings</strong> links will be available in the menu on the bot's profile page.</p>
|
||
<center><div>
|
||
<a href="/file/811140979/2/yD8AphHbahk/7662d14f4e0442ae3a" target="_blank"><img src="/file/811140979/2/yD8AphHbahk/7662d14f4e0442ae3a" title="An empty conversation with a bot" style="width: 250px; padding: 10px 5px" /></a>
|
||
|
||
<a href="/file/811140479/2/1c2zUWhR7sA/98889b2a45f8e42a35" target="_blank"><img src="/file/811140479/2/1c2zUWhR7sA/98889b2a45f8e42a35" title="A bot's profile page, featuring 'Help' and 'Settings' buttons" style="width: 250px; padding: 10px 5px" /></a>
|
||
|
||
</div></center>
|
||
|
||
<h4><a class="anchor" name="formatting-bold-italic-fixed-width-text-and-inline-links" href="#formatting-bold-italic-fixed-width-text-and-inline-links"><i class="anchor-icon"></i></a>Formatting: bold, italic, fixed-width text and inline links</h4>
|
||
<p>You can use bold, italic or fixed-width text, as well as inline links in your bots' messages. Telegram clients will render them accordingly. </p>
|
||
<blockquote>
|
||
<p><a href="bots/api#formatting-options">Read more in the Bot API manual »</a></p>
|
||
</blockquote>
|
||
<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 in order to augment communication between human users, e.g. by providing news, notifications from external services or additional search functionality. This is especially true for work-related groups. Now, when you share a group with a bot, you tend to ask yourself “How can I be sure that the little rascal isn't selling my chat history to my competitors?” The answer is — <strong>privacy mode</strong>.</p>
|
||
<p>A bot running in privacy mode will not receive all messages that people send to the group. Instead, it will only receive:</p>
|
||
<ul>
|
||
<li>Messages that start with a slash '/' (see <a href="#commands">Commands</a> above)</li>
|
||
<li>Replies to the bot's own messages</li>
|
||
<li>Service messages (people added or removed from the group, etc.)</li>
|
||
<li>Messages from channels where it's a member</li>
|
||
</ul>
|
||
<p>On one hand, this helps some of us sleep better at night (in our tinfoil nightcaps), on the other — it allows the bot developer to save a lot of resources, since they won't need to process tens of thousands irrelevant messages each day.</p>
|
||
<p>Privacy mode is enabled by default for all bots, except bots that were added to the group as <strong>admins</strong> (bot admins always receive all messages). It can be disabled, so that the bot receives all messages like an ordinary user (the bot will need to be <strong>re-added</strong> to the group for this change to take effect). We only recommend doing this in cases where it is absolutely necessary for your bot to work — users can always see a bot's current privacy setting in the group members list. In most cases, using the <a href="/bots/api#forcereply">force reply</a> option for the bot's messages should be more than enough. </p>
|
||
<p><a href="/bots/faq#what-messages-will-my-bot-get">So what messages exactly will my bot get? »</a></p>
|
||
<h4><a class="anchor" name="deep-linking" href="#deep-linking"><i class="anchor-icon"></i></a>Deep linking</h4>
|
||
<p>Telegram bots have a <a href="https://en.wikipedia.org/wiki/Deep_linking">deep linking</a> mechanism, that allows for passing additional parameters to the bot on startup. It could be a command that launches the bot — or an authentication token to connect the user's Telegram account to their account on some external service.</p>
|
||
<p>Each bot has a link that opens a conversation with it in Telegram — <code>https://t.me/<bot username></code>. You can add the parameters <strong>start</strong> or <strong>startgroup</strong> to this link, with values up to 64 characters long. For example:</p>
|
||
<pre><code>https://t.me/triviabot?startgroup=test</code></pre>
|
||
<p><code>A-Z</code>, <code>a-z</code>, <code>0-9</code>, <code>_</code> and <code>-</code> are allowed. We recommend using <a href="https://en.wikipedia.org/wiki/Base64#The_URL_applications">base64url</a> to encode parameters with binary and other types of content.</p>
|
||
<p>Following a link with the <strong>start</strong> parameter will open a one-on-one conversation with the bot, showing a START button in the place of the input field. If the <strong>startgroup</strong> parameter is used, the user is prompted to select a group to add the bot to. As soon as a user confirms the action (presses the START button in their app or selects a group to add the bot to), your bot will receive a message from that user in this format:</p>
|
||
<pre><code>/start PAYLOAD</code></pre>
|
||
<p><code>PAYLOAD</code> stands for the value of the <strong>start</strong> or <strong>startgroup</strong> parameter that was passed in the link.</p>
|
||
<h5><a class="anchor" name="deep-linking-example" href="#deep-linking-example"><i class="anchor-icon"></i></a>Deep linking Example</h5>
|
||
<p>Suppose the website example.com would like to send notifications to its users via a Telegram bot. Here's what they could do to enable notifications for a user with the ID <code>123</code>.</p>
|
||
<ol>
|
||
<li><a href="#6-botfather">Create a bot</a> with a suitable username, e.g. @ExampleComBot</li>
|
||
<li>Set up a <a href="/bots/api#setwebhook">webhook</a> for incoming messages</li>
|
||
<li>Generate a random string of a sufficient length, e.g. <code>$memcache_key = "vCH1vGWJxfSeofSAs0K5PA"</code></li>
|
||
<li>Put the value <code>123</code> with the key <code>$memcache_key</code> into Memcache for 3600 seconds (one hour) </li>
|
||
<li>Show our user the button <code>https://t.me/ExampleComBot?start=vCH1vGWJxfSeofSAs0K5PA</code></li>
|
||
<li>Configure the webhook processor to query Memcached with the parameter that is passed in incoming messages beginning with <code>/start</code>. If the key exists, record the chat_id passed to the webhook as <strong>telegram_chat_id</strong> for the user <code>123</code>. Remove the key from Memcache.</li>
|
||
<li>Now when we want to send a notification to the user <code>123</code>, check if they have the field <strong>telegram_chat_id</strong>. If yes, use the <a href="/bots/api#sendmessage">sendMessage</a> method in the <a href="/bots/api">Bot API</a> to send them a message in Telegram.</li>
|
||
</ol>
|
||
<h4><a class="anchor" name="location-and-number" href="#location-and-number"><i class="anchor-icon"></i></a>Location and Number</h4>
|
||
<p>Some bots need extra data from the user to work properly. For example, knowing the user's location helps provide more relevant geo-specific results. The user's phone number can be very useful for integrations with other services, like banks, etc.</p>
|
||
<p>Bots can ask a user for their <strong>location</strong> and <strong>phone number</strong> using special buttons. Note that both phone number and location request buttons will only work in private chats.</p>
|
||
<div><center>
|
||
<a href="/file/811140587/2/jaowDLZg2l0/5ba3f7d7fd5c6c28dc" target="_blank"><img src="/file/811140587/2/jaowDLZg2l0/5ba3f7d7fd5c6c28dc" title="Phone number and location sharing buttons" style="width: 295px; padding: 10px 20px;" /></a></center>
|
||
|
||
</div>
|
||
|
||
<p>When these buttons are pressed, Telegram clients will display a confirmation alert that tells the user what's about to happen.</p>
|
||
<blockquote>
|
||
<p><a href="/bots/api#keyboardbutton">Manual: Number and location buttons »</a></p>
|
||
</blockquote>
|
||
<hr>
|
||
<h3><a class="anchor" name="6-botfather" href="#6-botfather"><i class="anchor-icon"></i></a>6. BotFather</h3>
|
||
<blockquote>
|
||
<p>Jump to top to learn everything about <a href="#">Telegram bots »</a></p>
|
||
</blockquote>
|
||
<p><a href="https://t.me/botfather">BotFather</a> is the one bot to rule them all. It will help you create new bots and change settings for existing ones.</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 <strong>/newbot</strong> command to create a new bot. The BotFather will ask you for a name and username, then generate an authentication token for your new bot. </p>
|
||
<p>The <strong>name</strong> of your bot is displayed in contact details and elsewhere.</p>
|
||
<p>The <strong>Username</strong> is a short name, to be used in mentions and t.me links. Usernames are 5-32 characters long and are case insensitive, but may only include Latin characters, numbers, and underscores. Your bot's username <strong>must</strong> end in 'bot', e.g. 'tetris_bot' or 'TetrisBot'.</p>
|
||
<p>The <strong>token</strong> is a string along the lines of <code>110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code> that is required to authorize the bot and send requests to the <a href="/bots/api">Bot API</a>. Keep your token secure and store it safely, it can be used by anyone to control your bot.</p>
|
||
<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 compromised or you lost it for some reason, use the <strong>/token</strong> command to generate a new one.</p>
|
||
<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><strong>/mybots</strong> — returns a list of your bots with handy controls to edit their settings</li>
|
||
<li><strong>/mygames</strong> — does the same for your games</li>
|
||
</ul>
|
||
<p><strong>Edit bots</strong></p>
|
||
<ul>
|
||
<li><strong>/setname</strong> – change your bot's name.</li>
|
||
<li><strong>/setdescription</strong> — change the bot's <strong>description</strong>, a short text of up to 512 characters, describing your bot. Users will see this text at the beginning of the conversation with the bot, titled 'What can this bot do?'.</li>
|
||
<li><strong>/setabouttext</strong> — change the bot's <strong>about info</strong>, an even shorter text of up to 120 characters. Users will see this text on the bot's profile page. When they share your bot with someone, this text is sent together with the link.</li>
|
||
<li><strong>/setuserpic</strong> — change the bot's profile pictures. It's always nice to put a face to a name.</li>
|
||
<li><strong>/setcommands</strong> — change the list of commands supported by your bot. Users will see these commands as suggestions when they type <code>/</code> in the chat with your bot. Each command has a name (must start with a slash ‘/’, alphanumeric plus underscores, no more than 32 characters, case-insensitive), parameters, and a text description. Users will see the list of commands whenever they type '/' in a conversation with your bot.</li>
|
||
<li><strong>/deletebot</strong> — delete your bot and free its username.</li>
|
||
</ul>
|
||
<p><strong>Edit settings</strong></p>
|
||
<ul>
|
||
<li><strong>/setinline</strong> — toggle <a href="/bots/inline">inline mode</a> for your bot.</li>
|
||
<li><strong>/setinlinegeo</strong> - request location data to provide <a href="/bots/inline#location-based-results">location-based inline results</a>.</li>
|
||
<li><strong>/setjoingroups</strong> — toggle whether your bot can be added to groups or not. Any bot must be able to process private messages, but if your bot was not designed to work in groups, you can disable this.</li>
|
||
<li><strong>/setprivacy</strong> — set which messages your bot will receive when added to a group. With privacy mode disabled, the bot will receive all messages. We recommend leaving <a href="#privacy-mode">privacy mode</a> enabled. You will need to re-add the bot to existing groups for this change to take effect.</li>
|
||
</ul>
|
||
<p><strong>Manage games</strong></p>
|
||
<ul>
|
||
<li><strong>/newgame</strong> — create a new <a href="/bots/games">game</a>.</li>
|
||
<li><strong>/listgames</strong> — get a list of your games.</li>
|
||
<li><strong>/editgame</strong> — edit a game.</li>
|
||
<li><strong>/deletegame</strong> — delete an existing game.</li>
|
||
</ul>
|
||
<blockquote>
|
||
<p>Please note, that it may take <strong>a few minutes</strong> for changes to take effect.</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 stay competitive in this environment, your bot also needs to be responsive. In order to help developers keep their bots in shape, Botfather will send status alerts if it sees something is wrong.</p>
|
||
<p>We will be checking the number of replies and the request/response conversion rate for popular bots (~300 requests per minute: but don't write this down as the value may change in the future). If we get abnormally low readings, you will receive a notification from Botfather.</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, you will only get one alert per bot per hour. 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'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't fix your bot at the moment. This will disable all alerts for the bot in question for the specified period of time. We do not recommend using this option since your users may migrate to a more stable bot. You can unmute alerts in your bot's settings via Botfather.</li>
|
||
</ul>
|
||
<h5><a class="anchor" name="monitored-issues" href="#monitored-issues"><i class="anchor-icon"></i></a>Monitored issues</h5>
|
||
<p>We will currently notify you about the following issues:</p>
|
||
<p><strong>1.</strong></p>
|
||
<pre><code>Too few **private messages** are sent compared to previous weeks: **{value}**</code></pre>
|
||
<p>Your bot is sending much fewer messages than it did in the previous weeks. This is useful for newsletter-style bots that send out messages without prompts from the users. The larger the value, the more significant the difference. </p>
|
||
<p><strong>2.</strong></p>
|
||
<pre><code>Too few replies to incoming **private messages**. Conversion rate: **{value}**</code></pre>
|
||
<p>Your bot is not replying to all messages that are being sent to it (the request/response conversion rate for your bot was too low for at least two of the last three 5-minute periods). To provide a good user experience, please respond to all messages that are sent to your bot. Respond to <em>message</em> <a href="https://core.telegram.org/bots/api#update">updates</a> by calling <em>send…</em> methods (e.g. <a href="https://core.telegram.org/bots/api#sendmessage">sendMessage</a>).</p>
|
||
<p><strong>3.</strong></p>
|
||
<pre><code>Too few answers to **inline queries**. Conversion rate: **{value}**</code></pre>
|
||
<p>Your bot is not replying to all inline queries that are being sent to it, calculated in the same way as above. Respond to <em>inline_query</em> <a href="https://core.telegram.org/bots/api#update">updates</a> by calling <a href="/bots/api#answerinlinequery">answerInlineQuery</a>.</p>
|
||
<p><strong>4.</strong></p>
|
||
<pre><code>Too few answers to **callback queries**. Conversion rate: **{value}**
|
||
Too few answers to **callback game queries**. Conversion rate: **{value}**</code></pre>
|
||
<p>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 <em>callback_query</em> <a href="https://core.telegram.org/bots/api#update">updates</a> by calling <a href="/bots/api#answercallbackquery">answerCallbackQuery</a>.</p>
|
||
<blockquote>
|
||
<p>Please note that the status alerts feature is still being tested and will be improved in the future.</p>
|
||
</blockquote>
|
||
<hr>
|
||
<p>That's it for the introduction. You are now definitely ready to proceed to the <a href="/bots/api"><strong>BOT API MANUAL</strong></a>.</p>
|
||
<p>If you've got any questions, please check out our <a href="/bots/faq"><strong>Bot FAQ »</strong></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/blog">Blog</a></li>
|
||
<li><a href="//telegram.org/jobs">Jobs</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/dl/android">Android</a></li>
|
||
<li><a href="//telegram.org/dl/wp">Windows Phone</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?45"></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>
|
||
|