33. Google Calendar Integration

The calendar_picker field is a Free field type and generates bookable slots from its working hours. The Google Calendar free/busy overlay and event creation are PRO features.

Server-side Calendar requests use the same site capability envelope as Google Sheets: license_key, product, forge_site_url, and site_token. Direct calls that only know the license key are rejected before the Worker touches Google tokens or creates events. Public submissions also validate calendar_picker values before payment capture: the posted value must parse to a future timestamp inside the field’s configured advance window, on an enabled weekday, and within work_start <= slot < work_end.

Calendar Picker Field

{
  "id": "field_appointment",
  "type": "calendar_picker",
  "label": "Preferred Time",
  "required": true,
  "slot_duration": 30,
  "work_start": 9,
  "work_end": 17,
  "advance_days": 30
}

Slot Calculation Flow

1. User selects a date
2. Frontend sends AJAX request to formforge_calendar_slots
3. Server queries Google Calendar free/busy API
4. Busy periods are subtracted from working hours to produce available slots
5. Calendar not readable: if the free/busy list cannot be read (Google or the Avakode server does not answer, or the answer has no list of slots) and the bookings of the form go into the calendar (Pro running, with its Google Calendar feature on), the call answers HTTP 503 with the body {"success":false,"data":{"code":"calendar_unavailable","message":"Could not load free times. Please try again later."}}; the picker shows that message and offers no times. A form with no calendar chosen, a site where Pro is not running, and a site where the Google Calendar feature of Pro is off (for example because the licence has ended) get the locally generated slots

$result = FORMFORGE_Forge_API::instance()->calendar_freebusy(
    $calendar_id,
    '2025-02-15T00:00:00Z',
    '2025-02-15T23:59:59Z',
    30, 9, 17
);
// Returns: { "available_slots": ["09:00", "09:30", "10:00", ...] }

---