Deep links

Telegram clients must handle special tg:// and t.me deep links encountered in messages, link entities and in other apps by registering OS handlers.

Links are generally available in two flavors: t.me HTTPS links and tg: URIs.

t.me link syntax examples:

• t.me/path?query
• http://t.me/path?query
• https://t.me/path?query

Where t.me can also be telegram.me, telegram.dog, and the domain specified in the me_url_prefix field of the global configuration, obtainable using help.getConfig.

tg: link syntax examples:

• tg:path?query
• tg://path?query

The #fragment part is always ignored when parsing Telegram deep links.

Also note that whenever a <username>.t.me link is encountered and <username>:

• Is not equal to:
  • www
  • addemoji
  • addlist
  • addstickers
  • addtheme
  • auth
  • boost
  • confirmphone
  • contact
  • giftcode
  • invoice
  • joinchat
  • login
  • m
  • proxy
  • setlanguage
  • share
  • socks
  • web
  • a
  • k
  • z
• AND is not a single letter
• AND is a valid username

...it should be treated exactly as a t.me/<username>/ link (generate a t.me/<username>/ link and append the rest of the path (if present) and the query string (if present)).

Everywhere where link parameters contain a user, chat, channel or supergroup ID, it will be in MTProto format, see here » for info on how to convert it to bot API format.

TON Sites

Used to open TON Sites using the in-app Telegram Browser.

Syntax:

tonsite://somesite.domain/path?query#hash

Also available without the tonsite:// scheme for .ton domains:

getting-started.ton/path?query#hash

In both cases, the #hash part of the URL should not be ignored.

To open such URLs:

• Replace the tonsite scheme with https
• Transform the host part of the URL thusly:
  • Replace all . characters with -d
  • Replace - characters with -h (except for the -s generated by the first replace)
  • Append a .
  • Append the domain name specified in the ton_proxy_address client configuration parameter »

The resulting URL should only be opened using the in-app Telegram Browser (i.e. no option should be given to open such links using third party browsers).

Public username links

Used to link to public users, groups and channels, see here for more info on how to handle them ».

t.me syntax:

t.me/<username>?text=<draft_text>&profile

tg: syntax:

tg://resolve?domain=<username>&text=<draft_text>&profile

Parameters:

Name	Optional	Description
username	Required	Username to check or import »
draft_text	Optional	UTF-8 text to pre-enter into the text input bar, if the user can write in the chat. Before insertion: - Validate that the text is valid UTF-8. - If the text starts with a @, prepend a whitespace to it (to avoid triggering an inline query). - Trim the text to message_length_max UTF-8 codepoints.
profile	Optional	If set, clicking on this link should open the destination peer's profile page, not the chat view.

Note that message links have the same syntax, with extra parameters.

Temporary profile links

Used to link to user profiles, generated using contacts.exportContactToken.
These links can be generated even for profiles that don't have a username, and they have an expiration date, specified by the expires field of the exportedContactToken constructor returned by contacts.exportContactToken.

t.me syntax:

t.me/contact/<token>

tg: syntax:

tg://contact?token=<token>

Parameters:

Name	Optional	Description
token	Required	Profile token to import using contacts.importContactToken, will return user information.

Phone number links

Used to link to public and private users by their phone number.

t.me syntax:

t.me/+<phone_number>?text=<draft_text>&profile

tg: syntax:

tg://resolve?phone=<phone_number>&text=<draft_text>&profile

Parameters:

Name	Optional	Description
phone_number	Required	Phone number to resolve using contacts.resolvePhone
draft_text	Optional	UTF-8 text to pre-enter into the text input bar, if the user can write in the chat. Before insertion: - Validate that the text is valid UTF-8. - If the text starts with a @, prepend a whitespace to it (to avoid triggering an inline query). - Trim the text to message_length_max UTF-8 codepoints.
profile	Optional	If set, clicking on this link should open the user's profile page, not the chat with them.

Note that chat invite links have the same syntax, but <phone_number> won't be a valid phone number.

Chat invite links

Used to invite users to private groups and channels, see here for more info on how to generate such links ».

t.me syntax:

t.me/+<hash>

t.me syntax (legacy):

t.me/joinchat/<hash>

tg: syntax:

tg://join?invite=<hash>

Parameters:

Name	Optional	Description
hash	Required	Invite hash to check or import »

Chat folder links

Used to invite users to private groups and channels, see here for more info on how to generate such links ».

t.me syntax:

t.me/addlist/<slug>

tg: syntax:

tg://addlist?slug=<slug>

Parameters:

Name	Optional	Description
slug	Required	Invite slug to check or import »

Message links

Used to link to specific messages in public or private groups and channels.

t.me syntax (public links):

t.me/<username>/<id>?single&thread=<thread_id>&comment=<comment>&t=<media_timestamp>
t.me/<username>/<thread_id>/<id>?single&comment=<comment>&t=<media_timestamp>

t.me syntax (private links):

t.me/c/<channel>/<id>?single&thread=<thread_id>&comment=<comment>&t=<media_timestamp>
t.me/c/<channel>/<thread_id>/<id>?single&comment=<comment>&t=<media_timestamp>

tg: syntax (public links):

tg://resolve?domain=<username>&post=<id>&single&thread=<thread_id>&comment=<comment>&t=<media_timestamp>

tg: syntax (private links):

tg://privatepost?channel=<channel>&post=<id>&single&thread=<thread_id>&comment=<comment>&t=<media_timestamp>

Parameters:

Name	Optional	Description
username	Required if public link	Dialog username.
channel	Required if private link	Channel or supergroup ID.
id	Required	Message ID.
single	Optional	For albums/grouped media, if set indicates that this is a link to a specific media in the album; otherwise, it is a link to the entire album.
thread_id	Optional	For message threads, contains the thread ID.
comment	Optional	For channel comments, username will contain the channel username, id 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.
media_timestamp	Optional	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: - Seconds: 123, regex ^(\d+)$ - Minutes and seconds: 10:23, example regex ^(\d+):(\d{1,2})$ - Hours, minutes and seconds: 1h23m10s, example regex ^(?:(\d+)h)?(?:(\d{1,2})m)?(?:(\d{1,2})s)$

Note that since a forum topic ID is actually the ID of the service message that created the topic, whenever the client resolves a message link that points to a messageActionTopicCreate service message, it should open the topic, instead.
Also, if the message ID is 1 and the linked-to supergroup is a forum, the "General" topic should be opened instead of the first message of the supergroup.

Forum topic links

Used to link to a specific forum topic.

The syntax is exactly the same as for message links, because the topic ID is actually the ID of the service message that created the topic, so whenever the client resolves a message link that points to a messageActionTopicCreate service message, it should open the topic, instead.

Also, if the message ID is 1 and the linked-to supergroup is a forum, the "General" topic should be opened instead of the first message of the supergroup.

Share links

Used to share a prepared message and URL into a chosen chat's text field.
These links should be handled as follows:

• Open a dialog selection prompt
• After selection: validate, trim and enter the URL at the beginning of the text field
• Append a newline to the text field
• Append and select the text, if present

t.me syntax:

t.me/share?url=<url>&text=<text>

tg: syntax:

tg://msg_url?url=<url>&text=<text>

Parameters:

Name	Optional	Description
url	Required	URL to share (urlencoded)
text	Optional	Message to share

Business chat links

Business chat deep links » allow business owners to share pre-made links to their Telegram Business account, optionally filling out the message input field with a pre-prepared message (with support for styled text entities »).

There is no additional limit on the prepared message length (because the message text is not present in the URL's query string, but rather it's fetched from the server using the link slug); each created business chat deep link also has a view counter.

See here » for more info on how to create, edit, resolve and get view information about business chat links.

These links should be handled as follows:

• Invoke account.resolveBusinessChatLink, passing the slug to obtain info about the link as a account.resolvedBusinessChatLinks and increase the view counter.
• Open the returned peer, pre-filling the text input field with the returned message and entities (if present).

t.me syntax:

t.me/m/<slug>

tg: syntax:

tg://message?slug=<slug>

Parameters:

Name	Optional	Description
slug	Required	Slug to pass to account.resolveBusinessChatLink and link management methods.

Video chat/Livestream links

Used to join video/voice chats in groups, and livestreams in channels.
Such links are generated using phone.exportGroupCallInvite.
Note that voicechat links are deprecated, the API will always export videochat links for video and voice chats in groups, clients should support parsing the old link format only for backwards compatibility.

t.me syntax:

t.me/<username>?videochat
t.me/<username>?videochat=<invite_hash>
t.me/<username>?livestream
t.me/<username>?livestream=<invite_hash>
t.me/<username>?voicechat
t.me/<username>?voicechat=<invite_hash>

tg: syntax:

tg://resolve?domain=<username>&videochat
tg://resolve?domain=<username>&videochat=<invite_hash>
tg://resolve?domain=<username>&livestream
tg://resolve?domain=<username>&livestream=<invite_hash>
tg://resolve?domain=<username>&voicechat
tg://resolve?domain=<username>&voicechat=<invite_hash>

Parameters:

Name	Optional	Description
invite_hash	Optional	Invite hash exported if the can_self_unmute flag is set when calling phone.exportGroupCallInvite: should be passed to phone.joinGroupCall, allows the user to speak in livestreams or muted group chats.

Stickerset links

Used to import stickersets or custom emoji stickersets as described here ».

t.me syntax:

t.me/addstickers/<slug>
t.me/addemoji/<slug>

tg: syntax:

tg://addstickers?set=<slug>
tg://addemoji?set=<slug>

Parameters:

Name	Optional	Description
slug	Required	Stickerset short name, used when installing stickers.

Custom emoji stickerset links

Used to import custom emoji stickersets as described here ».

t.me syntax:

t.me/addemoji/<slug>

tg: syntax:

tg://addemoji?set=<slug>

Parameters:

Name	Optional	Description
slug	Required	Stickerset short name, used when installing stickers.

Story links

Used to link to a Telegram Story », generated using the procedure specified here ».

t.me syntax:

t.me/<username>/s/<story_id>

tg: syntax:

tg://resolve?domain=<username>&story=<story_id>

Parameters:

Name	Optional	Description
username	Required	Username of the user or channel that posted the story.
story_id	Required	ID of the Telegram Story to be fetched and viewed as described here ».

Boost links

Used by users to boost channels », granting them the ability to post stories and further perks.

Use the channel information to boost the channel as described here ».

t.me syntax (public channels):

t.me/boost/<username>
t.me/<username>?boost

t.me syntax (private channels):

t.me/boost?c=<id>
t.me/c/<id>?boost

tg: syntax (public channels):

tg://boost?domain=<username>

tg: syntax (private channels):

tg://boost?channel=<id>

Parameters:

Name	Optional	Description
username	Required for public links	Channel username.
channel	Required for private links	Channel ID.

Proxy links

Used to share a proxy server that can be used to connect to Telegram.

MTProxy links

Used for MTProxies ».

t.me syntax:

t.me/proxy?server=<server>&port=<port>&secret=<secret>

tg: syntax:

tg://proxy?server=<server>&port=<port>&secret=<secret>

Parameters:

Name	Optional	Description
server	Required	MTProxy server IP address or host
port	Required	MTProxy server port
secret	Required	MTProxy secret »

Socks5 proxy links

Used for socks5 proxies.

t.me syntax:

t.me/socks?server=<server>&port=<port>&user=<user>&pass=<pass>

tg: syntax:

tg://socks?server=<server>&port=<port>&user=<user>&pass=<pass>

Parameters:

Name	Optional	Description
server	Required	Proxy server IP address or host
port	Required	Proxy server port
user	Optional	Proxy server username
pass	Optional	Proxy server password

Theme links

Used to install themes ».

t.me syntax:

t.me/addtheme/<name>

tg: syntax:

tg://addtheme?slug=<name>

Parameters:

Name	Optional	Description
name	Required	Theme short name used when installing themes »

Wallpaper links

Used to share and install chat backgrounds (wallpapers): see here for more info on the various wallpaper and fill types ».

Image wallpapers

Used for image-based wallpapers ».

t.me syntax:

t.me/bg/<slug>?mode=<mode>

tg: syntax:

tg://bg?slug=<slug>&mode=<mode>

Parameters:

Name	Optional	Description
slug	Required	Wallpaper slug used to obtain the image file using account.getWallPaper.
mode	Optional	A combination of blur and motion (joined by +) to enable blurring and/or parallax motion as specified in the docs ».

Solid fill wallpapers

Used for fill wallpapers » with a solid fill ».

t.me syntax:

t.me/bg/<hex_color>

tg: syntax:

tg://bg?color=<hex_color>

Parameters:

Name	Optional	Description
hex_color	Required	Fill color in hex RGB format.

Gradient fill wallpapers

Used for fill wallpapers » with a gradient fill ».

t.me syntax:

t.me/bg/<top_color>-<bottom_color>?rotation=<rotation>

tg: syntax:

tg://bg?gradient=<top_color>-<bottom_color>&rotation=<rotation>

Parameters:

Name	Optional	Description
top_color	Required	Top gradient color in hex RGB format.
bottom_color	Required	Bottom gradient color in hex RGB format.
rotation	Optional	Clockwise rotation angle of the gradient, in degrees; 0-359. Must be always divisible by 45, default to 0 if not set.

Freeform gradient fill wallpapers

Used for fill wallpapers » with a freeform gradient fill ».

t.me syntax:

t.me/bg/<hex_color1>~<hex_color2>~<hex_color3>
t.me/bg/<hex_color1>~<hex_color2>~<hex_color3>~<hex_color4>

tg: syntax:

tg://bg?gradient=<hex_color1>~<hex_color2>~<hex_color3>
tg://bg?gradient=<hex_color1>~<hex_color2>~<hex_color3>~<hex_color4>

Parameters:

Name	Optional	Description
hex_color1	Required	First gradient color in hex RGB format.
hex_color2	Required	Second gradient color in hex RGB format.
hex_color3	Required	Third gradient color in hex RGB format.
hex_color4	Optional	Fourth gradient color in hex RGB format.

Solid pattern wallpapers

Used for pattern wallpapers » with a solid fill ».

t.me syntax:

t.me/bg/<slug>?intensity=<intensity>&bg_color=<bg_color>&mode=<mode>

tg: syntax:

tg://bg?slug=<slug>&intensity=<intensity>&bg_color=<bg_color>&mode=<mode>

Parameters:

Name	Optional	Description
slug	Required	Wallpaper slug used to obtain the pattern file using account.getWallPaper.
intensity	Required	A value ranging from -100 to 100, used to combine the pattern with the fill as specified in the docs.
bg_color	Required	Fill color in hex RGB format.
mode	Optional	motion to enable parallax motion as specified in the docs.

Gradient pattern wallpapers

Used for pattern wallpapers » with a gradient fill ».

t.me syntax:

t.me/bg/<slug>?intensity=<intensity>&bg_color=<top_color>-<bottom_color>&rotation=<rotation>&mode=<mode>

tg: syntax:

tg://bg?slug=<slug>&intensity=<intensity>&bg_color=<top_color>-<bottom_color>&rotation=<rotation>&mode=<mode>

Parameters:

Name	Optional	Description
slug	Required	Wallpaper slug used to obtain the pattern file using account.getWallPaper.
intensity	Required	A value ranging from -100 to 100, used to combine the pattern with the fill as specified in the docs.
top_color	Required	Top gradient color in hex RGB format.
bottom_color	Required	Bottom gradient color in hex RGB format.
rotation	Optional	Clockwise rotation angle of the gradient, in degrees; 0-359. Must be always divisible by 45, default to 0 if not set.
mode	Optional	motion to enable parallax motion as specified in the docs.

Freeform gradient pattern wallpapers

Used for pattern wallpapers » with a freeform gradient fill ».

t.me syntax:

t.me/bg/<slug>?intensity=<intensity>&bg_color=<hex_color1>~<hex_color2>~<hex_color3>&mode=<mode>
t.me/bg/<slug>?intensity=<intensity>&bg_color=<hex_color1>~<hex_color2>~<hex_color3>~<hex_color4>&mode=<mode>

tg: syntax:

tg://bg?slug=<slug>&intensity=<intensity>&bg_color=<hex_color1>~<hex_color2>~<hex_color3>&mode=<mode>
tg://bg?slug=<slug>&intensity=<intensity>&bg_color=<hex_color1>~<hex_color2>~<hex_color3>~<hex_color4>&mode=<mode>

Parameters:

Name	Optional	Description
slug	Required	Wallpaper slug used to obtain the pattern file using account.getWallPaper.
intensity	Required	A value ranging from -100 to 100, used to combine the pattern with the fill as specified in the docs.
hex_color1	Required	First gradient color in hex RGB format.
hex_color2	Required	Second gradient color in hex RGB format.
hex_color3	Required	Third gradient color in hex RGB format.
hex_color4	Optional	Fourth gradient color in hex RGB format.
mode	Optional	motion to enable parallax motion as specified in the docs.

Bot links

Used to link to bots.

t.me syntax:

t.me/<bot_username>?start=<parameter>

tg: syntax:

tg://resolve?domain=<bot_username>&start=<parameter>

Note that referral links have a similar syntax, with a mandatory prefix in parameter.

Parameters:

Name	Optional	Description
bot_username	Required	Bot username
parameter	Optional	Start parameter, up to 64 base64url characters: if provided and the bot_username is indeed a bot, the text input bar should be replaced with a Start button (even if the user has already started the bot) that should invoke messages.startBot with the appropriate parameter once clicked. Note that if the bot_username is equal to the premium_bot_username configuration value », clicking on this link should immediately invoke messages.startBot with the appropriate parameter.

Group/channel bot links

Used to add bots to groups or channels.
First of all, check that the <bot_username> indeed links to a bot.
Then, for group links:

• If the admin parameter is not provided:
  • Bring up a dialog selection of groups where the user can add members
  • Add the bot to the group
  • If a parameter is provided, invoke messages.startBot with the appropriate parameter
• If the admin parameter is provided:
  • Bring up a dialog selection of groups where the user can add/edit admins
  • If the bot is already an admin of the group, combine existing admin rights with the admin rights in admin
  • Add the bot as admin/modify admin permissions to the new rights
  • If a parameter is provided, invoke messages.startBot with the appropriate parameter

For channel links:

• Bring up a dialog selection of channels where the user can add/edit admins
• If the bot is already an admin of the channel, combine existing admin rights with the admin rights in admin
• Add the bot as admin/modify admin permissions to the new rights

t.me syntax (groups):

t.me/<bot_username>?startgroup=<parameter>&admin=<permissions>
t.me/<bot_username>?startgroup&admin=<permissions>

tg: syntax (groups):

tg://resolve?domain=<bot_username>&startgroup=<parameter>&admin=<permissions>
tg://resolve?domain=<bot_username>&startgroup&admin=<permissions>

t.me syntax (channels):

t.me/<bot_username>?startchannel&admin=<permissions>

tg: syntax (channels):

tg://resolve?domain=<bot_username>&startchannel&admin=<permissions>

Parameters:

Name	Optional	Description
bot_username	Required	Bot username
parameter	Optional for group links, absent in channel links	Start parameter, only for group links, up to 64 base64url characters: if provided and the bot_username is indeed a bot, messages.startBot with the appropriate parameter should be invoked after adding the bot to the group.
admin	Optional for group links, required for channel links	A combination of the following identifiers separated by +, each corresponding to the appropriate flag in the chatAdminRights » constructor: - change_info - chatAdminRights.change_info - post_messages - chatAdminRights.post_messages - edit_messages - chatAdminRights.edit_messages - delete_messages - chatAdminRights.delete_messages - restrict_members - chatAdminRights.ban_users - invite_users - chatAdminRights.invite_users - pin_messages - chatAdminRights.pin_messages - manage_topics - chatAdminRights.manage_topics - promote_members - chatAdminRights.add_admins - manage_video_chats - chatAdminRights.manage_call - anonymous - chatAdminRights.anonymous - manage_chat - chatAdminRights.other - post_stories - chatAdminRights.post_stories - edit_stories - chatAdminRights.edit_stories - delete_stories - chatAdminRights.delete_stories

Game links

Used to share games.

These links should be handled as follows:

• Check if bot_username is indeed a bot username, if so then
• Bring up a dialog selection prompt
• Send the game to the selected dialog using an inputMediaGame with an inputGameShortName as specified in the game docs.

t.me syntax:

t.me/<bot_username>?game=<short_name>

tg: syntax:

tg://resolve?domain=<bot_username>&game=<short_name>

Parameters:

Name	Optional	Description
bot_username	Required	Username of the bot that owns the game
short_name	Required	Game short name

Settings links

Settings link

Used to bring the user to the app settings.

tg: syntax:

tg://settings

No parameters.

Change phone number link

Used to bring the user to the phone number modification page, invoking account.sendChangePhoneCode and account.changePhone.

tg: syntax:

tg://settings/change_number

No parameters.

Active sessions link

Used to bring the user to the active sessions page, calling account.getAuthorizations.

tg: syntax:

tg://settings/devices

No parameters.

Folder settings link

Used to bring the user to the folder settings.

tg: syntax:

tg://settings/folders

No parameters.

Language settings link

Used to bring the user to the language settings.

tg: syntax:

tg://settings/language

No parameters.

Privacy and security settings link

Used to bring the user to the privacy and security settings.

tg: syntax:

tg://settings/privacy

No parameters.

Autodelete settings link

Used to bring the user to the message autodeletion settings.

tg: syntax:

tg://settings/auto_delete

No parameters.

Profile settings link

Used to bring the user to the profile settings menu.

tg: syntax:

tg://settings/edit_profile

No parameters.

Theme settings link

Used to bring the user to the theme settings section of the app.

tg: syntax:

tg://settings/theme

No parameters.

Login code link

Contains the phone number verification code to use during user authorization ».

t.me syntax:

t.me/login/<code>

tg: syntax:

tg://login?code=<code>

Parameters:

Name	Optional	Description
code	Required	Login code.

Invoice links

Used to initiate payment of an invoice », generated using payments.exportedInvoice.

t.me syntax:

t.me/invoice/<slug>
t.me/$<slug>

tg: syntax:

tg://invoice?slug=<slug>

Parameters:

Name	Optional	Description
slug	Required	The invoice slug to be used during payment ».

Language pack links

Used to import custom language packs using langpack.getLangPack.

t.me syntax:

t.me/setlanguage/<slug>

tg: syntax:

tg://setlanguage?lang=<slug>

Parameters:

Name	Optional	Description
slug	Required	Name of language pack to import using langpack.getLangPack

Telegram Passport links

See the Telegram Passport documentation for parameters and usage ».

tg: syntax:

tg://passport?params
tg://resolve?domain=telegrampassport&params

Phone confirmation links

Different from login code links.
These links are used to confirm ownership of the phone number, to prevent account deletion: see the account deletion docs for more info on how to handle them ».

t.me syntax:

t.me/confirmphone?phone=<phone>&hash=<hash>

tg: syntax:

tg://confirmphone?phone=<phone>&hash=<hash>

Parameters:

Name	Optional	Description
phone	Required	Phone number
hash	Required	Confirmation hash to handle as described here »

Premium multigift links

Used to bring the user to the screen used for gifting Telegram Premium subscriptions to friends, see here for more info on gifting Telegram Premium to multiple users ».

This link is used to invite users to gift Premium subscription to other users, see here » for the different link type containing the actual giftcodes that can be used to import a gifted Telegram Premium subscription.

tg: syntax:

tg://premium_multigift?ref=<referrer>

Parameters:

Name	Optional	Description
referrer	Optional	Used by official apps for analytics using help.saveAppLog.

Premium referrer links

Used by official apps to show the Telegram Premium subscription page.

tg: syntax:

tg://premium_offer?ref=<referrer>

Parameters:

Name	Optional	Description
referrer	Optional	Used by official apps for analytics using help.saveAppLog

Premium giftcode links

Used to process Telegram Premium giftcode links.

tg: syntax:

tg://giftcode?slug=<slug>

t.me syntax:

t.me/giftcode/<slug>

Parameters:

Name	Optional	Description
slug	Optional	Gift code slug to be passed to payments.checkGiftCode to obtain further info, and eventually to payments.applyGiftCode to apply it. See the giveaways documentation for more info.

QR code login links

Used by the QR code login flow ».

tg: syntax:

tg://login?token=<base64encodedtoken>

Parameters:

Name	Optional	Description
server	Required	Base64URL-encoded QR code login token

Main Mini App links

Used to open Main Mini Apps ».

If the specified bot does not have a configured Main Mini App (i.e. the user.bot_has_main_app flag will not be set), fall back to the behavior of username links ».

The main mini app should be opened using messages.requestMainWebView.

t.me syntax:

t.me/<bot_username>?startapp&mode=<mode>
t.me/<bot_username>?startapp=<start_parameter>&mode=<mode>

Note that Direct Mini App links have a similar syntax, with an additional short_name parameter to identify a specific Mini App owned by the bot.

tg: syntax:

tg://resolve?domain=<bot_username>&startapp&mode=<mode>
tg://resolve?domain=<bot_username>&startapp=<start_parameter>&mode=<mode>

Parameters:

Name	Optional	Description
bot_username	Required	Username of the bot that owns the main mini app »
start_parameter	Optional	If provided, should be passed to messages.requestMainWebView.start_param
mode	Optional	If equal to compact, the messages.requestMainWebView.compact flag must be set. If equal to fullscreen, the app must be opened in fullscreen mode.

Direct mini app links

Used to share Direct link Mini apps.

These links are different from bot attachment menu deep links, because they don't require the user to install an attachment menu, and a single bot can offer multiple named mini apps, distinguished by their short_name.

These links should be handled as specified in the direct link Mini Apps documentation ».

t.me syntax:

t.me/<bot_username>/<short_name>?startapp=<start_parameter>&mode=<mode>

tg: syntax:

tg://resolve?domain=<bot_username>&appname=<short_name>&startapp=<start_parameter>&mode=<mode>

Note that Main Mini App links have a similar syntax, without a short_name parameter.

Parameters:

Name	Optional	Description
bot_username	Required	Username of the bot that owns the game
appname	Required	Mini app short name, to pass to inputBotAppShortName.short_name when invoking messages.getBotApp
startapp	Optional	start_param to pass to messages.requestAppWebView
mode	Optional	If equal to compact, the messages.requestAppWebView.compact flag must be set. If equal to fullscreen, the app must be opened in fullscreen mode.

Bot attachment or side menu links

Used to install and open a bot attachment or side menu » in a certain chat.
For all link types, clients should first install the associated bot attachment or side menu entry as specified here », and if the user accepts the installation prompt, open the Mini App using the following logic, depending on the link subtype:

Open in current chat

After installing the attachment/side menu entry globally, opens the associated mini app using messages.requestWebView in the currently open chat, by passing it to the peer parameter of messages.requestWebView.

If the current chat is not supported by the attachMenuBot.peer_types field:

• If the user has just installed the attachment menu in the previous step, notify the user that the attachment menu was installed successfully.
• Otherwise, notify the user that the attachment menu webapp can't be opened in the specified chat.

t.me syntax:

t.me/<bot_username>?startattach
t.me/<bot_username>?startattach=<start_parameter>

tg: syntax:

tg://resolve?domain=<bot_username>&startattach
tg://resolve?domain=<bot_username>&startattach=<start_parameter>

Parameters:

Name	Optional	Description
bot_username	Required	Username of the bot that owns the attachment/side menu entry
start_parameter	Optional	If provided, should be passed to messages.requestWebView.start_param

Open in specific chat

After installing the attachment/side menu entry globally, opens the associated mini app using messages.requestWebView in a specific chat (passed to the peer parameter of messages.requestWebView).

t.me syntax:

t.me/<username>?attach=<bot_username>
t.me/<username>?attach=<bot_username>&startattach=<start_parameter>
t.me/+<phone_number>?attach=<bot_username>
t.me/+<phone_number>?attach=<bot_username>&startattach=<start_parameter>

tg: syntax:

tg://resolve?domain=<username>&attach=<bot_username>
tg://resolve?domain=<username>&attach=<bot_username>&startattach=<start_parameter>
tg://resolve?phone=<phone_number>&attach=<bot_username>
tg://resolve?phone=<phone_number>&attach=<bot_username>&startattach=<start_parameter>

If the specified chat is not supported by the attachMenuBot.peer_types field:

• If the user has just installed the attachment menu in the previous step, notify the user that the attachment menu was installed successfully.
• Otherwise, notify the user that the attachment menu webapp can't be opened in the specified chat.

Parameters:

Name	Optional	Description
username	Required for username links	Username of chat where to open the mini app
phone_number	Required for phone number links	Phone number of private chat where to the open mini app
bot_username	Required	Username of the bot that owns the attachment/side menu
start_parameter	Optional	If provided, should be passed to messages.requestWebView.start_param

Open in any chat

After installing the attachment/side menu entry globally, opens a dialog selection form that will open the attachment menu mini app using messages.requestWebView in a specific chat (pass it to the peer parameter of messages.requestWebView).

t.me syntax:

t.me/<bot_username>?startattach&choose=users+bots+groups+channels
t.me/<bot_username>?startattach=<start_parameter>&choose=users+bots+groups+channels

tg: syntax:

tg://resolve?domain=<bot_username>&startattach&choose=users+bots+groups+channels
tg://resolve?domain=<bot_username>&startattach=<start_parameter>&choose=users+bots+groups+channels

Parameters:

Name	Optional	Description
bot_username	Required	Username of the bot that owns the attachment/side menu
start_parameter	Optional	If provided, should be passed to messages.requestWebView.start_param
choose	Optional	A combination of users, bots, groups, channels separated by +: indicates the dialog types to show in the dialog selection popup: must be intersected with the dialog types contained in the attachMenuBot.peer_types field before use.

Stars topup link

Used to ensure that the user has at least N Telegram Stars on their balance.
If not, this link must bring the user to the Telegram Star topup page.

tg: syntax:

tg://stars_topup?balance=<star_count>&purpose=<purpose>

Parameters:

Name	Optional	Description
star_count	Required	Indicates the number of required stars to execute an action (integer, must be clamped between 1 and 1000000000000). If the current balance is higher than or equal to this value, instead of bringing up the topup form, a simple toast should be displayed, indicating that the user already has enough stars to complete the operation: this toast should also contain a "Buy anyway" button that must bring up the star topup form unconditionally.
purpose	Optional	Contains a string indicating the reason why the topup is required, that must be shown on the topup page (if activated), possible values: - subs - Buy Stars to keep your channel subscriptions. - subadvance12 - Buy Stars to keep your subscriptions active for the next 12 months.

Referral links

Used for Affiliate programs: when imported, all Telegram Star purchases made for digital products and subscriptions in the associated mini app will also transfer a certain amount of Stars to the creator of the link.

See here » for more info on the full flow.

t.me syntax:

t.me/<bot_username>?ref=<referrer>
t.me/<bot_username>?start={prefix}<referrer>

tg: syntax:

tg://resolve?domain=<bot_username>&ref=<referrer>
tg://resolve?domain=<bot_username>&start={prefix}<referrer>

{prefix} is any of the prefixes specified in the starref_start_param_prefixes client configuration parameter »: it is mandatory for the second variants of referral links, to distinguish them from bot links.

Parameters:

Name	Optional	Description
bot_username	Required	Username of the bot that owns the mini app
referrer	Required	Referral ID, to be passed to contacts.resolveUsername

ID links

ID links are merely an abstraction offered by the bot API to simplify construction of inputMessageEntityMentionName and inputKeyboardButtonUserProfile constructors, and should be ignored by normal clients.

tg: syntax:

tg://user?id=<id>

Parameters:

Name	Optional	Description
id	Required	User ID

Emoji links

Emoji links are merely an abstraction offered by the bot API to simplify construction of messageEntityCustomEmoji constructors, and should be ignored by normal clients.

tg: syntax:

tg://emoji?id=<id>

Parameters:

Name	Optional	Description
id	Required	Custom emoji ID

Unsupported links

If a client encounters a tg: link type not listed on this page, help.getDeepLinkInfo should be invoked with just the path component of the link.

Schema:

help.deepLinkInfoEmpty#66afa166 = help.DeepLinkInfo;
help.deepLinkInfo#6a4ee832 flags:# update_app:flags.0?true message:string entities:flags.1?Vector<MessageEntity> = help.DeepLinkInfo;

---functions---

help.getDeepLinkInfo#3fedc75f path:string = help.DeepLinkInfo;

The method may return formatted text, containing for example:

• A description of what the link does or,
• An explanation of why a certain link isn't supported by the app;

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 update_app flag will also be set, and the app should directly link to a store or attempt updating to the latest version.

Example links that can be used for testing:

• tg://need_update_for_some_feature?test=a
• tg:some_unsupported_feature?test=b

In these cases, help.getDeepLinkInfo should be invoked with the following parameters:

• help.getDeepLinkInfo({path: "need_update_for_some_feature"})
• help.getDeepLinkInfo({path: "some_unsupported_feature"})

Note that this method should not be called for unrecognized t.me links, the usual HTTP link handling logic must be used, instead.