Back to Overview

Telegram Notifications

Receive instant Telegram messages whenever a meeting is booked, cancelled, or rescheduled. This guide covers operator setup for self-hosted deployments running a shared bot.

Luka Breitig — Technical Product Builder & AI Developer
Luka Breitig

Technical Product Builder & AI Developer

✈️ Real-time booking notifications

Tymeslot can send formatted Telegram messages the moment a meeting is booked, cancelled, or rescheduled — no polling, no email lag.

  • One shared bot per instance — users connect their own Telegram account via a deep link, no credentials required
  • Three events supported: new meeting, cancellation, and reschedule — each independently togglable
  • Delivery is asynchronous with automatic retries — transient Telegram API errors never block bookings

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 (e.g. MyTymeslotBot) — users will start a conversation with this bot to link their account.

2 Generate a webhook secret

Tymeslot verifies that incoming webhook calls genuinely come from Telegram using a shared secret. Generate a random value — any alphanumeric string of 64+ characters works: 

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...\nTELEGRAM_BOT_USERNAME=MyTymeslotBot\nTELEGRAM_WEBHOOK_SECRET=<your generated secret>

Setting TELEGRAM_BOT_TOKEN is all that is needed to enable shared bot mode — no separate feature flag is required. The application will refuse 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. The webhook endpoint and bot-setup startup task are only activated in shared bot mode.

4 Deploy and verify

After restarting with the new variables, Tymeslot automatically registers the webhook with Telegram on startup. You can confirm it worked by calling 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. The webhook registration is idempotent — it is safe to call on every restart.

🔗 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 deep link to your bot appears.
  2. Click Open in Telegram and tap Start in the bot chat.
  3. Tymeslot receives the confirmation via webhook and automatically advances the wizard.
  4. The user picks a name for the integration and selects which events to subscribe to, then saves.

If the user has already started the bot before, Telegram will not resend the /start command when they tap the button again. In that case the wizard shows a fallback command — e.g. /start abc123... — which the user can paste directly into the bot chat to complete linking.

🛠️ Local development

Telegram webhooks require 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=...\nexport TELEGRAM_BOT_USERNAME=...\nexport TELEGRAM_WEBHOOK_SECRET=...\nexport PHX_HOST=abc123.ngrok-free.app\nexport PHX_SCHEME=https\nmix phx.server

On startup, BotSetup registers https://abc123.ngrok-free.app/api/telegram/webhook with Telegram. Restart the server whenever your ngrok URL changes (free plan assigns a new URL each session).

PHX_HOST overrides the endpoint config

PHX_HOST and PHX_SCHEME are read at startup by the bot setup task and by the message builder when generating "View in dashboard" links in notifications. Without them, the application falls back to the Phoenix endpoint config, which points to localhost in development.

🔗 Related Articles

Read Docker Self-Hosting

Docker Self-Hosting

Deploy Tymeslot with Docker Compose on any VPS or home server. Includes reverse proxy setup, file upload volumes, and WebSocket configuration for LiveView.

Read Cloudron Deployment

Cloudron Deployment

Install Tymeslot on Cloudron in minutes. PostgreSQL, SSL certificates, email relay, and automatic updates are all provisioned and managed for you.

Read Railway Deployment

Railway Deployment

Deploy Tymeslot to Railway with one click. PostgreSQL is provisioned and connected automatically — set two environment variables and your instance is live.