Skip to content

Telegram

URL Format

telegram://token@telegram?chats=channel-1[,chat-id-1,...]

URL Fields

  • Token (Required)
    URL part: telegram://token/

Query/Param Props

Props can be either supplied using the params argument or through the URL using ?key=value&key=value etc.

  • chats - Chat IDs or Channel names (using @channel-name) (Required) Aliases: channels

  • apiurl - Bot API server base URL (default: https://api.telegram.org) Default: empty

  • notification - If disabled, sends Message silently Default: ✔ Yes

  • parsemode - How the text Message should be parsed Default: None Possible values: None, Markdown, HTML, MarkdownV2

  • preview - If disabled, no web page preview will be displayed for URLs Default: ✔ Yes

  • skiptlsverify - Skip TLS certificate verification Default: ❌ No

  • title - Notification title, optionally set by the sender Default: empty

Getting a token for Telegram

Talk to the botfather.

Identifying the target chats/channels

The chats param consists of one or more Chat IDs or channel names.

Public Channels

The channel names can be retrieved in the telegram client in the Channel info section for public channels. Replace the t.me/ prefix from the link with a @.

Note

Channels names need to be prefixed by @ to identify them as such.

Note

If your channel only has an invite link (starting with t.me/+), you have to use it's Chat ID (see below)

Note

A message_thread_id param (reference) can be added, with the format of $chat_id:$message_thread_id. More info on how to obtain the message_thread_id.

Chats

Private channels, Group chats and private chats are identified by Chat IDs. Unfortunatly, they are generally not visible in the telegram clients. The easiest way to retrieve them is by using the shoutrrr generate telegram command which will guide you through creating a URL with your target chats.

Tip

You can use the nickfedor/shoutrrr image in docker to run it without download/installing the shoutrrr CLI using:

docker run --rm -it nickfedor/shoutrrr generate telegram

Asking @shoutrrrbot

Another way of retrieving the Chat IDs, is by forwarding a message from the target chat to the @shoutrrrbot. It will reply with the Chat ID for the chat where the forwarded message was originally posted. Note that it will not work correctly for Group chats, as those messages are just seen as being posted by a user, not in a specific chat. Instead you can use the second method, which is to invite the @shoutrrrbot into your group chat and address a message to it (start the message with @shoutrrrbot). You can then safely kick the bot from the group.

The bot should be constantly online, unless it's usage exceeds the free tier on GCP. It's source is available at github.com/nicholas-fedor/shoutrrrbot.

Sending to several chats

Each chat in the chats param gets its own request, in order. A chat that Telegram rejects does not stop the chats after it, and the error lists every chat that failed.

A message can hold up to 4096 characters, counted as UTF-16 code units the way Telegram measures text. Most characters count as one unit, and an emoji or another character outside the Basic Multilingual Plane counts as two. A title sent on its own line, as the HTML parse mode or no parse mode sends it, counts toward the limit too. A longer message fails before any request is sent.

Optional parameters

You can optionally specify the notification, parseMode and preview parameters in the URL:

telegram://token@telegram/?channels=channel&notification=no&preview=false&parseMode=html

See the telegram documentation for more information.

Note

preview and notification are inverted in regards to their API counterparts (disable_web_page_preview and disable_notification)

Parse Mode and Title

If a parse mode is specified, the message needs to be escaped as per the corresponding sections in Formatting options.

When a title has been specified, it will be prepended to the message, but this is only supported for the HTML parse mode. Note that, if no parse mode is specified, the message will be escaped and sent using HTML.

Since the markdown modes are really hard to escape correctly, it's recommended to stick to HTML parse mode.

Bot API server

By default, Shoutrrr sends requests to Telegram's own Bot API server at https://api.telegram.org. The apiurl param points it at another server, such as a self-hosted Bot API server or a proxy where Telegram's domains are blocked. Requests go to the given base URL followed by /bot<token>/<method>, so a proxy can serve the API under a path.

Self-hosted Bot API server

telegram://token@telegram?chats=@channel&apiurl=http://localhost:8081

The URL must use http or https and have a host. It cannot hold userinfo, a query, or a fragment. The self-hosted server accepts only plain HTTP, so use https only behind a TLS proxy.

Every request carries the bot token in its path, so an http API URL sends the token unencrypted. Shoutrrr logs a warning the first time a send goes out that way.

Set skiptlsverify=yes when the TLS proxy's certificate cannot be verified, such as a self-signed one. The connection stays encrypted, but Shoutrrr does not check which server it talks to. The option can also be passed as a send param, which applies to that send only. A custom HTTP client set through SetHTTPClient keeps its own TLS settings, so skiptlsverify does not change it. Shoutrrr logs a warning the first time a send skips certificate verification through its own client.

To generate a URL for another server, pass the params to the generator:

shoutrrr generate telegram -g telegram -p apiurl=http://localhost:8081
shoutrrr generate telegram -g telegram -p apiurl=https://tg.example.com -p skiptlsverify=yes