rani/matterbridge.git

Viewing file on branch master

1	# Telegram
2
3	- Status: Working
4	- Maintainers: @selfhoster1312
5	- Features: ???
6
7	## Configuration
8
9	> [!TIP]
10	> For detailed information about telegram settings, see [settings.md](settings.md)
11
12	Basic configuration example:
13
14	```toml
15	[telegram.mytelegram]
16	Token="Yourtokenhere"
17	RemoteNickFormat="({PROTOCOL}) {NICK} "
18	MessageFormat="HTMLNick"
19	```
20
21	## FAQ
22
23	### How to get a token for my bot?
24
25	See [account.md](account.md)
26
27	### How to retrieve my Telegram chat ID?
28
29	> [!WARNING]
30	> So-called topics in "forums" have a different address format! See
31	> dedicated FAQ answer about this.
32
33	To retrive your ChatId, you can:
34
35	- post `/chatId` in the Telegram chat, and the bot will reply the ID
36	- from a desktop computer, navigate to your channel, and copy the numbers at the end of the URL
37	- look for `Channel:"-XXXXXXX"` in `config.Message` in matterbridge debug log (where `-XXXXXXX` is your ChatId)
38
39	### Does matterbridge support Telegram channels?
40
41	"Channels" in telegram are read-only chatrooms where only admin can post. Adding a bot to a channel requires giving it administrator rights. If you feel comfortable doing that, please report if it works.
42
43	### Why can't I invite my bot into my channel?
44
45	As of September 2025, the Telegram web interface is bugged and will silently error when trying to invite a bot into a (read-only) channel as an ordinary member.
46
47	Maybe adding it as an administrator directly works. Adding it from the mobile application works (it will prompt to make the bot administrator instead).
48
49	### Limitations
50
51	- The Telegram API does not report any changes when messages are deleted so Matterbridge is unable to remove any bridged messages after they've been sent (This will render many common spam solutions useless). Use regexp with the `IgnoreMessages=` field to remove any common spam messages. # Telegram
52
53	### Matterbridge is not relaying messages from Telegram
54
55	See
56	* https://core.telegram.org/bots#privacy-mode
57	* https://github.com/yagop/node-telegram-bot-api/issues/174#issuecomment-244632667
58
59	If your bot is not getting messages:
60
61	Disable privacy mode with @Botfather.
62
63	* Go to [BotFather](https://t.me/botfather) send /setprivacy.
64	* Select the username of the bot.
65	* Select Disable.
66	* Kick bot from chat if it's already in it.
67	* Invite bot to chat.
68
69	The order is important.
70
71	### Matterbridge is not relay messages from other bots
72
73	> Bots talking to each other could potentially get stuck in unwelcome loops. To avoid this, we decided that bots will not be able to see messages from other bots regardless of mode.
74
75	https://core.telegram.org/bots/faq#why-doesn-39t-my-bot-see-messages-from-other-bots
76
77	### Matterbridge is not relaying images/stickers/files from Telegram
78
79	Because images/stickers/files are from non-public url's, you'll need to setup a [mediaserver](Mediaserver-setup-(advanced))
80
81	### Matterbridge is not relaying messages to Telegram
82
83	Did you enable `MessageFormat="HTML"` in your config?
84	You could be sending invalid HTML. Set it to `MessageFormat=""`
85
86	More info in https://github.com/42wim/matterbridge/blob/master/matterbridge.toml.sample#L836-L838
87
88	### Matterbridge is not deleting messages from Telegram to other bridges
89
90	Telegram doesn't has "deleted messages" metadata, so we don't know which messages are deleted.
91
92	### Users are shown as "unknown user"
93
94	Telegram channels will always return unknown users. Telegram groups will show usernames if possible
95
96	### How to use MediaConvertTgs with lottie?
97
98	This requires the external dependency `lottie`, which can be installed like this:
99	`pip install lottie cairosvg`
100	https://github.com/42wim/matterbridge/issues/874
101
102	Note that if you insist on using an ancient Python version like 3.5, the pip installation is slightly more complicated. Matterbridge expects `lottie_convert.py` to be in your `$PATH`; if that's not already the case, try putting this into your `~/.profile`:
103	```
104	PATH=$HOME/.local/bin:$PATH
105	export PATH
106	```
107
108	If you encounter bugs with this, try to extract the Telegram sticker file and run lottie on it like this:
109	`lottie_convert.py --input-format lottie file_1234_tgs.webp myoutput.webp`
110	This might give you additional information about what's going on.
111
112	### How to join a topic in a Telegram forum?
113
114	What telegram calls a forum is a chatroom which has been split into several sub-rooms, much like a so-called Discord server or a Matrix space.
115
116	Each topic then has a `message_thread_id` which is visible from the web interface after the usual ChatId. For example, you may see in your URL `/-XXXXXX/Y` where `-XXXXXX` is your ChatId and `Y` is the topic ID.
117
118	Specifically when using topics (not normal groups), you need to add `100` between the `-` and the usual ChatId. For example, `-XXXXXX` becomes `-100XXXXXX`. Then you need to add the topic ID, like so: `-100XXXXXXX/Y`.
119
120	> [!WARNING]
121	> The first topic created is an exception and should not have `/Y` added to the Channel configuration in your gateway. For this topic only, use `-100XXXXXX`.
122
123	This `100` magic number is to our knowledge not documented in the Telegram Bot API docs, but [has been observed in the wild](https://stackoverflow.com/questions/32423837/telegram-bot-how-to-get-a-group-chat-id) and has cost one matterbridge contributor more than their fair share of mental health points.
124