TIMEZONE SLOTS CONVERTER — COMPLETE USER GUIDE
Generate timezone-aware appointment slots with flexible weekly schedules and date-specific overrides. Perfect for booking systems, scheduling platforms, consultation apps, and multi-timezone marketplaces.

═══════════════════════════════════════════════════════════════

📋 OVERVIEW

This plugin converts expert availability patterns (in their local timezone) into UTC time slots that can be:
- Displayed in any user's timezone
- Stored in your database
- Used in booking workflows
- Filtered and sorted dynamically

Key Features:
✓ Multiple time blocks per day
✓ Date-specific overrides for holidays/exceptions
✓ Automatic timezone conversion to UTC
✓ DST-aware (Daylight Saving Time)
✓ Customizable slot intervals
✓ Month-by-month generation

═══════════════════════════════════════════════════════════════

⚙️ SETUP INSTRUCTIONS

STEP 1: ADD THE ELEMENT
1. In your Bubble editor, add the "Timeslots" element to your page
2. The element is invisible (no UI) — it's a data processor
3. Configure it using the fields below

═══════════════════════════════════════════════════════════════

📝 ELEMENT FIELDS (CONFIGURE IN APPEARANCE TAB)

─────────────────────────────────────────────────────────────

1️⃣ WEEKLY AVAILABILITY PATTERNS

Configure when the expert is available each day of the week.

Field Names:
- sunday_pattern
- monday_pattern
- tuesday_pattern
- wednesday_pattern
- thursday_pattern
- friday_pattern
- saturday_pattern

Format Options:

A) Single Time Block (one continuous session):
  480,1020
  ↓
  Available from 8:00 AM to 5:00 PM

B) Multiple Time Blocks (separated by pipe |):
  480,720 | 840,1020
  ↓
  Available 8:00 AM–12:00 PM AND 2:00 PM–5:00 PM
  (Perfect for lunch breaks or split schedules)

C) Leave Empty:
  (blank)
  ↓
  Unavailable on this day

⏰ TIME FORMAT (Minutes Since Midnight):

Times are specified in minutes from midnight (00:00):

Common Examples:
- 0 = 12:00 AM (midnight)
- 480 = 8:00 AM (8 × 60)
- 720 = 12:00 PM (12 × 60)
- 1020 = 5:00 PM (17 × 60)
- 1200 = 8:00 PM (20 × 60)
- 1439 = 11:59 PM

💡 Quick Calculation:
  Minutes = (Hours × 60) + Minutes
 
  Examples:
  • 9:30 AM = (9 × 60) + 30 = 570
  • 2:45 PM = (14 × 60) + 45 = 885

─────────────────────────────────────────────────────────────

2️⃣ SLOT INTERVAL (Required)

Field: interval
Type: Number (minutes)

How far apart each appointment slot should be.

Examples:
- 15 = 15-minute slots (dentist appointments)
- 30 = 30-minute slots (consultations)
- 60 = 1-hour slots (coaching sessions)
- 120 = 2-hour slots (workshops)

Note: This represents the gap between slot start times, not the appointment duration.

─────────────────────────────────────────────────────────────

3️⃣ TIMEZONE ID (Required)

Field: timezone_id
Type: Text (IANA timezone identifier)

The expert's local timezone where they set their availability.

✅ Valid Examples:
- America/New_York (US Eastern)
- America/Los_Angeles (US Pacific)
- America/Chicago (US Central)
- Europe/London (UK)
- Europe/Paris (France, Germany, Spain)
- Asia/Kolkata (India)
- Asia/Tokyo (Japan)
- Australia/Sydney (Australia)
- Pacific/Auckland (New Zealand)

❌ Invalid Examples:
- EST (use America/New_York)
- PST (use America/Los_Angeles)
- GMT (use Europe/London)
- IST (use Asia/Kolkata)

📖 Full List of Valid Timezones:
https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

⚠️ Important: The plugin automatically handles Daylight Saving Time (DST) transitions.

─────────────────────────────────────────────────────────────

4️⃣ MONTH OFFSET (Optional)

Field: month_offset
Type: Number
Default: 0 (current month)

Which month to generate slots for, relative to today.

Examples:
- 0 = Current month (January if today is January 26)
- 1 = Next month (February if today is January 26)
- 2 = Two months ahead
- -1 = Previous month

💡 Use Case: Let users navigate between months in your booking calendar.

─────────────────────────────────────────────────────────────

5️⃣ DATE-SPECIFIC OVERRIDES (Optional)

Field: date_patterns
Type: Static Text (JSON format)

Use this to override weekly patterns for specific dates like:
- Holidays (completely unavailable)
- Special hours (shorter/longer availability)
- One-time events
- Vacation days

Format (JSON Array):
[
 {
   "date": "2026-01-30",
   "patterns": [[600, 900], [1080, 1200]]
 },
 {
   "date": "2026-01-31",
   "patterns": []
 }
]

JSON Structure Explained:

{
 "date": "YYYY-MM-DD",           ← ISO date format (required)
 "patterns": [[start, end], ...]  ← Array of time blocks
}

Rules:
✓ Dates must be in ISO format: YYYY-MM-DD
✓ Date override completely REPLACES the weekly pattern for that day
✓ Empty patterns array [] = completely unavailable
✓ Dates outside the target month are ignored
✓ Multiple time blocks supported (same as weekly patterns)

Examples:

A) Holiday (Completely Unavailable):
[
 {
   "date": "2026-12-25",
   "patterns": []
 }
]

B) Half Day (Only Morning):
[
 {
   "date": "2026-01-15",
   "patterns": [[480, 720]]
 }
]

C) Extended Hours (Special Event):
[
 {
   "date": "2026-02-14",
   "patterns": [[480, 1320]]
 }
]

D) Multiple Dates:
[
 {
   "date": "2026-01-15",
   "patterns": []
 },
 {
   "date": "2026-01-30",
   "patterns": [[600, 900]]
 },
 {
   "date": "2026-02-14",
   "patterns": [[480, 720], [840, 1020]]
 }
]

💡 Tip: Leave this field empty if you don't need date overrides.

═══════════════════════════════════════════════════════════════

🎬 ACTIONS

ACTION: Get Available Times

This action triggers the slot generation process.

Usage:
1. Add a workflow trigger (button click, page load, etc.)
2. Select action: "Get available times" (from your Timeslots element)
3. Slots are automatically generated and published to the element's state

Example Workflow:
When Button "Load Slots" is clicked
 → Get available times (Timeslots A)

Note: Slots also auto-regenerate when element properties change (e.g., month_offset updates).

═══════════════════════════════════════════════════════════════

📤 OUTPUT

STATE: slots

Type: List of Dates (Bubble date objects)
Timezone: UTC

Each item in the list represents one available appointment slot, stored as a JavaScript Date object in UTC timezone.

How to Use:

1️⃣ Display in Repeating Group:
  Data source: Timeslots A's slots
  Type: date
  Cell content: Current cell's date (formatted as needed)

2️⃣ Format for Display:
  Bubble automatically converts UTC to user's local timezone
  Use: Current cell's date:formatted as "h:mm a"

3️⃣ Save to Database:
  Store directly as date field (UTC is preserved)

4️⃣ Filter/Search:
  Use Bubble's date operators (:filtered, :sorted, etc.)

═══════════════════════════════════════════════════════════════

📖 COMPLETE EXAMPLE

Scenario: A New York consultant available Mon-Fri, 9 AM–5 PM, with lunch break and a half-day on Jan 30.

CONFIGURATION:

monday_pattern: "540,720 | 780,1020"
tuesday_pattern: "540,720 | 780,1020"
wednesday_pattern: "540,720 | 780,1020"
thursday_pattern: "540,720 | 780,1020"
friday_pattern: "540,720 | 780,1020"
saturday_pattern: (empty)
sunday_pattern: (empty)
interval: 30
timezone_id: "America/New_York"
month_offset: 0
date_patterns: '[
 {
   "date": "2026-01-30",
   "patterns": [[540, 720]]
 }
]'

RESULT:

Regular Weekdays (Mon-Fri):
- 9:00 AM – 12:00 PM (morning session)
- 1:00 PM – 5:00 PM (afternoon session)
- 30-minute slots
- Total: 14 slots per day

January 30, 2026 (Override):
- 9:00 AM – 12:00 PM only
- 6 slots

Weekends:
- No availability

All slots returned in UTC, ready to display in any timezone.

═══════════════════════════════════════════════════════════════

🔧 TROUBLESHOOTING

Issue: No slots generated
✓ Check that interval and timezone_id are filled
✓ Verify at least one day has a pattern
✓ Ensure pattern format is correct (e.g., "480,1020")
✓ Check browser console for errors

Issue: Slots appear on wrong dates
✓ Remember: UTC slots may appear on different dates when converted to local timezone
✓ This is normal for experts/users in very different timezones
✓ Example: Monday 11 PM NYC → Tuesday 12 AM UTC → Tuesday 9:30 AM India

Issue: Slots at odd times (e.g., 9:53 PM)
✓ This happens when availability starts at non-round times
✓ Expert's 11:23 AM → Converts to 9:53 PM in another timezone
✓ To avoid: Set availability on round hours/half-hours

Issue: Invalid timezone error
✓ Use IANA format (e.g., "America/New_York" not "EST")
✓ Reference: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Issue: JSON parse error in date_patterns
✓ Validate JSON syntax at https://jsonlint.com
✓ Ensure double quotes (not single quotes)
✓ Check comma placement
✓ Dates must be "YYYY-MM-DD" format

═══════════════════════════════════════════════════════════════

💡 BEST PRACTICES

1. Use Round Times
  Set availability on the hour or half-hour for cleaner slot times.
  ✓ 480 (8:00 AM)
  ✓ 510 (8:30 AM)
  ✗ 487 (8:07 AM)

2. Match Interval to Appointment Type
  • Quick calls: 15 minutes
  • Standard meetings: 30 minutes
  • Deep consultations: 60+ minutes

3. Account for Buffer Time
  If you need prep time, build it into your patterns:
  Pattern: "540,720 | 810,1020"
  (30-min gap from 12:00-12:30 PM for lunch/prep)

4. Test Timezone Conversion
  Preview your app in different timezones to verify slot display.

5. Dynamic Month Navigation
  Store month_offset in a custom state, update with +/- buttons.

6. Validate User Input
  If letting users set patterns via UI, validate format before saving.

═══════════════════════════════════════════════════════════════

🌐 DEMO APP

Try our interactive demo to see the plugin in action:
https://bubble.io/page?id=timezoneslotsconverter&tab=Design&name=index

═══════════════════════════════════════════════════════════════