Debian Codegraph @

docs/services/chat/telegram/index.md

raw
1 # Telegram
2
3 ## URL Format
4
5 !!! info ""
6 telegram://__`token`__@telegram?chats=__`channel-1`__[,__`chat-id-1`__,...]
7
8 --8<-- "docs/services/chat/telegram/config.md"
9
10 ## Getting a token for Telegram
11
12 Talk to [the botfather](https://core.telegram.org/bots#6-botfather).
13
14 ## Identifying the target chats/channels
15
16 The `chats` param consists of one or more `Chat ID`s or `channel name`s.
17
18 ### Public Channels
19 The channel names can be retrieved in the telegram client in the `Channel info` section for public channels.
20 Replace the `t.me/` prefix from the link with a `@`.
21
22 !!! note
23 Channels names need to be prefixed by `@` to identify them as such.
24
25 !!! note
26 If your channel only has an invite link (starting with `t.me/+`), you have to use it's Chat ID (see below)
27
28 !!! note
29 A `message_thread_id` param ([reference](https://core.telegram.org/bots/api#sendmessage)) can be added, with the format of `$chat_id:$message_thread_id`. [More info](https://stackoverflow.com/questions/74773675/how-to-get-topic-id-for-telegram-group-chat/75178418#75178418) on how to obtain the `message_thread_id`.
30
31 ### Chats
32 Private channels, Group chats and private chats are identified by `Chat ID`s. Unfortunatly, they are generally not visible in the
33 telegram clients.
34 The easiest way to retrieve them is by using the `shoutrrr generate telegram` command which will guide you through
35 creating a URL with your target chats.
36
37 !!! tip
38 You can use the `nickfedor/shoutrrr` image in docker to run it without download/installing the `shoutrrr` CLI using:
39 ```
40 docker run --rm -it nickfedor/shoutrrr generate telegram
41 ```
42
43 ### Asking @shoutrrrbot
44 Another way of retrieving the Chat IDs, is by forwarding a message from the target chat to the [@shoutrrrbot](https://t.me/shoutrrrbot).
45 It will reply with the Chat ID for the chat where the forwarded message was originally posted.
46 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.
47 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.
48
49 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](https://github.com/nicholas-fedor/shoutrrrbot).
50
51
52
53 ## Optional parameters
54
55 You can optionally specify the __`notification`__, __`parseMode`__ and __`preview`__ parameters in the URL:
56
57 !!! info ""
58 <pre>telegram://__`token`__@__`telegram`__/?channels=__`channel`__&notification=no&preview=false&parseMode=html</pre>
59
60 See [the telegram documentation](https://core.telegram.org/bots/api#sendmessage) for more information.
61
62 !!! note
63 `preview` and `notification` are inverted in regards to their API counterparts (`disable_web_page_preview` and `disable_notification`)
64
65 ### Parse Mode and Title
66
67 If a parse mode is specified, the message needs to be escaped as per the corresponding sections in
68 [Formatting options](https://core.telegram.org/bots/api#formatting-options).
69
70 When a title has been specified, it will be prepended to the message, but this is only supported for
71 the `HTML` parse mode. Note that, if no parse mode is specified, the message will be escaped and sent using `HTML`.
72
73 Since the markdown modes are really hard to escape correctly, it's recommended to stick to `HTML` parse mode.