Skip to content

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 ph command on your machine, to test the kit before you touch the server.
  • The kit version and its sha256 from the kit-notify-telegram resource page on Tara. Use them as kit-notify-telegram@<version>:<sha256>.

1. Create the bot ​

  1. In Telegram, search for @BotFather and open the chat with the verified account. Send /newbot.
  2. BotFather asks for a name. Type any display name, for example PhillipCLI Alerts.
  3. BotFather asks for a username. It must be unique and must end in bot, for example phillipcli_alerts_bot.
  4. 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.
Illustration, the real screen may differ slightly. After /newbot, a name and a username ending in bot, BotFather replies with the token (1).

2. Add the bot to the group ​

  1. Open your group and tap the group name to open the group info.
  2. Choose Add Members, search for the bot's username, select it, and confirm.
  3. 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.
Choose Add Members in the group info (1), pick the bot (2), then send /start@<bot username> in the group (3).

3. Find the chat ID ​

  1. Open this address in a browser, with your token in place of <token>: https://api.telegram.org/bot<token>/getUpdates.
  2. Find the object with your /start message and read message.chat.id.
  3. Copy the number, including the minus sign. A supergroup ID looks like -100…. A basic group ID is a negative number without -100.
  4. Clear the page from the browser history, and do not use a shared browser. The address contains the token.
In the getUpdates answer, the id under message.chat is the chatId (1), for example -1001234567890.

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.

bash
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 calls check(), which asks Telegram for the bot (getMe) and the group (getChat), and sends nothing. The result looks like bot @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.

bash
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>"}}
ServiceKitsDefault settingsSecret
TaraTARA_NOTIFY_PLUGINSTARA_NOTIFY_SETTINGSTARA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM
RyomaRYOMA_NOTIFY_PLUGINSRYOMA_NOTIFY_SETTINGSRYOMA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM
BandumBANDUM_NOTIFY_PLUGINSBANDUM_NOTIFY_SETTINGSBANDUM_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.

  1. 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.
  2. Choose the Organization and the Plugin kit-notify-telegram.
  3. In Organization-specific settings, enter one name=value per line, for example chatId=-1001234567890.
  4. Choose the events to receive, then save.
  5. In the row's actions menu, choose Send test. The message should arrive in the group within seconds.
Enter chatId=… in Organization-specific settings (1), choose the events (2), then choose Save (3). Send a test from the channel row's actions menu.

You can do the same from the command line:

bash
ph tara notify set <org> kit-notify-telegram --set chatId=<chat id> --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-telegram

Troubleshooting ​

Error textCauseFix
the Telegram bot token is missingThe secret variable is empty or has the wrong nameSet <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM and restart
settings.chatId (ID of the chat group that receives notifications) is missingNo chatId in the settingsAdd 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 validCopy 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 supergroupAdd the bot, read the ID again with getUpdates, check for migrate_to_chat_id
could not reach TelegramThe server cannot reach api.telegram.orgOpen 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 downWait. 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 channelRead 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 to address because Telegram has no per-person recipients here.
  • Messages carry metadata and links only, never the content of work.

Further reading ​