Back to Overview

Telegram Notifications

Get a Telegram message whenever a meeting is booked, requested, cancelled or rescheduled. This guide covers setting up a shared bot on a self-hosted instance.

Luka Breitig, Software Engineer & AI Developer
Luka Breitig

Mis à jour le 7 septembre 2026

Real-time booking notifications

Tymeslot sends a formatted Telegram message as soon as a meeting is booked, requested, cancelled or rescheduled, so you hear about it without checking your inbox.

  • One shared bot per instance: each user links their own Telegram account through a deep link, without handling any bot credentials
  • Six events, each switched on or off per integration: Meeting Created, Booking Requested, Booking Declined, Booking Request Expired, Meeting Cancelled and Meeting Rescheduled
  • Messages are sent in the background with automatic retries, so a Telegram outage never holds up a booking

1 Create a Telegram bot

  1. Open Telegram and start a conversation with @BotFather.
  2. Send /newbot and follow the prompts to choose a name and username.
  3. BotFather replies with your bot token, a string like 123456789:ABCdef.... Save it.
  4. Note the bot username (for example MyTymeslotBot). Users start a conversation with this bot to link their account.

2 Generate a webhook secret

Tymeslot uses a shared secret to check that incoming webhook calls really come from Telegram. Generate a random value. Telegram accepts up to 256 letters, digits, underscores and hyphens; this command gives 64 hexadecimal characters: 

openssl rand -hex 32

Save the output; you will set it as TELEGRAM_WEBHOOK_SECRET in the next step.

3 Set environment variables

Add the following variables to your deployment environment:

TELEGRAM_BOT_TOKEN=123456789:ABCdef...
TELEGRAM_BOT_USERNAME=MyTymeslotBot
TELEGRAM_WEBHOOK_SECRET=<your generated secret>

Setting TELEGRAM_BOT_TOKEN is enough to switch on shared bot mode; no separate feature flag is needed. The application refuses to start if the token is set but TELEGRAM_BOT_USERNAME or TELEGRAM_WEBHOOK_SECRET are missing.

Own-bot mode

If you want each user to supply their own bot token and chat ID instead, set TELEGRAM_ENABLED=true without setting TELEGRAM_BOT_TOKEN. Users will then enter their own bot credentials in the dashboard. Tymeslot registers its Telegram webhook only in shared bot mode.

4 Deploy and verify

After you restart with the new variables, Tymeslot registers its webhook with Telegram on startup, retrying a few times if Telegram is briefly unreachable. To confirm it worked, call the Telegram Bot API directly: 

curl https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo

The response should show your instance URL under url and pending_update_count: 0. Registration runs on every restart and is safe to repeat.

How users connect their account

Once the bot is running, your users connect their Telegram account from Dashboard → Automation → Telegram:

  1. Click Add Telegram Account. A link to your bot appears; it expires after 10 minutes.
  2. Click Open in Telegram and tap Start in the bot chat.
  3. Telegram notifies Tymeslot, and the form moves on to the next step by itself.
  4. The user names the integration, selects the events to receive and saves.

If the user has started the bot before, Telegram does not resend the /start command when they tap the button again. For that case, the form also shows the full command, for example /start abc123..., which the user can paste into the bot chat to finish linking. If the link expires first, click Generate New Link.

The Connect Telegram step with an Open in Telegram button, a waiting-for-connection status, and a fallback /start command to paste into the bot chat
The linking step, with the fallback /start command underneath.

Local development

Telegram only delivers webhooks to a publicly reachable HTTPS URL. For local development, use ngrok to expose your local server: 

ngrok http 4000

Then start Tymeslot with the ngrok URL as the host: 

export TELEGRAM_BOT_TOKEN=...
export TELEGRAM_BOT_USERNAME=...
export TELEGRAM_WEBHOOK_SECRET=...
export PHX_HOST=abc123.ngrok-free.app
export URL_SCHEME=https
mix phx.server

In production, Tymeslot registers https://<PHX_HOST>/api/telegram/webhook with Telegram at startup. In development it skips that step, so register your ngrok URL yourself with Telegram's setWebhook method, passing the same secret: 

curl -F url=https://abc123.ngrok-free.app/api/telegram/webhook -F secret_token=$TELEGRAM_WEBHOOK_SECRET https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook

Run it again whenever your ngrok URL changes (the free plan assigns a new URL each session).

How the webhook URL is built

PHX_HOST sets the host in the webhook URL Tymeslot registers at startup and in the "View in dashboard" link inside each notification. The scheme comes from the Phoenix endpoint's URL config, which URL_SCHEME sets in development, and that config also supplies the host when PHX_HOST is unset. With neither variable set, development uses http and localhost.

Related Articles

Read Slack Notifications

Slack Notifications

Instant Slack notifications for every booking, cancellation, and reschedule. Connect via OAuth for branded messages and channel switching, or paste an Incoming Webhook URL for a quick setup.