<metaproperty="description"content="Telegram clients must handle special tg:// and t.me deep links encountered in messages, link entities and in other apps by registering OS handlers.">
<metaproperty="og:title"content="Deep links">
<metaproperty="og:image"content="">
<metaproperty="og:description"content="Telegram clients must handle special tg:// and t.me deep links encountered in messages, link entities and in other apps by registering OS handlers.">
<p>Telegram clients must handle special <code>tg://</code> and <code>t.me</code> deep links encountered in messages, link entities and in other apps by registering OS handlers. </p>
<p>Links are generally available in two flavors: <code>t.me</code> HTTPS links and <code>tg:</code> URIs. </p>
<p><code>t.me</code> link syntax examples: </p>
<ul>
<li><code>t.me/path?query</code></li>
<li><code>http://t.me/path?query</code></li>
<li><code>https://t.me/path?query</code></li>
</ul>
<p>Where <code>t.me</code> can also be <code>telegram.me</code>, <code>telegram.dog</code>, and the domain specified in the <code>me_url_prefix</code> field of the global <ahref="/constructor/config">configuration</a>, obtainable using <ahref="/method/help.getConfig">help.getConfig</a>.</p>
<p>Also note that whenever a <code><username>.t.me</code> link is encountered and <code><username></code> is not equal to <code>www</code>, is not a single letter and is a valid username, it should be treated exactly as a <code>t.me/<username>/</code> link (generate a <code>t.me/<username>/</code> link and append the rest of the path (if present) and the query string (if present)). </p>
<p>Used to link to user profiles, generated using <ahref="/method/contacts.exportContactToken">contacts.exportContactToken</a>.<br>
These links can be generated even for profiles that don't have a username, and they have an expiration date, specified by the <code>expires</code> field of the <ahref="/constructor/exportedContactToken">exportedContactToken</a> constructor returned by <ahref="/method/contacts.exportContactToken">contacts.exportContactToken</a>. </p>
<td>Phone number to resolve using <ahref="/method/contacts.resolvePhone">contacts.resolvePhone</a></td>
</tr>
</tbody>
</table>
<p>Note that <ahref="#message-links">chat invite links</a> have the same syntax, but <code><phone_number></code> won't be a valid phone number. </p>
<p>Used to invite users to private groups and channels, see <ahref="/api/invites#invite-links">here for more info on how to generate such links »</a>. </p>
<p>Used to invite users to private groups and channels, see <ahref="/api/folders#shared-folders">here for more info on how to generate such links »</a>. </p>
<td>For <ahref="/api/threads">message threads</a>, contains the thread ID.</td>
</tr>
<tr>
<td><code>comment</code></td>
<tdstyle="text-align: center;">Optional</td>
<td>For <ahref="/api/discussion">channel comments</a>, <code>username</code> will contain the channel username, <code>id</code> will contain the message ID of the channel message that started the comment section and this field will contain the message ID of the comment in the discussion group.</td>
</tr>
<tr>
<td><code>media_timestamp</code></td>
<tdstyle="text-align: center;">Optional</td>
<td>Timestamp at which to start playing the media file present in the body or in the webpage preview of the message, in the following formats: <br>- Seconds: <code>123</code>, regex <code>^(\d+)$</code><br>- Minutes and seconds: <code>10:23</code>, example regex <code>^(\d+):(\d{1,2})$</code><br>- Hours, minutes and seconds: <code>1h23m10s</code>, example regex <code>^(?:(\d+)h)?(?:(\d{1,2})m)?(?:(\d{1,2})s)$</code></td>
<p>Note that since a <ahref="/api/forum#forum-topics">forum topic</a> ID is actually the ID of the service message that created the topic, whenever the client resolves a <ahref="#message-links">message link</a> that points to a <ahref="/constructor/messageActionTopicCreate">messageActionTopicCreate</a> service message, it should open the topic, instead.<br>
Also, if the message ID is <code>1</code> and the linked-to supergroup is a forum, the "General" topic should be opened instead of the first message of the supergroup. </p>
<p>Used to link to a specific <ahref="/api/forum#forum-topics">forum topic</a>. </p>
<p>The syntax is exactly the same as for <ahref="#message-links">message links</a>, because the topic ID is actually the ID of the service message that created the topic, so whenever the client resolves a <ahref="#message-links">message link</a> that points to a <ahref="/constructor/messageActionTopicCreate">messageActionTopicCreate</a> service message, it should open the topic, instead. </p>
<p>Also, if the message ID is <code>1</code> and the linked-to supergroup is a forum, the "General" topic should be opened instead of the first message of the supergroup. </p>
<p>Used to join video/voice chats in groups, and livestreams in channels.<br>
Such links are generated using <ahref="/method/phone.exportGroupCallInvite">phone.exportGroupCallInvite</a>.<br>
Note that <code>voicechat</code> links are deprecated, the API will always export <code>videochat</code> links for video and voice chats in groups, clients should support parsing the old link format only for backwards compatibility. </p>
<td>Invite hash exported if the <code>can_self_unmute</code> flag is set when calling <ahref="/method/phone.exportGroupCallInvite">phone.exportGroupCallInvite</a>: should be passed to <ahref="/method/phone.joinGroupCall">phone.joinGroupCall</a>, allows the user to speak in livestreams or muted group chats.</td>
<p>Used to import stickersets or <ahref="/api/custom-emoji">custom emoji</a> stickersets as described <ahref="/api/stickers#installing-stickersets">here »</a>.</p>
<p>Used to share and install chat backgrounds (wallpapers): see <ahref="/api/wallpapers">here for more info on the various wallpaper and fill types »</a>. </p>
<td>Wallpaper slug used to obtain the image file using <ahref="/method/account.getWallPaper">account.getWallPaper</a>.</td>
</tr>
<tr>
<td><code>mode</code></td>
<tdstyle="text-align: center;">Optional</td>
<td>A combination of <code>blur</code> and <code>motion</code> (joined by <code>+</code>) to enable blurring and/or parallax motion as specified in the <ahref="/api/wallpapers#image-wallpapers">docs »</a>.</td>
</tr>
</tbody>
</table>
<h4><aclass="anchor"href="#solid-fill-wallpapers"id="solid-fill-wallpapers"name="solid-fill-wallpapers"><iclass="anchor-icon"></i></a>Solid fill wallpapers</h4>
<p>Used for <ahref="/api/wallpapers#fill-wallpapers">fill wallpapers »</a> with a <ahref="/api/wallpapers#solid-fill">solid fill »</a>. </p>
<h4><aclass="anchor"href="#gradient-fill-wallpapers"id="gradient-fill-wallpapers"name="gradient-fill-wallpapers"><iclass="anchor-icon"></i></a>Gradient fill wallpapers</h4>
<p>Used for <ahref="/api/wallpapers#fill-wallpapers">fill wallpapers »</a> with a <ahref="/api/wallpapers#gradient-fill">gradient fill »</a>. </p>
<td>Clockwise rotation angle of the gradient, in degrees; 0-359. Must be always divisible by 45, default to 0 if not set.</td>
</tr>
</tbody>
</table>
<h4><aclass="anchor"href="#freeform-gradient-fill-wallpapers"id="freeform-gradient-fill-wallpapers"name="freeform-gradient-fill-wallpapers"><iclass="anchor-icon"></i></a>Freeform gradient fill wallpapers</h4>
<p>Used for <ahref="/api/wallpapers#fill-wallpapers">fill wallpapers »</a> with a <ahref="/api/wallpapers#freeform-gradient-fill">freeform gradient fill »</a>. </p>
<td>Wallpaper slug used to obtain the pattern file using <ahref="/method/account.getWallPaper">account.getWallPaper</a>.</td>
</tr>
<tr>
<td><code>intensity</code></td>
<tdstyle="text-align: center;">Required</td>
<td>A value ranging from -100 to 100, used to combine the pattern with the fill <ahref="/api/wallpapers#pattern-wallpapers">as specified in the docs</a>.</td>
</tr>
<tr>
<td><code>bg_color</code></td>
<tdstyle="text-align: center;">Required</td>
<td>Fill color in hex RGB format.</td>
</tr>
<tr>
<td><code>mode</code></td>
<tdstyle="text-align: center;">Optional</td>
<td><code>motion</code> to enable parallax motion as specified in the <ahref="/api/wallpapers#image-wallpapers">docs</a>.</td>
<p>Used for <ahref="/api/wallpapers#pattern-wallpapers">pattern wallpapers »</a> with a <ahref="/api/wallpapers#gradient-fill">gradient fill »</a>. </p>
<td>Wallpaper slug used to obtain the pattern file using <ahref="/method/account.getWallPaper">account.getWallPaper</a>.</td>
</tr>
<tr>
<td><code>intensity</code></td>
<tdstyle="text-align: center;">Required</td>
<td>A value ranging from -100 to 100, used to combine the pattern with the fill <ahref="/api/wallpapers#pattern-wallpapers">as specified in the docs</a>.</td>
</tr>
<tr>
<td><code>top_color</code></td>
<tdstyle="text-align: center;">Required</td>
<td>Top gradient color in hex RGB format.</td>
</tr>
<tr>
<td><code>bottom_color</code></td>
<tdstyle="text-align: center;">Required</td>
<td>Bottom gradient color in hex RGB format.</td>
</tr>
<tr>
<td><code>rotation</code></td>
<tdstyle="text-align: center;">Optional</td>
<td>Clockwise rotation angle of the gradient, in degrees; 0-359. Must be always divisible by 45, default to 0 if not set.</td>
</tr>
<tr>
<td><code>mode</code></td>
<tdstyle="text-align: center;">Optional</td>
<td><code>motion</code> to enable parallax motion as specified in the <ahref="/api/wallpapers#image-wallpapers">docs</a>.</td>
<p>Used for <ahref="/api/wallpapers#pattern-wallpapers">pattern wallpapers »</a> with a <ahref="/api/wallpapers#freeform-gradient-fill">freeform gradient fill »</a>. </p>
<td>Wallpaper slug used to obtain the pattern file using <ahref="/method/account.getWallPaper">account.getWallPaper</a>.</td>
</tr>
<tr>
<td><code>intensity</code></td>
<tdstyle="text-align: center;">Required</td>
<td>A value ranging from -100 to 100, used to combine the pattern with the fill <ahref="/api/wallpapers#pattern-wallpapers">as specified in the docs</a>.</td>
</tr>
<tr>
<td><code>hex_color1</code></td>
<tdstyle="text-align: center;">Required</td>
<td>First gradient color in hex RGB format.</td>
</tr>
<tr>
<td><code>hex_color2</code></td>
<tdstyle="text-align: center;">Required</td>
<td>Second gradient color in hex RGB format.</td>
</tr>
<tr>
<td><code>hex_color3</code></td>
<tdstyle="text-align: center;">Required</td>
<td>Third gradient color in hex RGB format.</td>
</tr>
<tr>
<td><code>hex_color4</code></td>
<tdstyle="text-align: center;">Optional</td>
<td>Fourth gradient color in hex RGB format.</td>
</tr>
<tr>
<td><code>mode</code></td>
<tdstyle="text-align: center;">Optional</td>
<td><code>motion</code> to enable parallax motion as specified in the <ahref="/api/wallpapers#image-wallpapers">docs</a>.</td>
<td>Start parameter, up to 64 <ahref="https://en.wikipedia.org/wiki/Base64#The_URL_applications">base64url</a> characters: if provided and the <code>bot_username</code> is indeed a bot, the text input bar should be replaced with a <code>Start</code> button (even if the user has already started the bot) that should invoke <ahref="/method/messages.startBot">messages.startBot</a> with the appropriate <code>parameter</code> once clicked.</td>
First of all, check that the <code><bot_username></code> indeed links to a bot.<br>
Then, for group links:</p>
<ul>
<li>If the <code>admin</code> parameter is not provided:<ul>
<li>Bring up a dialog selection of groups where the user can add members</li>
<li>Add the bot to the group</li>
<li>If a <code>parameter</code> is provided, invoke <ahref="/method/messages.startBot">messages.startBot</a> with the appropriate <code>parameter</code></li>
</ul>
</li>
<li>If the <code>admin</code> parameter is provided:<ul>
<li>Bring up a dialog selection of groups where the user can add/edit admins</li>
<li>If the bot is already an admin of the group, combine existing admin rights with the admin rights in <code>admin</code></li>
<li>Add the bot as admin/modify admin permissions to the new rights</li>
<li>If a <code>parameter</code> is provided, invoke <ahref="/method/messages.startBot">messages.startBot</a> with the appropriate <code>parameter</code></li>
</ul>
</li>
</ul>
<p>For channel links:</p>
<ul>
<li>Bring up a dialog selection of channels where the user can add/edit admins</li>
<li>If the bot is already an admin of the channel, combine existing admin rights with the admin rights in <code>admin</code></li>
<li>Add the bot as admin/modify admin permissions to the new rights</li>
<tdstyle="text-align: center;">Optional for group links, absent in channel links</td>
<td>Start parameter, only for group links, up to 64 <ahref="https://en.wikipedia.org/wiki/Base64#The_URL_applications">base64url</a> characters: if provided and the <code>bot_username</code> is indeed a bot, <ahref="/method/messages.startBot">messages.startBot</a> with the appropriate <code>parameter</code> should be invoked after adding the bot to the group.</td>
</tr>
<tr>
<td><code>admin</code></td>
<tdstyle="text-align: center;">Optional for group links, required for channel links</td>
<p>Used to share <ahref="/api/bots/games">games</a>. </p>
<p>These links should be handled as follows: </p>
<ul>
<li>Check if <code>bot_username</code> is indeed a bot username, if so then</li>
<li>Bring up a dialog selection prompt</li>
<li>Send the game to the selected dialog using an <ahref="/constructor/inputMediaGame">inputMediaGame</a> with an <ahref="/constructor/inputGameShortName">inputGameShortName</a> as specified in the <ahref="/api/bots/games#sending-a-game">game docs</a>. </li>
<h3><aclass="anchor"href="#named-bot-web-app-links"id="named-bot-web-app-links"name="named-bot-web-app-links"><iclass="anchor-icon"></i></a>Named bot web app links</h3>
<p>Used to share <ahref="/api/bots/webapps#named-bot-web-apps">named bot web apps</a>. </p>
<p>These links are different from <ahref="#bot-attachment-menu-links">bot attachment menu deep links</a>, because they don't require the user to install an attachment menu, and a single bot can offer multiple named web apps, distinguished by their <code>short_name</code>. </p>
<p>These links should be handled as specified in the <ahref="/api/bots/webapps#named-bot-web-apps">named bot web app documentation »</a>. </p>
<td>Username of the bot that owns the <ahref="/api/bots/games">game</a></td>
</tr>
<tr>
<td><code>appname</code></td>
<tdstyle="text-align: center;">Required</td>
<td>Web app short name, to pass to <ahref="/constructor/inputBotAppShortName">inputBotAppShortName</a>.<code>short_name</code> when invoking <ahref="/method/messages.getBotApp">messages.getBotApp</a></td>
</tr>
<tr>
<td><code>startapp</code></td>
<tdstyle="text-align: center;">Optional</td>
<td><code>start_param</code> to pass to <ahref="/method/messages.requestAppWebView">messages.requestAppWebView</a></td>
<p>Used to bring the user to the app settings. </p>
<p><code>tg:</code> syntax:</p>
<pre><code>tg://settings</code></pre>
<p>No parameters.</p>
<h4><aclass="anchor"href="#change-phone-number-link"id="change-phone-number-link"name="change-phone-number-link"><iclass="anchor-icon"></i></a>Change phone number link</h4>
<p>Used to bring the user to the phone number modification page, invoking <ahref="/method/account.sendChangePhoneCode">account.sendChangePhoneCode</a> and <ahref="/method/account.changePhone">account.changePhone</a>.</p>
<p>Used to bring the user to the language settings. </p>
<p><code>tg:</code> syntax:</p>
<pre><code>tg://settings/language</code></pre>
<p>No parameters.</p>
<h4><aclass="anchor"href="#privacy-and-security-settings-link"id="privacy-and-security-settings-link"name="privacy-and-security-settings-link"><iclass="anchor-icon"></i></a>Privacy and security settings link</h4>
<p>Used to bring the user to the privacy and security settings. </p>
<p>Used to initiate <ahref="/api/payments">payment of an invoice »</a>, generated using <ahref="/constructor/payments.exportedInvoice">payments.exportedInvoice</a>. </p>
<p>Different from <ahref="#login-code-link">login code links</a>.<br>
These links are used to confirm ownership of the phone number, to prevent account deletion: see <ahref="/api/account-deletion">the account deletion docs for more info on how to handle them »</a>.</p>
<h3><aclass="anchor"href="#bot-attachment-menu-links"id="bot-attachment-menu-links"name="bot-attachment-menu-links"><iclass="anchor-icon"></i></a>Bot attachment menu links</h3>
<p>Used to install and optionally open a <ahref="/api/bots/attach">bot attachment menu »</a> in a certain chat.<br>
For all link types, clients should:</p>
<ul>
<li>Check that the associated bot username has an associated <ahref="/api/bots/attach">attachment menu</a> as specified <ahref="/api/bots/attach">here »</a>.</li>
<li>If not installed, ask the user to <ahref="/api/bots/attach">install the attachment menu »</a>.</li>
<li>Check that the attachment menu can be opened in the chosen chat type by checking the <ahref="/constructor/attachMenuBot">attachMenuBot</a>.<code>peer_types</code> field.<ul>
<li>If the chosen chat is supported, open the attachment menu <ahref="/api/bots/webapps#normal-web-apps">web app »</a></li>
<li>Otherwise:<ul>
<li>If the user has just installed the attachment menu @ step 2, notify the user that the attachment menu was installed successfully.</li>
<li>Otherwise, notify the user that the attachment menu webapp can't be opened in the specified chat.</li>
</ul>
</li>
</ul>
</li>
</ul>
<h4><aclass="anchor"href="#open-in-current-chat"id="open-in-current-chat"name="open-in-current-chat"><iclass="anchor-icon"></i></a>Open in current chat</h4>
<p>Installs and opens an attachment menu web app in the currently open chat. </p>
<td>Username of the bot that owns the <ahref="/api/bots/attach">attachment menu</a></td>
</tr>
<tr>
<td><code>start_parameter</code></td>
<tdstyle="text-align: center;">Optional</td>
<td>If provided, should be passed to <ahref="/method/messages.requestWebView">messages.requestWebView</a>.<code>start_param</code></td>
</tr>
</tbody>
</table>
<h4><aclass="anchor"href="#open-in-specific-chat"id="open-in-specific-chat"name="open-in-specific-chat"><iclass="anchor-icon"></i></a>Open in specific chat</h4>
<p>Installs and opens an attachment menu web app in a specific chat. </p>
<td>Username of the bot that owns the <ahref="/api/bots/attach">attachment menu</a></td>
</tr>
<tr>
<td><code>start_parameter</code></td>
<tdstyle="text-align: center;">Optional</td>
<td>If provided, should be passed to <ahref="/method/messages.requestWebView">messages.requestWebView</a>.<code>start_param</code></td>
</tr>
<tr>
<td><code>choose</code></td>
<tdstyle="text-align: center;">Optional</td>
<td>A combination of <code>users</code>, <code>bots</code>, <code>groups</code>, <code>channels</code> separated by <code>+</code>: indicates the dialog types to show in the dialog selection popup: must be intersected with the dialog types contained in the <ahref="/constructor/attachMenuBot">attachMenuBot</a>.<code>peer_types</code> field before use.</td>
<p>ID links are merely an abstraction offered by the <ahref="/bots/api">bot API</a> to simplify construction of <ahref="/constructor/inputMessageEntityMentionName">inputMessageEntityMentionName</a> and <ahref="/constructor/inputKeyboardButtonUserProfile">inputKeyboardButtonUserProfile</a> constructors, and should be ignored by normal clients. </p>
<p>Emoji links are merely an abstraction offered by the <ahref="/bots/api">bot API</a> to simplify construction of <ahref="/constructor/messageEntityCustomEmoji">messageEntityCustomEmoji</a> constructors, and should be ignored by normal clients. </p>
<p>If a client encounters a <code>tg:</code> link type not listed on this page, <ahref="/method/help.getDeepLinkInfo">help.getDeepLinkInfo</a> should be invoked with just the <code>path</code> component of the link. </p>
<p>The method may return formatted text, containing for example: </p>
<ul>
<li>A description of what the link does or,</li>
<li>An explanation of why a certain link isn't supported by the app;</li>
</ul>
<p>And/or an invitation to upgrade to the latest version of the client app to be able to use the link: in this case, the result <code>update_app</code> flag will also be set, and the app should directly link to a store or attempt updating to the latest version. </p>
<p>Example links that can be used for testing: </p>
<p>Note that this method should not be called for unrecognized <code>t.me</code> links, the usual HTTP link handling logic should be used, instead.</p></div>
</div>
</div>
</div>
<divclass="footer_wrap">
<divclass="footer_columns_wrap footer_desktop">
<divclass="footer_column footer_column_telegram">
<h5>Telegram</h5>
<divclass="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
