Telegram Setup

Clawbolt uses a Telegram bot as its messaging interface. This guide walks you through creating a bot, connecting it to Clawbolt, and configuring who can use it.

1. Create a bot with BotFather

BotFather is Telegram’s built-in tool for creating and managing bots.

Open Telegram on your phone or desktop
Search for @BotFather or open t.me/BotFather
Send /newbot
BotFather asks for a display name (e.g. “My Clawbolt”). This is what users see in chat.
BotFather asks for a username (e.g. my_clawbolt_bot). Must end in bot and be unique across Telegram.
BotFather replies with your bot token. It looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Keep this secret.

Add the token to your .env file:

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

2. Configure access control

Clawbolt rejects all incoming messages by default. Before starting the server, configure who is allowed to message the bot.

Allow by username

The simplest option. Add Telegram usernames (without the @) to your .env:

TELEGRAM_ALLOWED_USERNAMES=johndoe,janedoe

Allow by chat ID

Chat IDs are numeric and never change, so they are more reliable than usernames. Add them to your .env:

TELEGRAM_ALLOWED_CHAT_IDS=123456789,987654321

Allow everyone

To allow any Telegram user to message the bot:

TELEGRAM_ALLOWED_CHAT_IDS=*

If both TELEGRAM_ALLOWED_CHAT_IDS and TELEGRAM_ALLOWED_USERNAMES are set, a message is allowed when either matches.

Finding your chat ID

To find your own chat ID:

Search for @userinfobot on Telegram and start a chat
It replies with your user ID, which is your chat ID for private messages

Alternatively, send a message to your bot and check the server logs. Clawbolt logs the chat ID of blocked messages:

INFO: Chat 123456789 / @yourname not in allowlist, ignoring

3. Connect the webhook

Telegram delivers messages to Clawbolt via a webhook: Telegram sends an HTTPS request to your server for every new message.

Docker Compose (automatic)

When using Docker Compose, the webhook is registered automatically on startup:

Docker Compose starts a Cloudflare Tunnel alongside the app
The tunnel creates a public HTTPS URL (a random *.trycloudflare.com domain)
The app discovers the tunnel URL and calls Telegram’s setWebhook API

No Cloudflare account or auth token is required. Check the tunnel URL with:

docker compose logs tunnel

Local development (manual)

If you are running without Docker, you need a tunnel to give Telegram a public URL:

# Install cloudflared: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
cloudflared tunnel --url http://localhost:8000

Copy the https://*.trycloudflare.com URL from the output, then register the webhook:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://<your-tunnel-url>/api/webhooks/telegram"}'

4. Verify everything works

Check that Telegram sees your webhook:

curl -s "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo" | python3 -m json.tool

You should see your tunnel URL in the url field and no errors in last_error_message.

Then send a message to your bot on Telegram. If Clawbolt is running and configured correctly, it will respond.

Troubleshooting

Bot does not respond to messages

Check the server logs for allowlist rejections. If you see “not in allowlist, ignoring”, update TELEGRAM_ALLOWED_CHAT_IDS or TELEGRAM_ALLOWED_USERNAMES in your .env.
Verify the webhook is registered: run the getWebhookInfo curl command above.
Make sure the server is running and reachable at the tunnel URL.

“Webhook was not set” or empty URL in getWebhookInfo

If using Docker Compose, check that the tunnel container is healthy: docker compose ps.
If running locally, make sure cloudflared is still running and re-register the webhook.

getWebhookInfo shows last_error_message

SSL error or Connection refused: the tunnel may have restarted with a new URL. Re-register the webhook with the new URL.
Wrong response from the webhook: 500: check the server logs for application errors.

BotFather says the username is taken

Bot usernames must be globally unique and end in bot. Try a more specific name like yourcompany_clawbolt_bot.