How to send Urlwatch alerts to Telegram

To send urlwatch alerts to Telegram, create a bot with BotFather, start a conversation with it, find the destination chat ID with urlwatch --telegram-chats, then enable urlwatch’s Telegram reporter in its YAML configuration. You need the bot’s API token and the chat ID for each destination.

1. Create a Telegram bot and find the chat ID

In Telegram, open a conversation with BotFather, send /newbot, and follow the prompts.
Copy the bot token BotFather returns. Treat it as a credential: do not publish it or commit it to a public repository.
Open the bot using the link Telegram provides and send /start. This starts the private chat that urlwatch will use as a destination.
On the machine where urlwatch is installed, run urlwatch --telegram-chats. Find the chat ID for the intended destination and copy it exactly.

For a group or other destination, make sure the bot is available there and use the destination ID reported by urlwatch. Do not guess the ID; use the command’s output to identify the intended chat.

2. Enable the Telegram reporter

Open the urlwatch configuration, for example by running urlwatch --edit-config, and add or update the Telegram section:

telegram:
  bot_token: 'YOUR_BOT_API_TOKEN'
  chat_id: 'YOUR_CHAT_ID'
  enabled: true

Replace both placeholders with your actual values. Keep the token private. The enabled setting is required for delivery; merely adding the credentials does not turn the reporter on.

Send alerts to multiple chats

Set chat_id to a YAML list when the same alerts should go to more than one destination:

telegram:
  bot_token: 'YOUR_BOT_API_TOKEN'
  chat_id:
    - 'FIRST_CHAT_ID'
    - 'SECOND_CHAT_ID'
  enabled: true

Choose notification formatting

By default, notifications are not silent and are sent without monospace formatting. You can change either behavior:

telegram:
  bot_token: 'YOUR_BOT_API_TOKEN'
  chat_id: 'YOUR_CHAT_ID'
  enabled: true
  silent: true
  monospace: true

Option	Effect	Documented default
`enabled`	Turns the Telegram reporter on.	Enable it for delivery.
`bot_token`	Authenticates the bot.	Supply the token from BotFather.
`chat_id`	Selects one destination or a YAML list of destinations.	Supply the ID or IDs found with `urlwatch --telegram-chats`.
`silent`	Sends notifications silently when set to `true`.	`false`
`monospace`	Displays the notification as a preformatted code block when set to `true`.	`false`

3. Understand what arrives in Telegram

urlwatch decides which pages to monitor and what changed; Telegram is only the delivery destination. A change notification includes the changed URL and a unified diff of what changed, according to the urlwatch Handbook. Review the monitored jobs and their change output in urlwatch when adjusting what alerts contain.

4. Troubleshoot missing alerts

Symptom	Likely cause	What to check
No Telegram message arrives.	The reporter is disabled.	Confirm `enabled: true` appears under the `telegram` key in the active urlwatch configuration.
The bot does not appear as a destination.	You have not started a conversation with the bot.	Open the bot and send `/start`, then run `urlwatch --telegram-chats` again.
Messages do not reach the intended chat.	The chat ID is wrong or belongs to another destination.	Use the ID shown by `urlwatch --telegram-chats` and check the configured destination carefully.
Telegram rejects delivery.	The token may have been copied incorrectly or the configured token is not the bot token.	Check the BotFather token and update `bot_token`. Keep it secret while troubleshooting.
Configuration changes have no effect.	A different configuration file may be in use, or YAML indentation may be invalid.	Edit the configuration opened by `urlwatch --edit-config`; keep nested fields indented under `telegram:` and consult the documentation for your installed version.

The current reporter documentation does not specify a Telegram-specific test command. Check the CLI help or the documentation matching your installed urlwatch version before trying a test option.

5. Reliability and operating notes

Protect the token. Store it as a secret in deployment configuration, restrict access to the urlwatch config, and rotate it through Telegram if it is exposed.
Verify the destination. Chat IDs are destination-specific; recheck them when moving from a private chat to a group or another chat.
Keep monitoring and delivery separate. A Telegram reporter forwards urlwatch’s change report. If an expected alert is absent, check both whether the monitored job detected a change and whether the reporter is enabled and correctly configured.
Cost and performance. The documented setup uses urlwatch’s reporter and Telegram credentials; no separate screenshot service is required to send these change alerts. The cited urlwatch documentation does not give delivery latency, pricing, or throughput guarantees, so do not assume a particular delivery time or rate limit.

Or skip the browser setup

For a screenshot of a page instead of a change alert, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF. Its API can remove cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

FAQ

Does Telegram monitor webpages for urlwatch?

No. urlwatch monitors configured pages and produces change reports; Telegram receives the notifications.

Can one urlwatch setup notify several chats?

Yes. Set chat_id to a YAML list of destination IDs.

Can I make notifications silent or easier to read as diffs?

Yes. Set silent: true for silent delivery or monospace: true for preformatted output.

Where can I check version-specific reporter settings?

Use the urlwatch reporters documentation and match it to your installed release. The setup here follows the current 2.29 reporter documentation.