Skip to content

Commit 4d87b7a

Browse files
MicLiegMicLieg
authored
feat: add documentation for telegram topic & silent notification support (#102)
1 parent dc71a2c commit 4d87b7a

File tree

1 file changed

+141
-103
lines changed

1 file changed

+141
-103
lines changed

‎alerts/telegram.md‎

Lines changed: 141 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,105 +1,143 @@
11
# Telegram
22

3-
[Telegram](https://telegram.org) is an instant messenger app that allows other applications to send messages via a webhook. This functionality is used to allow users to receive alerts about LinuxGSM.
4-
5-
## Setup a Telegram Bot
6-
7-
To enable Telegram alerts you need to create your own Telegram Bot.
8-
9-
1. To do this you will need to speak to @BotFather by visiting [here](https://telegram.me/BotFather).
10-
2. Click start to begin the chat.
11-
12-
![BotFather Chat](../.gitbook/assets/botfather\_chat.png)
13-
14-
1. Type `/newbot` and follow the instructions to create a bot.
15-
16-
![new Bot](../.gitbook/assets/botfather\_new\_bot.png)
17-
18-
1. Once complete an API token will be given. Enter the token to the [LinuxGSM config](../configuration/linuxgsm-config.md).
19-
20-
```
21-
#Telegram Alerts | https://github.com/GameServerManagers/LinuxGSM/wiki/Telegram
22-
23-
telegramalert="on"
24-
telegramtoken="401319987:AAGmgLWzYDprqkMHBjCT9qtzIRWCzqgoTLw"
25-
telegramchatid=""
26-
```
27-
28-
## Telegram Group
29-
30-
Use this step If you want to send alerts to a group. If not skip to [Retrieve the Chat ](telegram.md#retrieve-the-chat-id)ID.
31-
32-
### Setup a New Group
33-
34-
1. Select `New Group`
35-
2. Give your group a name
36-
3. Select the Bot you just created by typing `@ExampleBot`.
37-
38-
The bot will now be added to the group.
39-
40-
## Use an Existing group
41-
42-
If you are using an existing group, invite the bot to the group.
43-
44-
```
45-
View group info -> Add Members.
46-
```
47-
48-
## Retrieve the Chat ID
49-
50-
The chat id is used to identify where the alert is being sent. Each user and group has its own ID.
51-
52-
To obtain the chat id a message must be received by the bot. This will allow it to pick up the chat id. You can now search for your bot in telegram and sent it the message `LINUXGSM`.
53-
54-
* users: send the message `LINUXGSM` directly to the bot
55-
* groups: send the message `LINUXGSM` to the group
56-
57-
To retrieve the chat id visit the following url, replacing the `XXXXX` with your bot token from earlier.
58-
59-
```
60-
https://api.telegram.org/botXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/getUpdates
61-
```
62-
63-
Look for text `LINUXGSM` in the message and find the `chat id` part of that message.
64-
65-
> note: A group number includes a dash in the chat id e.g `-191537238`
66-
67-
```
68-
The number given is the chat id
69-
70-
> note: A group number includes a dash in the chat id e.g `-191537238`
71-
72-
Add the chat id to the [LinuxGSM config](../configuration/linuxgsm-config.md).
73-
```
74-
75-
The number given is the chat id
76-
77-
{% hint style="warning" %}
78-
A group number might include a dash in the chat id e.g `-191537238`
79-
{% endhint %}
80-
81-
```
82-
"chat":{"id":-191537238,
83-
```
84-
85-
Add the chat id to the [LinuxGSM config](https://app.gitbook.com/s/-LJf1\_IiU2L1vVxT7iNe/configuration/linuxgsm-config.md).
86-
87-
```
88-
## Telegram Alerts | https://github.com/GameServerManagers/LinuxGSM/wiki/Telegram
89-
90-
telegramalert="on"
91-
telegramtoken="401319987:AAGmgLWzYDprqkMHBjCT9qtzIRWCzqgoTLw"
92-
telegramchatid="-191537238"
93-
```
94-
95-
### Send Test Alert
96-
97-
Finally, test that everything correctly works by sending a test alert. You will now receive a message from the bot directly or to a chosen group.
98-
99-
```
100-
./gameserver test-alert
101-
```
102-
103-
## Custom cURL String
104-
105-
You can add a custom cURL string eg proxy (useful in Russia) in "curlcustomstring"
3+
[Telegram](https://telegram.org) is an instant messaging app that provides a powerful API that enables applications to send messages through bots. LinuxGSM leverages the [Telegram Bot API](https://core.telegram.org/bots/api) to dispatch alerts to users, enhancing monitoring and management of gaming servers.
4+
5+
## Creating a Telegram Bot
6+
7+
1. **Initiate Bot Creation**: Chat with [@BotFather](https://telegram.me/BotFather) on Telegram to start creating your bot. Begin the conversation by clicking "Start".
8+
9+
2. **Register Your Bot**: Send `/newbot` to @BotFather and follow the provided instructions to set up your bot. Upon completion, you will receive an API token.
10+
11+
![BotFather Chat](../.gitbook/assets/botfather_chat.png)
12+
13+
![New Bot](../.gitbook/assets/botfather_new_bot.png)
14+
15+
3. **Configure LinuxGSM**: Fill in the API token into your [LinuxGSM config](../configuration/linuxgsm-config.md) as follows:
16+
17+
```bash
18+
# Telegram Alerts | https://docs.linuxgsm.com/alerts/telegram
19+
telegramapi="api.telegram.org"
20+
telegramalert="on" # Enable alerts by changing "off" to "on"
21+
telegramtoken="XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" # Replace with your bot token
22+
telegramchatid=""
23+
telegramthreadid=""
24+
telegramsilentnotification="false" # Set to "true" to disable notification sounds and send alerts silently
25+
curlcustomstring="" # Optional: For proxies, etc.
26+
```
27+
28+
## Configuring Alerts for a Group
29+
30+
### New Group Creation
31+
32+
1. Select `New Group` within Telegram.
33+
2. Name your group.
34+
3. Add your bot by searching its `@Username`.
35+
36+
### Adding to an Existing Group
37+
38+
1. Open group info.
39+
2. Choose to add members.
40+
3. Search and select your bot by its `@Username`.
41+
42+
## Retrieving Your Telegram Chat ID
43+
44+
1. **Activate Your Bot**: Interact with your bot in Telegram.
45+
2. **Form the getUpdates URL**: Replace the placeholder with your bot's token in `https://api.telegram.org/botXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/getUpdates`.
46+
3. **Visit the URL**: Use a web browser to access the URL.
47+
4. **Locate the Chat ID**: In the JSON response, find the `id` field under the `chat` object.
48+
49+
```json
50+
"chat": {
51+
"id": 123456789,
52+
"first_name": "Your Name",
53+
"username": "YourUsername",
54+
"type": "private"
55+
}
56+
```
57+
58+
Note: The Chat ID for private chats is a positive number and for a group, it's a negative number.
59+
60+
5. **Update LinuxGSM Config**: Place your Chat ID in the [LinuxGSM config](../configuration/linuxgsm-config.md) file.
61+
62+
```bash
63+
# Telegram Alerts | https://docs.linuxgsm.com/alerts/telegram
64+
telegramapi="api.telegram.org"
65+
telegramalert="on"
66+
telegramtoken="XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
67+
telegramchatid="123456789" # Fill in your chat ID
68+
telegramthreadid=""
69+
telegramsilentnotification="false"
70+
curlcustomstring=""
71+
```
72+
73+
## Enabling Telegram Topics (Threads)
74+
75+
1. Verify that Topics are enabled for your group by checking the group's settings.
76+
2. If you don't already have a topic created. Create a new Topic by clicking the three dots in the top right corner of the group chat and selecting `New Topic`.
77+
3. Send a message in the Topic you want to use.
78+
4. Repeat [Retrieving Your Telegram Chat ID](#retrieving-your-telegram-chat-id) to retrieve the thread ID by looking for the `message_thread_id` field in the `message` object.
79+
80+
```json
81+
{
82+
"update_id": 123456,
83+
"message": {
84+
"message_id": 123,
85+
"from": {
86+
"id": 12345,
87+
"is_bot": false,
88+
"first_name": "Sender",
89+
"username": "SenderUsername",
90+
"language_code": "en"
91+
},
92+
"chat": {
93+
"id": -123456789,
94+
"first_name": "Your Name",
95+
"username": "YourUsername",
96+
"type": "supergroup"
97+
},
98+
"date": 1709691014,
99+
"message_thread_id": 11, // Use this number as your telegramthreadid
100+
"forum_topic_created": {
101+
"name": "LinuxGSM",
102+
"icon_color": 12345
103+
},
104+
"is_topic_message": true
105+
}
106+
}
107+
```
108+
109+
5. Update the `telegramthreadid` field in the [LinuxGSM config](../configuration/linuxgsm-config.md) with the thread ID.
110+
111+
```bash
112+
# Telegram Alerts | https://docs.linuxgsm.com/alerts/telegram
113+
telegramapi="api.telegram.org"
114+
telegramalert="on"
115+
telegramtoken="XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
116+
telegramchatid="123456789"
117+
telegramthreadid="5" # Fill in your thread ID
118+
telegramsilentnotification="false"
119+
curlcustomstring=""
120+
```
121+
122+
## Testing the Configuration
123+
124+
Execute a test alert with `./gameserver test-alert` to verify the setup.
125+
126+
If you receive an alert on Telegram in the right place (group or private chat), the configuration is correct.
127+
128+
## Advanced Configuration: Custom cURL String
129+
130+
For specific needs such as bypassing network restrictions, you can specify custom cURL arguments in the configuration.
131+
132+
```bash
133+
# Telegram Alerts | https://docs.linuxgsm.com/alerts/telegram
134+
# You can add a custom cURL string eg proxy (useful in Russia) in "curlcustomstring".
135+
# For example "--socks5 ipaddr:port" for socks5 proxy see more in "curl --help all".
136+
telegramapi="api.telegram.org"
137+
telegramalert="on"
138+
telegramtoken="XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
139+
telegramchatid="123456789"
140+
telegramthreadid="5"
141+
telegramsilentnotification="false"
142+
curlcustomstring="--socks5 ipaddr:port" # Fill in your custom cURL string
143+
```

0 commit comments

Comments
 (0)