Appearance
Calendar Integration
TL;DR:
- Connect Google Calendar once per workspace, then reuse it across all scenarios.
- Configure per-day working hours, slot duration, time format, and timezone.
- Translate all labels and messages shown to users during booking.
- Add a Calendar Slot Picker card to any Message node to let users book real appointment slots.
Who this is for
- Workspace owners and admins who want to offer appointment booking in their Telegram bot.
- Anyone needing real-time availability checking and automatic calendar event creation.
Overview
Connect your Google Calendar to let your bot show real available appointment slots and automatically create calendar events when users book a time.
Once connected, open Booking Settings to configure the schedule, labels, and messages the bot will use. These settings apply to every Calendar Slot Picker card in the workspace.
TIP
You only need to connect Google Calendar once per workspace. All Calendar Slot Picker cards across all scenarios share the same connection and booking defaults.
TIP
If one bot needs a different calendar, open Bot Settings → Customization → Calendar and override the workspace default there.
How to connect
- Open Workspace Settings → Integrations and click the Calendar tab.
- Click Connect Google Calendar.
- Choose the Google account whose calendar you want to use.
- Review the permissions and click Allow.
- You are redirected back. Status shows Connected with the connected email.
WARNING
The Google account must have full read/write access to the calendar. A "view only" share is not enough — the bot needs to create events.
Booking Settings
Click Configure next to the connected calendar to open the Booking Settings modal. It has three tabs: Schedule, Labels, and Messages.
Schedule tab
Configure when slots are available and how they are displayed.
Weekly schedule
Each day of the week can be enabled or disabled independently. For enabled days, use the hour grid to select which specific hours are available for booking — you can create gaps (for example, block out a lunch break) by leaving hours unselected.
This replaces a single "working hours from–to" range with per-day precision:
| Day | Hours selected | Effect |
|---|---|---|
| Monday | 9, 10, 11, 13, 14, 15, 16, 17 | Available with a lunch break at 12:00 |
| Wednesday | — | Day off, no slots offered |
| Saturday | 10, 11 | Two morning slots only |
Disabled days show no slots to users regardless of what is in the calendar.
Other schedule settings
| Setting | What it does |
|---|---|
| Slot duration | Length of each bookable appointment in minutes (e.g. 30, 60). |
| Time format | How times are shown to users — 24-hour or 12-hour AM/PM. |
| Timezone | The timezone used for all slot calculations and display. Defaults to the workspace timezone. |
Labels tab
Customize all text shown to users during the slot-picking flow. Leave a field empty to use the built-in default.
Date and time prompts
| Field | Shown when | Default |
|---|---|---|
| Date picker prompt | Above the date buttons. | "Choose a date:" |
| Time picker prompt | Above the time buttons. | "Choose a time:" |
| Time group prompt | Above the morning/day/evening group buttons (shown before individual times). | "Select a convenient time of day:" |
Time group split
When the number of time slots for a day exceeds the display limit, the bot groups them into Morning, Day, and Evening categories so the user picks a group first, then a specific time.
- Morning ends at — hour when Morning ends and Day begins (default: 12:00).
- Day ends at — hour when Day ends and Evening begins (default: 18:00).
These can be adjusted to match your business hours. For example, if your slots start at 14:00, set "Morning ends at" and "Day ends at" both to 14:00 so everything falls under Evening.
Group labels
| Field | Default |
|---|---|
| Morning label | Morning |
| Day label | Day |
| Evening label | Evening |
These labels appear on the group selection buttons alongside the time range, for example: "Morning (09:00–12:00)".
Messages tab
Configure all messages and button labels related to booking conflicts, rebooking, and cancellation.
No available slots
| Field | Shown when |
|---|---|
| No slots message | No available dates are found in the booking range. |
Slot conflict
When a slot becomes unavailable between display and confirmation (someone else booked it), the bot retries automatically.
| Field | What it does |
|---|---|
| Max retries | How many times the bot re-renders the date picker before giving up. Default: 3. |
| Retry message | Shown each time a retry happens (e.g. "That slot was just taken — please pick another."). |
| Error message | Shown when all retries are exhausted (e.g. "No slots left — please try again later."). |
Rebooking prompt
Shown when the user already has an active booking and reaches a Calendar Slot Picker card again.
| Field | Default |
|---|---|
| Prompt text | "You already have a booking: 📅 {date} at {time}\n\nWould you like to reschedule?" |
| Reschedule button | ✏️ Reschedule |
| Keep booking button | ✅ Keep booking |
| Cancel booking button | ❌ Cancel booking (shown only if Allow cancellation is enabled on the card) |
All fields support macros. The prompt text supports {date} and {time} placeholders which are replaced with the existing booking's date and time in the configured format.
Calendar selection resolution
When a booking card runs, the runtime resolves the target calendar in this order:
- Bot Settings → Customization → Calendar — if this bot overrides the workspace default.
- Workspace default calendar — the calendar selected in this tab.
- The connected Google account's Primary calendar as a hard fallback.
All Calendar Slot Picker cards inside the same bot use the same resolved calendar.
Using Calendar in scenarios
Once connected and configured, add a Calendar Slot Picker card inside a Message node. The card automatically uses the workspace booking defaults.
INFO
For per-card settings, output connectors, and booking variables, see Calendar Slot Picker.
Disconnecting
Click Disconnect to remove the connection.
What happens when you disconnect:
- The access token is removed and the bot immediately stops checking availability.
- Calendar Slot Picker cards show the "no slots" message to users until you reconnect.
- Booking data already saved to user context variables is not affected.
- Your booking defaults (schedule, labels, messages) are preserved.
Troubleshooting
"No available slots" shown to users
Cause: Google Calendar is not connected, booking defaults were not saved, or no hours are selected in the weekly schedule.
Fix: Open the Calendar tab, confirm Connected status, open Booking Settings → Schedule, and verify that at least one day has hours selected. Click Save.
Wrong slots are offered
Cause: Weekly schedule hours or timezone do not match expectations.
Fix: Review the Schedule tab. Check that the timezone matches the timezone your business operates in — a wrong timezone can shift all slots by several hours.
Calendar disconnected itself
Cause: The connection was revoked in Google account security settings.
Fix: Click Connect Google Calendar to reconnect. Booking defaults are preserved.
User sees "slot taken" repeatedly
Cause: The slot shown to the user was booked by someone else (or by a calendar event you added directly) before the user confirmed.
Fix: This is expected in busy calendars. Increase the Max retries value or shorten slot duration to offer more options.
FAQ
Q: Can I use a shared or team Google Calendar?
A: Yes. Connect the Google account that has read/write access to the shared calendar, then select it in the Default calendar dropdown.Q: Do I need to reconnect when the token expires?
A: No. Access tokens are refreshed automatically. You only need to reconnect if the app is manually revoked in Google security settings.Q: Can I have different hours on different days?
A: Yes — that is exactly what the per-day hour grid is for. Enable only the days you work and select only the hours you are available on each day.Q: What happens to existing bookings if I disconnect?
A: Context variables already saved to users are kept. The bot stops showing new slots until you reconnect.Q: Can I use multiple calendars?
A: Yes, within limits. Each workspace has one default calendar, and each bot can override it in Bot Settings. All booking cards inside the same bot use that bot's resolved calendar.Q: Will this affect the Google login workspace members use to sign in?
A: No. The calendar connection uses a separate OAuth flow and is independent from any Google-based workspace login.