Telegram

URL Format

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

URL Fields

• Token - API Bot token (Required)
  URL part: telegram://token@telegram/

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

• 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

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

Please note the following:

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

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

• 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 containrrr/shoutrrr image in docker to run it without download/installing the shoutrrr CLI using: docker run --rm -it containrrr/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/containrrr/shoutrrrbot.

Optional parameters

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

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

See the telegram documentation for more information.

TIP

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.