Set up Telegram notifications
This guide connects the kit-notify-telegram kit to a Telegram group. After it, Tara, Ryoma, or Bandum can post alerts and review events into that group. It takes about ten minutes.
About the pictures
The figures are illustrations that show where to click. Telegram, Slack, and the Portal change their screens from time to time, so the real screen may look a little different. The names of the buttons stay the same.
Who this is for
- An administrator who installs notification kits on a server (see Notifications).
- An organization owner or admin who wants alerts in a team group.
Before you start
- A Telegram account, and a group where the alerts should go. You must be allowed to add members to that group.
- The
phcommand on your machine, to test the kit before you touch the server. - The kit version and its sha256 from the
kit-notify-telegramresource page on Tara. Use them askit-notify-telegram@<version>:<sha256>.
1. Create the bot
- In Telegram, search for
@BotFatherand open the chat with the verified account. Send/newbot. - BotFather asks for a name. Type any display name, for example
PhillipCLI Alerts. - BotFather asks for a username. It must be unique and must end in
bot, for examplephillipcli_alerts_bot. - BotFather replies with a message that contains the token, in the form
123456789:AA…. Copy it and keep it secret. Anyone with the token can send messages as your bot.
2. Add the bot to the group
- Open your group and tap the group name to open the group info.
- Choose Add Members, search for the bot's username, select it, and confirm.
- Bots have privacy mode on by default, so in a group they see only commands and mentions. Send
/start@<bot_username>in the group (replace<bot_username>with your bot's username) so the bot receives one message.
3. Find the chat ID
- Open this address in a browser, with your token in place of
<token>:https://api.telegram.org/bot<token>/getUpdates. - Find the object with your
/startmessage and readmessage.chat.id. - Copy the number, including the minus sign. A supergroup ID looks like
-100…. A basic group ID is a negative number without-100. - Clear the page from the browser history, and do not use a shared browser. The address contains the token.
If the group is upgraded
When Telegram upgrades a basic group to a supergroup, the ID changes. In getUpdates you then see migrate_to_chat_id. Update chatId to the new value.
To post to a channel instead of a group, add the bot as an administrator of the channel. A bot that is only a member cannot post there.
4. Test the kit with ph kit check
Pass the token through the PHILLIP_KIT_TOKEN variable, never as an argument. The command ph kit check takes a kit folder or name[@version], repeated --set key=value, --live, and --send <text> with optional --to.
PHILLIP_KIT_TOKEN=<bot token> ph kit check kit-notify-telegram --set chatId=<chat id> --send "test"- Without options, the command checks the contract and the required setting.
- With
--live, it callscheck(), which asks Telegram for the bot (getMe) and the group (getChat), and sends nothing. The result looks likebot @your_bot → Group name. - With
--send, it posts a real message to the group.
5. Configure the service
Tara, Ryoma, and Bandum use the same kit. Each service has its own variable prefix. The example below is for Ryoma. Take <version> and <sha256> from the Tara resource page.
RYOMA_NOTIFY_PLUGINS=kit-notify-telegram@<version>:<sha256>
RYOMA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM=<bot token>
RYOMA_NOTIFY_SETTINGS={"kit-notify-telegram":{"chatId":"<chat id>"}}| Service | Kits | Default settings | Secret |
|---|---|---|---|
| Tara | TARA_NOTIFY_PLUGINS | TARA_NOTIFY_SETTINGS | TARA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM |
| Ryoma | RYOMA_NOTIFY_PLUGINS | RYOMA_NOTIFY_SETTINGS | RYOMA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM |
| Bandum | BANDUM_NOTIFY_PLUGINS | BANDUM_NOTIFY_SETTINGS | BANDUM_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM |
Tara also needs TARA_NOTIFY_TOKEN, a read-only Tara token that downloads the kit package. Restart the service after you change the variables. For the other variables, see Notifications.
6. Choose the channel for each organization
Tara can send each organization's events to its own group. The secret stays one per kit on the server, and each organization sets its own chatId.
- Sign in to the Portal as an owner or admin of the organization. Open the account menu, then Admin, then Notifications, then add a channel.
- Choose the Organization and the Plugin
kit-notify-telegram. - In Organization-specific settings, enter one
name=valueper line, for examplechatId=-1001234567890. - Choose the events to receive, then save.
- In the row's actions menu, choose Send test. The message should arrive in the group within seconds.
You can do the same from the command line:
ph tara notify set <org> kit-notify-telegram --set chatId=<chat id> --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-telegramTroubleshooting
| Error text | Cause | Fix |
|---|---|---|
the Telegram bot token is missing | The secret variable is empty or has the wrong name | Set <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM and restart |
settings.chatId (ID of the chat group that receives notifications) is missing | No chatId in the settings | Add chatId in the service settings or in the organization's channel |
Telegram rejected the bot token: … | The token is wrong, has an extra space, or is no longer valid | Copy the token again from the BotFather message |
chat group <id> not found: … (was the bot added to the group?) | The ID is wrong, the bot is not in the group, or the group was upgraded to a supergroup | Add the bot, read the ID again with getUpdates, check for migrate_to_chat_id |
could not reach Telegram | The server cannot reach api.telegram.org | Open the network route, or set apiUrl to your internal proxy |
Telegram is temporarily failing (HTTP 429) or (HTTP 5xx) | Telegram limits the rate or is down | Wait. Tara retries up to 8 times |
Telegram returned HTTP …: … | Another refusal, for example the bot was removed from the group or is not an administrator of a channel | Read the text after the colon, and fix the bot's rights |
Limits
- One destination per configuration: a single chat ID.
- A message is cut at 4096 characters. The subject goes on the first line.
- The kit ignores the
toaddress because Telegram has no per-person recipients here. - Messages carry metadata and links only, never the content of work.