Telegram

Telegram notifications are delivered through a bot you create and own. ChannelWatch uses Apprise under the hood, so you only need two pieces of information: a bot token and a chat ID.

Step 1: Create a bot with BotFather

1. Open the official @BotFather account in Telegram.
2. Send the command /newbot.
3. Follow the prompts: choose a display name, then a username ending in bot (e.g. channelwatch_alerts_bot).
4. BotFather replies with your bot token. It is a long value that includes a colon.

Copy the token and keep it somewhere safe. You’ll need it in Step 3.

Note

The bot token is a secret. Anyone who has it can send messages as your bot. Do not share it or commit it to version control.

Step 2: Get your chat ID

The chat ID tells the bot where to deliver messages. The method depends on whether you’re sending to a personal chat, a group, or a channel.

Personal chat (simplest)

1. Start a conversation with your new bot by searching for its username in Telegram and clicking Start.

2. Send any message to the bot (e.g. hello).

3. Open this URL in a browser, replacing <bot-token> with your actual token:

   https://api.telegram.org/bot<bot-token>/getUpdates

4. Look for "chat":{"id": in the JSON response. The number that follows is your chat ID (e.g. 123456789).

Group chat

1. Add your bot to the group.
2. Send a message in the group that mentions the bot (e.g. @channelwatch_alerts_bot hello).
3. Call the same getUpdates URL above. The chat ID for a group is a negative number (e.g. -987654321).

Channel destination

Add the bot to the channel with permission to post. Use a channel identifier supported by the bundled Apprise Telegram service, and confirm that you are targeting the intended channel rather than a personal conversation.

Note

Telegram keeps pending updates for no longer than 24 hours. Updates already consumed by another client will not remain pending. getUpdates also cannot be used while the bot has an outgoing webhook configured. Prefer a dedicated bot for ChannelWatch; do not delete a webhook used by another application just to look up a chat ID. See the Telegram Bot API.

Step 3: Enter credentials in ChannelWatch

1. Open the ChannelWatch web UI, go to Settings > Notifications, and stay on the Global scope.

2. Enable the Telegram toggle.

3. In the Bot Token / Chat ID field, enter your credentials in this format:

   <bot-token>/<chat-id>

   For example:

   <bot-token>/123456789

4. Click Save.

ChannelWatch wraps your input with the tgram:// prefix internally. You do not need to add it yourself.

Telegram bot token and chat IDJoin the bot token and destination chat ID with a slash. Sample credentials are masked. Captured from ChannelWatch v1.6.0 with safe demo data.View full-size screenshot

Environment variable

If you prefer to configure Telegram without the web UI, set this variable in your docker-compose.yml:

environment:
  CW_APPRISE_TELEGRAM: "<bot-token>/<chat-id>"

Replace <bot-token> and <chat-id> with your actual values.

Caution

Credentials in environment variables are visible to anyone who can run docker inspect on the container. For shared hosts, prefer the web UI, which stores credentials in /config/settings.json.

Step 4: Send a test notification

ChannelWatch v1.6.0 has a Diagnostics notification-test limitation. Use the supported command-line fallback below when testing this release. It sends a real message to configured destinations:

docker exec -it channelwatch python -m core.main --test-alert ALERT_CHANNEL_WATCHING

Check the intended Telegram chat and Delivery Log. A successful API response does not guarantee a device notification was displayed.

Troubleshooting

“Forbidden” error in logs

The bot is not a member of the target chat. For personal chats, make sure you started a conversation with the bot first (click Start in Telegram). For groups, add the bot as a member.

“Chat not found” error

The chat ID is wrong or the bot has never interacted with that chat. Double-check the ID from getUpdates. For groups, confirm the bot is in the group and that you used the negative ID (e.g. -987654321).

getUpdates returns an empty result

Send a fresh message addressed to the bot, then retry. Check whether another application already consumed the update or configured a webhook for the bot. Keep the token private when sharing the response.

Notifications stop arriving after working initially

Telegram bots do not require polling to send messages, but if you revoke and regenerate the bot token in BotFather, you must update the token in ChannelWatch. Go to Settings > Notifications, update the Bot Token / Chat ID field, and save.

Group notifications not working after adding the bot

Some groups require bots to have explicit send-message permission. In the group settings, confirm the bot is not restricted from posting.

Related pages

• Provider Matrix - compare all notification providers at a glance
• Discord - webhook-based notifications for Discord servers
• Slack - post alerts to a Slack channel
• Delivery Log - view per-notification delivery history and retry status
• Notification Examples - see what each alert type looks like when delivered