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.
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
Open Telegram and start a conversation with @BotFather.
Send /newbot
and follow the prompts to choose a name and username.
BotFather replies with your bot token — a string like 123456789:ABCdef.... Save it.
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:
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:
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:
Click Add Telegram Account
— a deep link to your bot appears.
Click Open in Telegram
and tap Start
in the bot chat.
Tymeslot receives the confirmation via webhook and automatically advances the wizard.
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.
The linking step, with the fallback
/start
command underneath.
🛠️
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:
In production,
BotSetup
registers
https://abc123.ngrok-free.app/api/telegram/webhook
with Telegram. Webhook registration runs only when the shared bot is
enabled and the app is running in production, so in development
register the URL yourself with Telegram's setWebhook API. Restart
the server whenever your ngrok URL changes (free plan assigns a new
URL each session).
How the webhook URL is built
PHX_HOST
is read at startup by the bot setup task and by the message builder when generating
"View in dashboard" links in notifications. The scheme comes from URL_SCHEME,
which feeds the Phoenix endpoint config that both also fall back to for the host. Without
either, the application uses that endpoint config, which points to
localhost
over http
in development.
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.
