Telegram Notifications

Send LIVCK alerts, incidents, maintenance notifications, and announcements directly to Telegram using a Telegram bot.

Overview

Telegram notifications allow team members to receive real-time updates via Telegram. Once a Telegram bot is configured at the system level, each team member can configure their Telegram User ID to receive personal notifications.

How It Works

LIVCK uses a Telegram bot to send notifications. The bot is configured once at the system level, and each team member adds their Telegram User ID to their profile to receive notifications.

Team members can receive notifications via:

  • Direct messages from the bot (using their Telegram User ID)
  • Group chats (using the group's chat ID)

System Configuration

Telegram notifications require a bot token to be configured in your LIVCK environment.

Step 1: Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Start a chat with BotFather
  3. Send the command /newbot
  4. Follow the prompts to create your bot:
    • Choose a display name (e.g., "LIVCK Status Bot")
    • Choose a unique username ending in "bot" (e.g., "livck_status_bot")
  5. BotFather will provide you with a bot token (looks like: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
  6. Copy this token

Step 2: Configure Environment Variable

Add the bot token to your .env file:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Step 3: Restart Application

Restart LIVCK to apply the configuration:

docker compose restart app

User Configuration

Once the bot token is configured, each team member needs to get their Telegram User ID and add it to their profile.

Step 1: Get Your Telegram User ID

Option 1: Using a Bot

  1. Open Telegram and search for @userinfobot or @getmyid_bot
  2. Start a chat with the bot
  3. Send any message
  4. The bot will reply with your User ID (a number like 123456789)

Option 2: From Your Own Bot

  1. Start a chat with your LIVCK bot (the one created with BotFather)
  2. Send any message to the bot (e.g., /start or "Hello")
  3. Check the LIVCK logs to find your User ID:
docker compose logs app | grep -i telegram

Step 2: Add User ID to Your Profile

  1. Log in to LIVCK
  2. Navigate to /user/profile
  3. Find the Telegram User ID field
  4. Enter your Telegram User ID (numbers only)
  5. Click Save

Step 3: Test the Configuration

After saving your User ID:

  1. Click the Test all configured Notification-Channels button in your profile
  2. Check Telegram for the test notification from your bot

If you receive the test message, your Telegram notifications are working correctly.

Group Notifications

You can also send notifications to Telegram groups by using the group's chat ID instead of a personal User ID.

Getting a Group Chat ID

  1. Add your LIVCK bot to the Telegram group
  2. Send a message in the group (e.g., "Hello")
  3. Visit this URL in your browser (replace YOUR_BOT_TOKEN with your actual bot token):
https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
  1. Look for the "chat":{"id": field in the response (will be a negative number like -123456789)
  2. Copy this chat ID

Using Group Chat ID

  1. Log in to LIVCK
  2. Navigate to /user/profile
  3. Enter the group chat ID in the Telegram User ID field (including the minus sign if present)
  4. Click Save
  5. Test the configuration

Tip: Group chat IDs are typically negative numbers, while personal User IDs are positive numbers.

Notification Triggers

Members receive Telegram notifications for:

  • New Alerts - When new announcements, incidents, or maintenance windows are created (if "Notify Subscribers" is enabled)
  • Alert Updates - When alerts are updated with new information
  • Status Changes - When incident or maintenance status changes
  • Alert Resolution - When incidents are resolved or maintenance is completed

Telegram Message Format

Telegram notifications include:

  • Alert Type - Announcement, Incident, or Maintenance
  • Alert Title - The name of the alert
  • Status - Current status (for incidents and maintenance)
  • Message - Alert description (formatted as plain text)
  • Timestamp - When the alert was created or updated
  • Link - Direct link to view the alert on your status page

Troubleshooting

Telegram Notifications Not Arriving

Check Bot Token:

  • Verify TELEGRAM_BOT_TOKEN is set in .env
  • Ensure the token is correct (no extra spaces)
  • Check if the bot is still active with BotFather
  • Restart LIVCK after changing the token: docker-compose restart app

Check User ID:

  • Verify your Telegram User ID is correct
  • Ensure it's entered as numbers only (no letters or special characters)
  • For groups, ensure the chat ID includes the minus sign if present
  • Test with a bot like @userinfobot to confirm your User ID

Check Bot Permissions:

  • Ensure you've started a chat with the bot (send any message to it first)
  • For groups, ensure the bot is a member of the group
  • Check if the bot has permission to send messages in the group

Check Logs:

docker compose logs app | grep -i telegram

Bot Not Responding

Cause: You haven't initiated a conversation with the bot.

Solution:

  1. Open Telegram and search for your bot by username
  2. Start a chat with the bot
  3. Send any message (e.g., /start)
  4. Now the bot can send you messages

Invalid Bot Token Error

Common Issues:

  • Token contains extra spaces or line breaks
  • Token is incomplete
  • Bot was deleted or revoked

Solution:

  • Recreate the bot with BotFather
  • Copy the new token carefully
  • Update .env with the new token
  • Restart LIVCK:
    docker compose restart app

Group Notifications Not Working

Check:

  1. Is the bot added to the group?
  2. Does the bot have permission to send messages?
  3. Is the chat ID correct (including minus sign)?
  4. Did you use the chat ID, not the group invite link?

Solution:

  • Add the bot to the group as a member
  • Ensure the bot has "Send Messages" permission
  • Get the correct chat ID using the /getUpdates API endpoint
  • Use the numeric chat ID, not the @username

Messages Not Reaching Group Members

Cause: Group members don't receive notifications automatically. The bot sends messages to the group, but individual members don't get personal notifications unless they configure their own User ID.

Solution:

  • To notify individual members, they each need to add their personal Telegram User ID to their LIVCK profile
  • To notify a group, use the group chat ID in one member's profile

Best Practices

Bot Configuration

Bot Name and Username

  • Choose a clear, recognizable name like "LIVCK Status Bot"
  • Use a professional username
  • Add a profile picture to make it easily identifiable

Bot Description

  • Set a description using BotFather's /setdescription command
  • Explain what the bot does: "LIVCK status page notifications"

Security

Protect Bot Token

  • Never share your bot token publicly
  • Don't commit the token to version control
  • Regenerate the token if it's exposed (via BotFather)

Group Access

  • Only add the bot to relevant groups
  • Remove the bot from groups when no longer needed
  • Use private groups for sensitive alerts

Notification Management

Avoid Spam

  • Don't send every minor update via Telegram
  • Use Telegram for critical alerts only
  • Consider using email for routine notifications

Test Regularly

  • Test notifications after configuration changes
  • Verify messages arrive promptly
  • Check message formatting and content

Use Cases

Personal Notifications

Each team member configures their own Telegram User ID to receive direct messages from the bot.

Team Group Notifications

Set up a Telegram group for your team, add the bot, and use the group chat ID in one member's profile to send notifications to the entire group.

Multiple Groups

Different team members can configure different group chat IDs:

  • Engineering team → Engineering group chat ID
  • Operations team → Operations group chat ID
  • Leadership → Leadership group chat ID

Hybrid Setup

Combine personal and group notifications:

  • On-call engineer receives personal DMs (personal User ID)
  • Entire team sees messages in group (group chat ID in another profile)

Advanced Configuration

Multiple Bots

If you need separate bots for different purposes, you'll need to set up multiple LIVCK instances since only one TELEGRAM_BOT_TOKEN can be configured per instance.

Bot Commands

Consider adding custom commands to your bot using BotFather:

  • /start - Welcome message
  • /status - Current status page link
  • /help - Help information

Use BotFather's /setcommands to configure these.

Additional Resources