# Deep links


<!-- ref: 92d814640d1871320e125b68b0181e34a48f86d8 -->

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](/constructor/config.md), obtainable using [help.getConfig](/method/help.getConfig.md).

`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** a single letter AND is **not** equal to `www` AND is a valid username AND is **not** equal to any of:

<!-- start disallowed t.me subdomains -->

- `addemoji`
- `addlist`
- `addstickers`
- `addstyle`
- `addtheme`
- `auction`
- `auth`
- `boost`
- `call`
- `confirmphone`
- `contact`
- `giftcode`
- `invoice`
- `joinchat`
- `login`
- `m`
- `nft`
- `proxy`
- `setlanguage`
- `share`
- `socks`
- `web`
- `a`
- `k`
- `z`

<!-- end disallowed t.me subdomains -->

...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&nbsp;&raquo;](/api/bots/ids.md) for info on how to convert it to bot API format.  

### TON Sites

Used to open [TON Sites](https://blog.ton.org/ton-sites) using the in-app [Telegram Browser](https://telegram.org/blog/w3-browser-mini-app-store#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 as follows:
  * 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&nbsp;&raquo;](/api/config.md#ton-proxy-address)

The resulting URL should only be opened using the in-app [Telegram Browser](https://telegram.org/blog/w3-browser-mini-app-store#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&nbsp;&raquo;](/api/invites.md#public-usernames).  

`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&nbsp;&raquo;](/api/invites.md#public-usernames) |
| `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](/api/bots/inline.md)). \
- Trim the text to [message_length_max](/constructor/config.md) 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](#message-links) and [monoforum links](#monoforum-links) have the same or similar syntax, with extra parameters.  

### Monoforum links

Used to open the direct messages chat (aka [monoforum &raquo;](/api/monoforum.md)) associated to a channel, see [here for more info on monoforums&nbsp;&raquo;](/api/monoforum.md).  

**Note**: when sharing messages sent to a monoforum, use [normal message links &raquo;](#message-links) with the ID of the monoforum, not the ID of the associated channel; the same rule applies for all other chat-related links involving a monoforum.  

`t.me` syntax:
```
t.me/<username>?direct
```

`tg:` syntax:
```
tg://resolve?domain=<username>&direct
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `username` | Required | Username of the channel, that has an associated monoforum. |
| `direct` | Required | Distinguishes monoforum links from other link types. |

Note that [public username links](#public-username-links) have a similar syntax, but don't have the `direct` flag.  

### Temporary profile links

Used to link to user profiles, generated using [contacts.exportContactToken](/method/contacts.exportContactToken.md).  
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/exportedContactToken.md) constructor returned by [contacts.exportContactToken](/method/contacts.exportContactToken.md).  

`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](/method/contacts.importContactToken.md), 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](/method/contacts.resolvePhone.md) |
| `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](/api/bots/inline.md)). \
- Trim the text to [message_length_max](/constructor/config.md) 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](#message-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&nbsp;&raquo;](/api/invites.md#invite-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&nbsp;&raquo;](/api/invites.md#invite-links) |

### Chat folder links

Used to invite users to private groups and channels, see [here for more info on how to generate such links&nbsp;&raquo;](/api/folders.md#shared-folders).  

`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&nbsp;&raquo;](/api/folders.md#shared-folders) |

### 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>&task=<task_id>&option=<option_id>
t.me/<username>/<thread_id>/<id>?single&comment=<comment>&t=<media_timestamp>&task=<task_id>&option=<option_id>
```

`t.me` syntax (private links):  
```
t.me/c/<channel>/<id>?single&thread=<thread_id>&comment=<comment>&t=<media_timestamp>&task=<task_id>&option=<option_id>
t.me/c/<channel>/<thread_id>/<id>?single&comment=<comment>&t=<media_timestamp>&task=<task_id>&option=<option_id>
```

`tg:` syntax (public links):
```
tg://resolve?domain=<username>&post=<id>&single&thread=<thread_id>&comment=<comment>&t=<media_timestamp>&task=<task_id>&option=<option_id>
```

`tg:` syntax (private links):
```
tg://privatepost?channel=<channel>&post=<id>&single&thread=<thread_id>&comment=<comment>&t=<media_timestamp>&task=<task_id>&option=<option_id>
```

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](/api/threads.md), contains the thread ID. |
| `comment` | Optional | For [channel comments](/api/discussion.md), `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)$` |
| `task_id` | Optional | Positive integer ID of a specific task to highlight, when the linked message contains a [checklist&nbsp;&raquo;](/api/todo.md), corresponding to a [todoItem](/constructor/todoItem.md).`id`. Invalid (non-positive or non-numeric) values should be treated as an error. |
| `option_id` | Optional | base64url-encoded identifier of a specific [poll&nbsp;&raquo;](/constructor/poll.md) option to highlight, when the linked message contains a poll, corresponding to a [pollAnswer](/constructor/pollAnswer.md).`option`. The decoded value must be valid UTF-8, otherwise it should be ignored. |

Note that since a [forum topic](/api/forum.md#forum-topics) ID is actually the ID of the service message that created the topic, whenever the client resolves a [message link](#message-links) that points to a [messageActionTopicCreate](/constructor/messageActionTopicCreate.md) 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](/api/forum.md#forum-topics).  

The syntax is exactly the same as for [message links](#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](#message-links) that points to a [messageActionTopicCreate](/constructor/messageActionTopicCreate.md) 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>
t.me/share/url?url=<url>&text=<text>
t.me/share/url/?url=<url>&text=<text>
t.me/msg/url?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&nbsp;&raquo;](/api/business.md#business-chat-links) allow business owners to share pre-made links to their [Telegram Business](/api/business.md) account, optionally filling out the message input field with a pre-prepared message (with support for [styled text entities&nbsp;&raquo;](/api/entities.md)).  

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&nbsp;&raquo;](/api/business.md#business-chat-links) 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](/method/account.resolveBusinessChatLink.md), passing the `slug` to obtain info about the link as a [account.resolvedBusinessChatLinks](/constructor/account.resolvedBusinessChatLinks.md) 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](/method/account.resolveBusinessChatLink.md) 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](/method/phone.exportGroupCallInvite.md).  
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](/method/phone.exportGroupCallInvite.md): should be passed to [phone.joinGroupCall](/method/phone.joinGroupCall.md), allows the user to speak in livestreams or muted group chats. |

### Conference links

Used to link to [E2E conference calls](/api/end-to-end/group-calls.md).

`t.me` syntax:
```
t.me/call/<slug>
```

`tg:` syntax:
```
tg://call?slug=<slug>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `slug` | Required | E2E conference call invitation hash to pass to the conference call methods. |

### Stickerset links

Used to import stickersets or [custom emoji](/api/custom-emoji.md) stickersets as described [here&nbsp;&raquo;](/api/stickers.md#installing-stickersets).

`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](/api/stickers.md#installing-stickersets). |

### Custom emoji stickerset links

Used to import [custom emoji](/api/custom-emoji.md) stickersets as described [here&nbsp;&raquo;](/api/stickers.md#installing-stickersets).

`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](/api/stickers.md#installing-stickersets). |

### Story links

Used to link to a [Telegram Story&nbsp;&raquo;](/api/stories.md), generated using the procedure [specified here&nbsp;&raquo;](/api/links.md#story-links).  

`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&nbsp;&raquo;](/api/stories.md#watching-stories).\
If equal to `live`, this is a [live story link &raquo;](#live-story-links), instead. |

#### Live story links

A special variant of [story links](#story-links) used to open the currently ongoing live story posted by a user or channel (the literal `live` keyword is used in place of the story ID).  

`t.me` syntax:
```
t.me/<username>/s/live
```

`tg:` syntax:
```
tg://resolve?domain=<username>&story=live
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `username` | Required | Username of the user or channel that posted the live story. |

### Story album links

Identifies a [story album &raquo;](/api/stories.md#story-albums) on a peer's profile: use [stories.getAlbumStories](/method/stories.getAlbumStories.md) to fetch stories within the specified album.  

`t.me` syntax:
```
t.me/<username>?album=<album_id>
t.me/<username>/a/<album_id>
```

`tg:` syntax:
```
tg://resolve?domain=<username>&album=<album_id>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `username` | Required | Username of the peer that owns the collection. |
| `album_id` | Required | Integer ID of the [story album &raquo;](/api/stories.md#story-albums), from [storyAlbum](/constructor/storyAlbum.md).`album_id`. |

### Post story links

Used to bring the user to the [story&nbsp;&raquo;](/api/stories.md) composer, optionally pre-selecting the type of story content to post.  

`tg:` syntax:
```
tg://post
tg://post/<content_type>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `content_type` | Optional | Type of story content to compose; if absent, the composer is opened without pre-selecting a content type. Recognized values: \
<!-- start_table post story content types -->\
\
- `photo` - Compose a photo story.\
- `video` - Compose a video story.\
- `live` - Compose a live story.\
\
<!-- end_table post story content types -->\
Any other non-empty value indicates a content type unsupported by the current client version, and should be handled by prompting the user to update the app. |

### Managed bot creation request links

Used to request creation of a new [managed bot &raquo;](/api/bots/managed-bots.md).  

Handle this link by starting the [managed bot creation flow &raquo;](/api/bots/managed-bots.md#creating-a-managed-bot), additionally setting the `via_deeplink` flag when finally invoking [bots.createBot](/method/bots.createBot.md).  

`t.me` syntax:
```
t.me/newbot/<manager_bot_username>/<suggested_bot_username>?name=<suggested_bot_name>
t.me/newbot/<manager_bot_username>?name=<suggested_bot_name>
```

`tg:` syntax:
```
tg://newbot?manager=<manager_bot_username>&username=<suggested_bot_username>&name=<suggested_bot_name>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `manager_bot_username` | Required | Username of the manager bot, passed to [bots.createBot](/method/bots.createBot.md).`manager_id`. \
Before using this value, resolve it and make sure that it's associated to a manager bot (i.e. the resolved [user](/constructor/user.md) must have the `bot_can_manage_bots` flag set). |
| `suggested_bot_username` | Optional | Suggested username for the managed bot that will be created, passed to [bots.createBot](/method/bots.createBot.md).`username`. \
If non-empty, and the passed value does **not** end in `bot`, append `bot` to the value before recommending it to the user. \
Can be empty, in which case the user must choose a username before invoking [bots.createBot](/method/bots.createBot.md). |
| `suggested_bot_name` | Optional | Suggested name for the managed bot that will be created, passed to [bots.createBot](/method/bots.createBot.md).`name`. \
Can be empty, in which case the user must choose a name before invoking [bots.createBot](/method/bots.createBot.md). |

### Boost links

Used by users to [boost channels&nbsp;&raquo;](/api/boost.md), granting them the ability to post stories and further perks.

Use the channel information to boost the channel as described [here&nbsp;&raquo;](/api/boost.md).  

`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. |

### OAuth links

Used to authorize an incoming [OAuth Telegram login request &raquo;](/api/url-authorization.md#oauth-authorization).  

Note that while the `token` must still be validated individually (it must be non-empty), the **entire deep link**, not just the `token` parameter, needs to be passed **verbatim** to [messages.requestUrlAuth](/method/messages.requestUrlAuth.md) as specified [here &raquo;](/api/url-authorization.md#oauth-authorization).   

**Important**: only handle this deep link if the request to open it comes from outside the app; do **not** handle it if it was clicked inside of the app, for example in messages, [buttons](/api/bots/buttons.md), the built-in browser and [mini apps](/api/bots/webapps.md), etc.  

Note that mini apps can still use OAuth login but [in a slightly different manner &raquo;](/api/url-authorization.md#oauth-authorization-for-mini-apps).  

`t.me` syntax:

```
https://t.me/oauth?startapp=<token>
```

`tg:` syntax:

```
tg://oauth?token=<token>
tg://resolve?domain=oauth&startapp=<token>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `token` | Required | OAuth token, must be non-empty. |

### Proxy links

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

#### MTProxy links

Used for [MTProxies&nbsp;&raquo;](/mtproto/mtproto-transports.md#transport-obfuscation).

`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&nbsp;&raquo;](/mtproto/mtproto-transports.md#transport-obfuscation) |

#### 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&nbsp;&raquo;](/api/themes.md#installing-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&nbsp;&raquo;](/api/themes.md#installing-themes) |

### AI compose tone links

Used to share and install a custom [AI composer tone&nbsp;&raquo;](/api/ai.md#ai-compose-tones).

Handle this link by resolving the slug with [aicompose.getTone](/method/aicompose.getTone.md), passing an [inputAiComposeToneSlug](/constructor/inputAiComposeToneSlug.md) with the `slug`, then show a preview of the returned [aiComposeTone](/constructor/aiComposeTone.md) that lets the user install it with [aicompose.saveTone](/method/aicompose.saveTone.md).  

`t.me` syntax:
```
t.me/addstyle/<slug>
```

`tg:` syntax:
```
tg://addstyle?slug=<slug>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `slug` | Required | Unique [AI composer tone&nbsp;&raquo;](/api/ai.md#ai-compose-tones) slug, as found in [aiComposeTone](/constructor/aiComposeTone.md).`slug`. |

### Wallpaper links

Used to share and install chat backgrounds (wallpapers): see [here for more info on the various wallpaper and fill types&nbsp;&raquo;](/api/wallpapers.md).  

#### [Image wallpapers](/api/wallpapers.md#image-wallpapers)

Used for [image-based wallpapers&nbsp;&raquo;](/api/wallpapers.md#image-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](/method/account.getWallPaper.md). |
| `mode` | Optional | A combination of `blur` and `motion` (joined by `+`) to enable blurring and/or parallax motion as specified in the [docs&nbsp;&raquo;](/api/wallpapers.md#image-wallpapers). |

#### Solid fill wallpapers

Used for [fill wallpapers&nbsp;&raquo;](/api/wallpapers.md#fill-wallpapers) with a [solid fill&nbsp;&raquo;](/api/wallpapers.md#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&nbsp;&raquo;](/api/wallpapers.md#fill-wallpapers) with a [gradient fill&nbsp;&raquo;](/api/wallpapers.md#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.  |

#### Free-form gradient fill wallpapers

Used for [fill wallpapers&nbsp;&raquo;](/api/wallpapers.md#fill-wallpapers) with a [free-form gradient fill&nbsp;&raquo;](/api/wallpapers.md#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&nbsp;&raquo;](/api/wallpapers.md#pattern-wallpapers) with a [solid fill&nbsp;&raquo;](/api/wallpapers.md#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](/method/account.getWallPaper.md). |
| `intensity` | Required | A value ranging from -100 to 100, used to combine the pattern with the fill [as specified in the docs](/api/wallpapers.md#pattern-wallpapers). |
| `bg_color` | Required | Fill color in hex RGB format. |
| `mode` | Optional | `motion` to enable parallax motion as specified in the [docs](/api/wallpapers.md#image-wallpapers). |

#### Gradient pattern wallpapers

Used for [pattern wallpapers&nbsp;&raquo;](/api/wallpapers.md#pattern-wallpapers) with a [gradient fill&nbsp;&raquo;](/api/wallpapers.md#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](/method/account.getWallPaper.md). |
| `intensity` | Required | A value ranging from -100 to 100, used to combine the pattern with the fill [as specified in the docs](/api/wallpapers.md#pattern-wallpapers). |
| `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](/api/wallpapers.md#image-wallpapers). |

#### Free-form gradient pattern wallpapers

Used for [pattern wallpapers&nbsp;&raquo;](/api/wallpapers.md#pattern-wallpapers) with a [free-form gradient fill&nbsp;&raquo;](/api/wallpapers.md#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](/method/account.getWallPaper.md). |
| `intensity` | Required | A value ranging from -100 to 100, used to combine the pattern with the fill [as specified in the docs](/api/wallpapers.md#pattern-wallpapers). |
| `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](/api/wallpapers.md#image-wallpapers). |

### 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`](#referral-links).

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](/method/messages.startBot.md) with the appropriate `parameter` once clicked. Note that if the `bot_username` is equal to the [`premium_bot_username` configuration value&nbsp;&raquo;](/api/config.md#premium-bot-username), clicking on this link should immediately invoke [messages.startBot](/method/messages.startBot.md) 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](/method/messages.startBot.md) 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](/method/messages.startBot.md) 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](/method/messages.startBot.md) 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&nbsp;&raquo;](/constructor/chatAdminRights.md) constructor: \
- `change_info` - [chatAdminRights.change_info](/constructor/chatAdminRights.md) \
- `post_messages` - [chatAdminRights.post_messages](/constructor/chatAdminRights.md) \
- `edit_messages` - [chatAdminRights.edit_messages](/constructor/chatAdminRights.md) \
- `delete_messages` - [chatAdminRights.delete_messages](/constructor/chatAdminRights.md) \
- `restrict_members` - [chatAdminRights.ban_users](/constructor/chatAdminRights.md) \
- `invite_users` - [chatAdminRights.invite_users](/constructor/chatAdminRights.md) \
- `pin_messages` - [chatAdminRights.pin_messages](/constructor/chatAdminRights.md) \
- `manage_topics` - [chatAdminRights.manage_topics](/constructor/chatAdminRights.md) \
- `promote_members` - [chatAdminRights.add_admins](/constructor/chatAdminRights.md) \
- `manage_video_chats` - [chatAdminRights.manage_call](/constructor/chatAdminRights.md) \
- `anonymous` - [chatAdminRights.anonymous](/constructor/chatAdminRights.md) \
- `manage_chat` - [chatAdminRights.other](/constructor/chatAdminRights.md) \
- `post_stories` - [chatAdminRights.post_stories](/constructor/chatAdminRights.md) \
- `edit_stories` - [chatAdminRights.edit_stories](/constructor/chatAdminRights.md) \
- `delete_stories` - [chatAdminRights.delete_stories](/constructor/chatAdminRights.md) \
- `manage_direct_messages` - [chatAdminRights.manage_direct_messages](/constructor/chatAdminRights.md) \
- `manage_tags` - [chatAdminRights.manage_ranks](/constructor/chatAdminRights.md) |

### Game links

Used to share [games](/api/bots/games.md).  

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](/constructor/inputMediaGame.md) with an [inputGameShortName](/constructor/inputGameShortName.md) as specified in the [game docs](/api/bots/games.md#sending-a-game).  

`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](/api/bots/games.md) |
| `short_name` | Required | Game short name |

### Settings links

Used to bring the user to the app settings, optionally directly opening a specific settings page or subsection.  

`tg:` syntax:
```
tg://settings
tg://settings/<path>
```

If no `<path>` is specified, the top-level settings page is opened.  

Otherwise, `<path>` is a slash-separated identifier of the specific settings page or subsection to open. Clients should recognize the values listed below, gracefully falling back to the closest recognized parent page (or, failing that, the top-level settings page) for any unrecognized or only partially-recognized `<path>`.  

<!-- start settings paths -->

- `appearance`
- `appearance/themes`
- `appearance/themes/edit`
- `appearance/themes/create`
- `appearance/wallpapers`
- `appearance/wallpapers/edit`
- `appearance/wallpapers/set`
- `appearance/wallpapers/choose-photo`
- `appearance/your-color/profile`
- `appearance/your-color/profile/add-icons`
- `appearance/your-color/profile/use-gift`
- `appearance/your-color/profile/reset`
- `appearance/your-color/name`
- `appearance/your-color/name/add-icons`
- `appearance/your-color/name/use-gift`
- `appearance/night-mode`
- `appearance/auto-night-mode`
- `appearance/text-size`
- `appearance/text-size/use-system`
- `appearance/message-corners`
- `appearance/animations`
- `appearance/stickers-and-emoji`
- `appearance/stickers-and-emoji/edit`
- `appearance/stickers-and-emoji/trending`
- `appearance/stickers-and-emoji/archived`
- `appearance/stickers-and-emoji/archived/edit`
- `appearance/stickers-and-emoji/emoji`
- `appearance/stickers-and-emoji/emoji/edit`
- `appearance/stickers-and-emoji/emoji/archived`
- `appearance/stickers-and-emoji/emoji/archived/edit`
- `appearance/stickers-and-emoji/emoji/suggest`
- `appearance/stickers-and-emoji/emoji/quick-reaction`
- `appearance/stickers-and-emoji/emoji/quick-reaction/choose`
- `appearance/stickers-and-emoji/suggest-by-emoji`
- `appearance/stickers-and-emoji/large-emoji`
- `appearance/stickers-and-emoji/dynamic-order`
- `appearance/stickers-and-emoji/emoji/show-more`
- `appearance/app-icon`
- `appearance/tap-for-next-media`
- `ask-question`
- `auto_delete`
- `business`
- `business/do-not-hide-ads`
- `change_number`
- `chat/browser`
- `chat/browser/enable-browser`
- `chat/browser/clear-cookies`
- `chat/browser/clear-cache`
- `chat/browser/history`
- `chat/browser/clear-history`
- `chat/browser/never-open`
- `chat/browser/clear-list`
- `chat/browser/search`
- `data`
- `data/storage`
- `data/storage/edit`
- `data/storage/auto-remove`
- `data/storage/clear-cache`
- `data/storage/max-cache`
- `data/usage`
- `data/usage/mobile`
- `data/usage/wifi`
- `data/usage/reset`
- `data/usage/roaming`
- `data/auto-download/mobile`
- `data/auto-download/mobile/enable`
- `data/auto-download/mobile/usage`
- `data/auto-download/mobile/photos`
- `data/auto-download/mobile/stories`
- `data/auto-download/mobile/videos`
- `data/auto-download/mobile/files`
- `data/auto-download/wifi`
- `data/auto-download/wifi/enable`
- `data/auto-download/wifi/usage`
- `data/auto-download/wifi/photos`
- `data/auto-download/wifi/stories`
- `data/auto-download/wifi/videos`
- `data/auto-download/wifi/files`
- `data/auto-download/roaming`
- `data/auto-download/roaming/enable`
- `data/auto-download/roaming/usage`
- `data/auto-download/roaming/photos`
- `data/auto-download/roaming/stories`
- `data/auto-download/roaming/videos`
- `data/auto-download/roaming/files`
- `data/auto-download/reset`
- `data/save-to-photos/chats`
- `data/save-to-photos/chats/max-video-size`
- `data/save-to-photos/chats/add-exception`
- `data/save-to-photos/chats/delete-all`
- `data/save-to-photos/groups`
- `data/save-to-photos/groups/max-video-size`
- `data/save-to-photos/groups/add-exception`
- `data/save-to-photos/groups/delete-all`
- `data/save-to-photos/channels`
- `data/save-to-photos/channels/max-video-size`
- `data/save-to-photos/channels/add-exception`
- `data/save-to-photos/channels/delete-all`
- `data/less-data-calls`
- `data/open-links`
- `data/share-sheet`
- `data/share-sheet/suggested-chats`
- `data/share-sheet/suggest-by`
- `data/share-sheet/reset`
- `data/saved-edited-photos`
- `data/pause-music`
- `data/raise-to-listen`
- `data/raise-to-speak`
- `data/show-18-content`
- `data/proxy`
- `data/proxy/edit`
- `data/proxy/use-proxy`
- `data/proxy/add-proxy`
- `data/proxy/share-list`
- `data/proxy/use-for-calls`
- `devices`
- `devices/edit`
- `devices/link-desktop`
- `devices/terminate-sessions`
- `devices/auto-terminate`
- `edit`
- `edit/set-photo`
- `edit/first-name`
- `edit/last-name`
- `edit/bio`
- `edit/birthday`
- `edit/change-number`
- `edit/username`
- `edit/your-color`
- `edit/channel`
- `edit/add-account`
- `edit/log-out`
- `edit_profile`
- `emoji-status`
- `profile-color/profile`
- `profile-color/profile/add-icons`
- `profile-color/profile/use-gift`
- `profile-color/name`
- `profile-color/name/add-icons`
- `profile-color/name/use-gift`
- `profile-photo/use-emoji`
- `faq`
- `features`
- `folders`
- `folders/edit`
- `folders/create`
- `folders/add-recommended`
- `folders/show-tags`
- `folders/tab-view`
- `language`
- `language/show-button`
- `language/translate-chats`
- `language/do-not-translate`
- `login_email`
- `notifications`
- `notifications/accounts`
- `notifications/private-chats`
- `notifications/private-chats/edit`
- `notifications/private-chats/show`
- `notifications/private-chats/preview`
- `notifications/private-chats/sound`
- `notifications/private-chats/add-exception`
- `notifications/private-chats/delete-exceptions`
- `notifications/private-chats/light-color`
- `notifications/private-chats/vibrate`
- `notifications/private-chats/priority`
- `notifications/groups`
- `notifications/groups/edit`
- `notifications/groups/show`
- `notifications/groups/preview`
- `notifications/groups/sound`
- `notifications/groups/add-exception`
- `notifications/groups/delete-exceptions`
- `notifications/groups/light-color`
- `notifications/groups/vibrate`
- `notifications/groups/priority`
- `notifications/channels`
- `notifications/channels/edit`
- `notifications/channels/show`
- `notifications/channels/preview`
- `notifications/channels/sound`
- `notifications/channels/add-exception`
- `notifications/channels/delete-exceptions`
- `notifications/channels/light-color`
- `notifications/channels/vibrate`
- `notifications/channels/priority`
- `notifications/stories`
- `notifications/stories/new`
- `notifications/stories/important`
- `notifications/stories/show-sender`
- `notifications/stories/sound`
- `notifications/stories/add-exception`
- `notifications/stories/delete-exceptions`
- `notifications/stories/light-color`
- `notifications/stories/vibrate`
- `notifications/stories/priority`
- `notifications/reactions`
- `notifications/reactions/messages`
- `notifications/reactions/stories`
- `notifications/reactions/show-sender`
- `notifications/reactions/sound`
- `notifications/reactions/light-color`
- `notifications/reactions/vibrate`
- `notifications/reactions/priority`
- `notifications/in-app-sounds`
- `notifications/in-app-vibrate`
- `notifications/in-app-preview`
- `notifications/in-chat-sounds`
- `notifications/in-app-popup`
- `notifications/lock-screen-names`
- `notifications/include-channels`
- `notifications/include-muted-chats`
- `notifications/count-unread-messages`
- `notifications/new-contacts`
- `notifications/pinned-messages`
- `notifications/reset`
- `notifications/web`
- `power-saving`
- `power-saving/videos`
- `power-saving/gifs`
- `power-saving/stickers`
- `power-saving/emoji`
- `power-saving/effects`
- `power-saving/preload`
- `power-saving/background`
- `power-saving/call-animations`
- `power-saving/particles`
- `power-saving/transitions`
- `password`
- `phone_privacy`
- `premium`
- `privacy`
- `privacy/blocked`
- `privacy/blocked/edit`
- `privacy/blocked/block-user`
- `privacy/blocked/block-user/chats`
- `privacy/blocked/block-user/contacts`
- `privacy/active-websites`
- `privacy/active-websites/edit`
- `privacy/active-websites/disconnect-all`
- `privacy/passcode`
- `privacy/passcode/disable`
- `privacy/passcode/change`
- `privacy/passcode/auto-lock`
- `privacy/passcode/face-id`
- `privacy/passcode/fingerprint`
- `privacy/2sv`
- `privacy/2sv/change`
- `privacy/2sv/disable`
- `privacy/2sv/change-email`
- `privacy/passkey`
- `privacy/passkey/create`
- `privacy/auto-delete`
- `privacy/auto-delete/set-custom`
- `privacy/login-email`
- `privacy/phone-number`
- `privacy/phone-number/never`
- `privacy/phone-number/always`
- `privacy/last-seen`
- `privacy/last-seen/never`
- `privacy/last-seen/always`
- `privacy/last-seen/hide-read-time`
- `privacy/profile-photos`
- `privacy/profile-photos/never`
- `privacy/profile-photos/always`
- `privacy/profile-photos/set-public`
- `privacy/profile-photos/update-public`
- `privacy/profile-photos/remove-public`
- `privacy/bio`
- `privacy/bio/never`
- `privacy/bio/always`
- `privacy/gifts`
- `privacy/gifts/show-icon`
- `privacy/gifts/never`
- `privacy/gifts/always`
- `privacy/gifts/accepted-types`
- `privacy/birthday`
- `privacy/birthday/add`
- `privacy/birthday/never`
- `privacy/birthday/always`
- `privacy/saved-music`
- `privacy/saved-music/never`
- `privacy/saved-music/always`
- `privacy/forwards`
- `privacy/forwards/never`
- `privacy/forwards/always`
- `privacy/calls`
- `privacy/calls/never`
- `privacy/calls/always`
- `privacy/calls/p2p`
- `privacy/calls/p2p/never`
- `privacy/calls/p2p/always`
- `privacy/calls/ios-integration`
- `privacy/voice`
- `privacy/voice/never`
- `privacy/voice/always`
- `privacy/messages`
- `privacy/messages/set-price`
- `privacy/messages/exceptions`
- `privacy/invites`
- `privacy/invites/never`
- `privacy/invites/always`
- `privacy/self-destruct`
- `privacy/data-settings`
- `privacy/data-settings/sync-contacts`
- `privacy/data-settings/delete-synced`
- `privacy/data-settings/suggest-contacts`
- `privacy/data-settings/delete-cloud-drafts`
- `privacy/data-settings/clear-payment-info`
- `privacy/data-settings/link-previews`
- `privacy/data-settings/bot-settings`
- `privacy/data-settings/map-provider`
- `privacy/archive-and-mute`
- `privacy-policy`
- `qr-code`
- `qr-code/share`
- `qr-code/scan`
- `search`
- `send-gift`
- `send-gift/self`
- `stars`
- `stars/top-up`
- `stars/stats`
- `stars/gift`
- `stars/earn`
- `themes`
- `ton`
- `saved-messages`
- `calls`
- `calls/all`
- `calls/missed`
- `calls/edit`
- `calls/show-tab`
- `calls/start-call`
- `my-profile`
- `my-profile/posts`
- `my-profile/posts/all-stories`
- `my-profile/posts/add-album`
- `my-profile/gifts`
- `my-profile/archived-posts`

<!-- end settings paths -->

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `path` | Optional | Slash-separated identifier of the settings page or subsection to open; if absent, the top-level settings page is opened. Must be one of the values listed above. |

### My stars links

Used to bring the user to the My Stars page, containing the topup button, the Star transaction history, statistics, and [much more &raquo;](/api/stars.md).  
This is equivalent to the `stars` [settings link](#settings-links) (`tg://settings/stars`).  

`tg:` syntax:
```
tg://stars
```

### My Grams links

Used to bring the user to the TON balance page, containing the topup button, the TON transaction history and statistics.  
This is equivalent to the `ton` [settings link](#settings-links) (`tg://settings/ton`).  

`tg:` syntax:
```
tg://ton
```

### Contacts links

Used to bring the user to the contact list, optionally directly opening a specific section or action.  

`tg:` syntax:
```
tg://contacts
tg://contacts/<section>
```

If no `<section>` is specified, the contact list is simply opened.  
Otherwise, `<section>` must be one of the following values; any unrecognized value should fall back to simply opening the contact list:

| `section` | Description |
| --- | --- |
| `search` | Focus the contact search field. |
| `sort` | Open the contact sorting options. |
| `new` | Start adding a new contact. |
| `invite` | Open the "invite friends" flow. |
| `manage` | Open the contact management screen. |

### New chat links

Used to bring the user to the chat creation flow.  

`tg:` syntax:
```
tg://new
tg://new/channel
tg://new/group
```

| Link | Description |
| --- | --- |
| `tg://new` | Start creating a new private chat (i.e. pick a contact to message). |
| `tg://new/channel` | Start creating a new channel. |
| `tg://new/group` | Start creating a new group. |

### Chat list links

Used to perform actions on the main chat list.  

`tg:` syntax:
```
tg://chats/edit
tg://chats/search
tg://chats/emoji-status
```

| Link | Description |
| --- | --- |
| `tg://chats/edit` | Open the chat list in selection/edit mode, allowing the user to select chats to perform bulk actions on. |
| `tg://chats/search` | Open global search. |
| `tg://chats/emoji-status` | Open the emoji status picker (equivalent to the `emoji-status` [settings link](#settings-links)). |

### Login code link

Contains the phone number verification code to use during [user authorization&nbsp;&raquo;](/api/auth.md).  

`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&nbsp;&raquo;](/api/payments.md), generated using [payments.exportedInvoice](/constructor/payments.exportedInvoice.md).  

`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&nbsp;&raquo;](/api/payments.md). |

### Language pack links

Used to import custom language packs using [langpack.getLangPack](/method/langpack.getLangPack.md).

`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](/method/langpack.getLangPack.md) |

### Telegram Passport links

See [the Telegram Passport documentation for parameters and usage&nbsp;&raquo;](/api/passport.md#uri-format).  

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

### Phone confirmation links

Different from [login code links](#login-code-link).  
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&nbsp;&raquo;](/api/account-deletion.md).

`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&nbsp;&raquo;](/api/account-deletion.md) |

### 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&nbsp;&raquo;](/api/giveaways.md).  

This link is used to invite users to gift Premium subscription to other users, see [here&nbsp;&raquo;](#premium-giftcode-links) 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](/method/help.saveAppLog.md). |

### Premium referrer links

Used by official apps to show the [Telegram Premium](/api/premium.md) subscription page.  

`tg:` syntax:
```
tg://premium_offer?ref=<referrer>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `referrer` | Optional | Used by official apps for analytics using [help.saveAppLog](/method/help.saveAppLog.md) |

### Premium giftcode links

Used to process [Telegram Premium giftcode links](/api/giveaways.md).  

`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](/method/payments.checkGiftCode.md) to obtain further info, and eventually to [payments.applyGiftCode](/method/payments.applyGiftCode.md) to apply it. See the [giveaways](/api/giveaways.md) documentation for more info. |

### QR code login links

Used by the [QR code login flow&nbsp;&raquo;](/api/qr-login.md).

`tg:` syntax:
```
tg://login?token=<base64encodedtoken>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `server` | Required | Base64URL-encoded [QR code login token](/api/qr-login.md) |

### Main Mini App links

Used to open [Main Mini Apps&nbsp;&raquo;](/api/bots/webapps.md#main-mini-apps).  

If the specified bot **does not** have a configured Main Mini App (i.e. the [user](/constructor/user.md).`bot_has_main_app` flag will **not** be set), fall back to the behavior of [username links&nbsp;&raquo;](#public-username-links).  

The main mini app should be opened using [messages.requestMainWebView](/method/messages.requestMainWebView.md).  

`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](#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&nbsp;&raquo;](/api/bots/webapps.md#main-mini-apps) |
| `start_parameter` | Optional | If provided, should be passed to [messages.requestMainWebView](/method/messages.requestMainWebView.md).`start_param` |
| `mode` | Optional | If equal to `compact`, the [messages.requestMainWebView](/method/messages.requestMainWebView.md).`compact` flag must be set. \
If equal to `fullscreen`, the [messages.requestMainWebView](/method/messages.requestMainWebView.md).`fullscreen` flag must be set. |

### Direct mini app links

Used to share [Direct link Mini apps](/api/bots/webapps.md#direct-link-mini-apps).  

These links are different from [bot attachment menu deep links](#bot-attachment-or-side-menu-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&nbsp;&raquo;](/api/bots/webapps.md#direct-link-mini-apps).  

`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](#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](/api/bots/games.md) |
| `appname` | Required | Mini app short name, to pass to [inputBotAppShortName](/constructor/inputBotAppShortName.md).`short_name` when invoking [messages.getBotApp](/method/messages.getBotApp.md) |
| `startapp` | Optional | `start_param` to pass to [messages.requestAppWebView](/method/messages.requestAppWebView.md) |
| `mode` | Optional | If equal to `compact`, the [messages.requestAppWebView](/method/messages.requestAppWebView.md).`compact` flag must be set. \
If equal to `fullscreen`, the [messages.requestAppWebView](/method/messages.requestAppWebView.md).`fullscreen` flag must be set.|

### Bot attachment or side menu links

Used to install and open a [bot attachment or side menu&nbsp;&raquo;](/api/bots/attach.md) in a certain chat.  
For all link types, clients should first [install the associated bot attachment or side menu entry as specified here&nbsp;&raquo;](/api/bots/attach.md), 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](/method/messages.requestWebView.md) in the currently open chat, by passing it to the `peer` parameter of [messages.requestWebView](/method/messages.requestWebView.md).  

If the current chat is not supported by the [attachMenuBot](/constructor/attachMenuBot.md).`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](/api/bots/attach.md) |
| `start_parameter` | Optional | If provided, should be passed to [messages.requestWebView](/method/messages.requestWebView.md).`start_param` |

#### Open in specific chat

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

`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](/constructor/attachMenuBot.md).`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](#public-username-links) | Username of chat where to open the mini app |
| `phone_number` | Required for [phone number links](#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](/api/bots/attach.md) |
| `start_parameter` | Optional | If provided, should be passed to [messages.requestWebView](/method/messages.requestWebView.md).`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](/method/messages.requestWebView.md) in a specific chat (pass it to the `peer` parameter of [messages.requestWebView](/method/messages.requestWebView.md)).  

`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](/api/bots/attach.md) |
| `start_parameter` | Optional | If provided, should be passed to [messages.requestWebView](/method/messages.requestWebView.md).`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](/constructor/attachMenuBot.md).`peer_types` field before use. |

### Stars topup link

Used to ensure that the user has at least N [Telegram Stars](/api/stars.md) on their balance.  
If not, this link must bring the user to the [Telegram Star topup page](/api/stars.md#buying-or-gifting-stars).  

`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: <!-- start_table topup -->\
\
- `subs` - Buy **Stars** to keep your channel subscriptions.\
- `subadvance12` - Buy **Stars** to keep your subscriptions active for the next 12 months.\
\
<!-- end_table topup --> |

### Collectible gift link

Identifies a unique [collectible gift &raquo;](/api/gifts.md#collectible-gifts): use [payments.getUniqueStarGift](/method/payments.getUniqueStarGift.md) to fetch info about the collectible.  

`t.me` syntax:

```
t.me/nft/<slug>
```

`tg:` syntax:

```
tg://nft?slug=<slug>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
|`slug`| Required | Identifier of the collectible gift, to pass to [payments.getUniqueStarGift](/method/payments.getUniqueStarGift.md). |

### Gift collection links

Identifies a [star gift collection &raquo;](/api/gifts.md#gift-collections) on a peer's profile: use [payments.getSavedStarGifts](/method/payments.getSavedStarGifts.md) with the `collection_id` flag set to fetch gifts within a collection.  

`t.me` syntax:
```
t.me/<username>?collection=<collection_id>
t.me/<username>/c/<collection_id>
```

`tg:` syntax:
```
tg://resolve?domain=<username>&collection=<collection_id>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `username` | Required | Username of the peer that owns the collection. |
| `collection_id` | Required | Integer ID of the [star gift collection &raquo;](/api/gifts.md#gift-collections), from [starGiftCollection](/constructor/starGiftCollection.md).`collection_id`. |

### Auction links

Identifies a [collectible gift auction &raquo;](/api/auctions.md)

`t.me` syntax:
```
t.me/auction/<slug>
```

`tg:` syntax:
```
tg://stargift_auction?slug=<slug>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `slug` | Required | Auction slug, use it to generate a [inputStarGiftAuctionSlug](/constructor/inputStarGiftAuctionSlug.md), passed to [payments.getStarGiftAuctionState](/method/payments.getStarGiftAuctionState.md). |

### Referral links
 
Used for [Affiliate programs](/api/bots/referrals.md): when imported, all Telegram Star purchases made for digital products and subscriptions in the associated [mini app](/api/bots/webapps.md) will also transfer a certain amount of Stars to the *creator* of the link.  

See [here &raquo;](/api/bots/referrals.md) 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 &raquo;](/api/config.md#starref-start-param-prefixes): it is mandatory for the second variants of referral links, to distinguish them from [bot links](#bot-links). 

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `bot_username` | Required | Username of the bot that owns the [mini app](/api/bots/webapps.md) |
| `referrer` | Required | Referrer ID, to be passed to [contacts.resolveUsername](/method/contacts.resolveUsername.md) |

### ID links

ID links are merely an abstraction offered by the [bot API](/bots/api.md) to simplify construction of [inputMessageEntityMentionName](/constructor/inputMessageEntityMentionName.md) and [inputKeyboardButtonUserProfile](/constructor/inputKeyboardButtonUserProfile.md) 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](/bots/api.md) to simplify construction of [messageEntityCustomEmoji](/constructor/messageEntityCustomEmoji.md) constructors, and should be ignored by normal clients.  

`tg:` syntax:
```
tg://emoji?id=<id>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `id` | Required | [Custom emoji ID](/api/custom-emoji.md) |

### Timestamp links

Timestamp links are merely an abstraction offered by the [bot API](/bots/api.md) to simplify construction of [messageEntityFormattedDate](/constructor/inputMessageEntityMentionName.md), and should be ignored by normal clients.  

`tg:` syntax:
```
tg://time?unix=<unix>&format=<format>
```

Parameters:

| Name | Optional | Description |
| --- | :---: | --- |
| `unix` | Required | Positive Unix timestamp (in seconds) of the date to display. |
| `format` | Optional | Format string indicating how the date should be displayed, see [here &raquo;](/api/entities.md#date-entities) for more info. |

### Unsupported links

If a client encounters a `tg:` link type not listed on this page, [help.getDeepLinkInfo](/method/help.getDeepLinkInfo.md) 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](/method/help.getDeepLinkInfo.md) 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.