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

Open Telegram and search for @BotFather (the official bot management account, verified with a blue checkmark).
Send the command /newbot.
Follow the prompts: choose a display name, then a username ending in bot (e.g. channelwatch_alerts_bot).
BotFather replies with your bot token in the format 1234567890:ABCDefGhIJKlmNoPQRsTUVwxyZ.

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

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)

Start a conversation with your new bot by searching for its username in Telegram and clicking Start.
Send any message to the bot (e.g. hello).
Open this URL in a browser, replacing YOUR_BOT_TOKEN with your actual token:
```
https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
```
Look for "chat":{"id": in the JSON response. The number that follows is your chat ID (e.g. 123456789).

Group chat

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

Alternative: use @userinfobot or @get_id_bot

If the getUpdates approach returns an empty result array, try forwarding any message to @userinfobot or @get_id_bot. Both bots reply with the chat ID of the forwarded message’s origin.

Step 3: Enter credentials in ChannelWatch

Open the ChannelWatch web UI and go to Settings > Notifications.
Enable the Telegram toggle.
In the Bot Token / Chat ID field, enter your credentials in this format:
```
bot_token/chat_id
```
For example:
```
1234567890:ABCDefGhIJKlmNoPQRsTUVwxyZ/123456789
```
Click Save.

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

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.

Step 4: Send a test notification

Go to Diagnostics > Alert Tests and run any alert test. The notification should arrive in your Telegram chat within a few seconds.

You can also test from the command line:

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

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

The bot has no recent messages to report. Send a fresh message to the bot or group, then call getUpdates again within a minute.

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.

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