Skip to main content

Telegram Integration

Receive instant push notifications on your mobile device via Telegram. Perfect for on-the-go monitoring with inline action buttons and Markdown formatting.

Prerequisites

  • Telegram account (personal or business)
  • BlackTide account (any plan)
  • Access to Alerts → Alert Channels in BlackTide

Step 1: Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Start a chat with BotFather and send /newbot
  3. Follow the prompts:
    • Bot name: BlackTide Alerts (display name, can include spaces)
    • Bot username: blacktide_alerts_bot (must be unique and end with "bot")
  4. BotFather will respond with your Bot Token (e.g., 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz)
  5. Copy and save this token securely (you'll need it in Step 3)

Step 2: Get Your Chat ID

Option A: Personal Chat (1-on-1 alerts)

  1. Search for your bot username in Telegram (e.g., @blacktide_alerts_bot)
  2. Start a chat with your bot by clicking Start
  3. Send any message to the bot (e.g., /start)
  4. Open this URL in your browser (replace YOUR_BOT_TOKEN):
    https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
  5. Look for "chat":{"id":123456789 in the JSON response
  6. Copy the chat id (e.g., 123456789)

Option B: Group Chat (team alerts)

  1. Create a Telegram group
  2. Add your bot to the group (search by username)
  3. Send a message in the group (e.g., /start)
  4. Open the getUpdates URL from Option A
  5. Look for "chat":{"id":-1001234567890 in the JSON response
  6. Copy the negative chat id (e.g., -1001234567890)

Option C: Channel (broadcast alerts)

  1. Create a Telegram channel
  2. Add your bot as an administrator
  3. Post a message in the channel
  4. Open the getUpdates URL from Option A
  5. Copy the chat id (starts with -100)

Step 3: Configure BlackTide Telegram Channel

  1. Log in to BlackTide
  2. Navigate to Alerts → Alert Channels
  3. Click New Channel
  4. Select Telegram as the channel type
  5. Fill in the configuration:
    • Name: On-Call Telegram (or descriptive name)
    • Bot Token: Paste token from Step 1
    • Chat ID: Paste chat ID from Step 2
    • Parse Mode: Markdown (recommended) or HTML
    • Disable Notification: false (enable sound/vibration)
  6. Click Test Channel to send a test message
  7. Verify the test message appears in your Telegram chat
  8. Click Save

Configuration Example

{
  "type": "telegram",
  "name": "On-Call Telegram",
  "config": {
    "botToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
    "chatId": "-1001234567890",
    "parseMode": "Markdown",
    "disableNotification": false
  }
}

Step 4: Create an Alert Rule

  1. Go to Alerts → Alert Rules
  2. Click New Rule
  3. Configure your rule:
    • Name: Production API Down
    • Monitors: Select monitors to watch
    • Conditions: 3 consecutive failures
    • Channels: Select your Telegram channel
    • Notify on Recovery: Yes
  4. Save the rule

Message Format

Downtime Alert

🚨 *Monitor Down*

*Monitor:* Production API
*URL:* https://api.example.com/health
*Status:* Down
*Region:* US East
*Failed Checks:* 3 consecutive
*Error:* Connection timeout after 10s

*Time:* 2026-02-13 14:30:00 UTC

[View Monitor] [Dashboard] [Acknowledge]

Recovery Alert

✅ *Monitor Recovered*

*Monitor:* Production API
*URL:* https://api.example.com/health
*Status:* Up
*Region:* US East
*Downtime:* 5 minutes 32 seconds

*Time:* 2026-02-13 14:35:32 UTC

[View Monitor] [View Incident]

Advanced Features

1. Inline Action Buttons

Telegram messages include interactive buttons:

  • View Monitor: Opens monitor detail page
  • Acknowledge: Marks incident as acknowledged
  • Silence 1h: Silences monitor for 1 hour
  • Dashboard: Opens BlackTide dashboard

2. Markdown Formatting

Use Markdown for rich text formatting:

  • Bold: *text* or **text**
  • Italic: _text_
  • Code: `code`
  • Code Block: ```code block```
  • Link: [text](url)

3. Silent Notifications

For low-priority alerts, disable sound/vibration:

{
  "disableNotification": true  // Silent notification
}

4. HTML Formatting (Alternative)

If you prefer HTML over Markdown:

{
  "parseMode": "HTML"
}

// Message format:
<b>Monitor Down</b>
<i>Production API</i>
<code>https://api.example.com</code>
<a href="https://blacktide.xyz">View Monitor</a>

Best Practices

1. Use Different Chats for Different Severities

  • Personal chat: P0 critical alerts only (immediate attention)
  • Team group: P1-P2 production issues (shared awareness)
  • Channel: All alerts (broadcast, no discussion)

2. Enable Notifications for Critical Alerts

// P0 (Critical) - Sound + vibration
"disableNotification": false

// P2-P3 (Low) - Silent
"disableNotification": true

3. Use Bot Commands

Add commands to your bot for quick actions:

  1. Talk to @BotFather
  2. Send /setcommands
  3. Select your bot
  4. Add commands:
    status - Check current monitor status
incidents - View open incidents
silence - Silence all monitors for 1 hour

4. Combine with Other Channels

Use Telegram alongside other notification methods:

  • Primary: Telegram (instant mobile notifications)
  • Backup: Email (reaches everyone)
  • Team: Slack/Discord (team visibility)

5. Test Regularly

Telegram bots can stop working if:

  • Bot token is revoked
  • Bot is removed from group/channel
  • Chat ID changes (rare)

Test your Telegram channels monthly to ensure they still work.

Troubleshooting

Test Message Not Appearing

Possible Causes:

  • Bot token is incorrect or revoked
  • Chat ID is incorrect
  • Bot was removed from group/channel
  • Bot doesn't have permission to send messages

Solution:

  1. Verify bot token is correct
  2. Test bot manually with curl:
    curl -X POST \
  "https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage" \
  -d "chat_id=YOUR_CHAT_ID&text=Test from BlackTide"
  3. Verify chat ID is correct (check getUpdates again)
  4. Ensure bot is still in the group/channel
  5. Check bot has permission to send messages (for channels, bot must be admin)

Messages Arriving but No Notification Sound

Solution:

  • Set "disableNotification": false in channel config
  • Check your Telegram notification settings for the chat
  • Verify your phone isn't in Do Not Disturb mode

Action Buttons Not Working

Possible Causes:

  • Old Telegram client version
  • BlackTide callback URL unreachable

Solution:

  • Update Telegram to the latest version
  • Verify buttons open correct URLs in browser

Getting "Forbidden" Error

Cause: Bot was blocked by user or kicked from group.

Solution:

  • For personal chat: Unblock the bot and send /start
  • For group: Re-add the bot to the group
  • For channel: Re-add bot as administrator

Security Considerations

Bot Token Security

  • Treat bot tokens as secrets (anyone with token can send messages as your bot)
  • Don't commit tokens to version control
  • Rotate tokens if they're accidentally exposed (talk to @BotFather, use /revoke)

Chat ID Privacy

  • Chat IDs are not secrets, but don't share unnecessarily
  • Use private groups for sensitive alerts
  • Consider using channels instead of groups for broadcast-only alerts

Sensitive Data in Alerts

  • Don't include API keys, passwords, or tokens in monitor names
  • Mask sensitive data in alert messages
  • Use private chats/groups for alerts containing PII

Rate Limits

Telegram has rate limits for bot messages:

  • Telegram API Limit: 30 messages per second (across all chats)
  • Group Limit: 20 messages per minute per group
  • BlackTide Limit: 30 alerts per hour per channel

If you hit the BlackTide rate limit, alerts are queued and sent when the window resets.

Bot API Reference

For advanced users, here are useful Telegram Bot API endpoints:

Send Message

POST https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage
{
  "chat_id": "YOUR_CHAT_ID",
  "text": "Your message",
  "parse_mode": "Markdown",
  "disable_notification": false
}

Get Updates (Chat ID)

GET https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates

Get Bot Info

GET https://api.telegram.org/botYOUR_BOT_TOKEN/getMe

Next Steps