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
- Open Telegram and search for @BotFather
- Start a chat with BotFather
- Send the command
/newbot
- 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")
- BotFather will provide you with a bot token (looks like:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz
) - 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
- Open Telegram and search for @userinfobot or @getmyid_bot
- Start a chat with the bot
- Send any message
- The bot will reply with your User ID (a number like
123456789
)
Option 2: From Your Own Bot
- Start a chat with your LIVCK bot (the one created with BotFather)
- Send any message to the bot (e.g.,
/start
or "Hello") - Check the LIVCK logs to find your User ID:
docker compose logs app | grep -i telegram
Step 2: Add User ID to Your Profile
- Log in to LIVCK
- Navigate to
/user/profile
- Find the Telegram User ID field
- Enter your Telegram User ID (numbers only)
- Click Save
Step 3: Test the Configuration
After saving your User ID:
- Click the Test all configured Notification-Channels button in your profile
- 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
- Add your LIVCK bot to the Telegram group
- Send a message in the group (e.g., "Hello")
- Visit this URL in your browser (replace
YOUR_BOT_TOKEN
with your actual bot token):
https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
- Look for the
"chat":{"id":
field in the response (will be a negative number like-123456789
) - Copy this chat ID
Using Group Chat ID
- Log in to LIVCK
- Navigate to
/user/profile
- Enter the group chat ID in the Telegram User ID field (including the minus sign if present)
- Click Save
- 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:
- Open Telegram and search for your bot by username
- Start a chat with the bot
- Send any message (e.g.,
/start
) - 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:
- Is the bot added to the group?
- Does the bot have permission to send messages?
- Is the chat ID correct (including minus sign)?
- 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
- Telegram Bot API Documentation
- BotFather - Official bot for creating and managing Telegram bots
- Users & Roles - Member profile management
- Email Notifications - Configure email alerts
- Slack Notifications - Configure Slack alerts