Build a booking system on Google Calendar and Outlook

Free/busy returns busy time, not open slots

A Stack Overflow question asks whether the Google Calendar API can return empty calendar spaces, because "what I can see returned is just current booked slots". Google's freeBusy.query returns, for each calendar, a busy list: "List of time ranges during which this calendar should be regarded as busy." Microsoft Graph's getSchedule returns schedule items with a status, an availabilityView string and the person's working hours, and Microsoft lists it as not supported for personal Microsoft accounts.

Open slots are your computation: bookable hours minus busy blocks, cut into slots. The free/busy guide does it by hand for both providers. In Pyas, meetingTimes.find does it across Google and Outlook accounts in one call.

The rules that make a gap bookable

A gap is not yet a slot you can offer. Each booking rule is a meetingTimes.find parameter:

• Working hours. Graph returns them with getSchedule, in a time zone that can be a custom one, with a bias and daylight saving rules instead of a name. Google's freeBusy response has no working hours. Pass workingHours for hosts whose provider reports none; respectWorkingHours is on by default.
• Buffers. buffer: { before, after } keeps minutes free around the host's other events, so a call doesn't start the minute the last one ends.
• Minimum notice. minimumNoticeMinutes stops a guest from booking a slot that starts in ten minutes.
• Length and grid. durationMinutes is the meeting length. slotMinutes (5, 10, 15, 20, 30 or 60) is the grid starts line up to, so you offer 10:00 and 10:30, not 10:07.

Tentative events count as busy unless you set tentativeIsBusy: false. One request covers at most 62 days.

Three time zones in every booking

The host works in one zone, the guest books from another, and each provider stores time its own way. Google stores an IANA name such as Europe/Zurich on an event's start and end. Graph's dateTimeTimeZone uses Windows names such as Pacific Standard Time plus a list of IANA names. Converting them has traps, such as three Canadian zones.

Do the arithmetic in UTC and convert at the edges. In Pyas, the timezone you pass to meetingTimes.find is the zone slots line up with, usually the host's. Slot times come back in UTC, and your page renders them in the guest's browser zone. Every event you read has startsAt and endsAt in UTC, startsAtLocal, and an IANA timezone, whatever Google or Outlook stored.

Two guests, one slot

Free/busy is a read. Nothing holds the time between showing a slot and creating the event, so two guests can pick the same 10:00, and the host can fill it from their phone in between.

Retries are the other source of duplicates, because a create that timed out may have succeeded. Graph has transactionId "to avoid redundant POST operations in case of client retries to create the same event." Google lets you choose the event id, unique per calendar, but warns "we cannot guarantee that ID collisions will be detected at event creation time."

What holds up:

1. Insert the booking row first, with a unique constraint on host and start time (or an exclusion constraint on the time range if slot lengths vary). The second guest fails here, before any event exists.
2. Read the slot again with freeBusy.query. This catches events the host added in their calendar.
3. Create the event with your booking id as the idempotency key. Pyas keeps the answer for 24 hours and replays it, so a retried create returns the first event.

Guests outside the organization

Booking guests are rarely in the host's company, and many use neither Google nor Outlook. They connect nothing. Each booking is an event on the host's calendar with the guest as an attendee, so the guest receives a normal invitation from the host's calendar and can accept it in whatever calendar they use.

On Microsoft, "When you create an event that includes attendees, the server sends invitations to all attendees", and this "can't be configured" (Create event). On Google, sendUpdates defaults to false, and attendees get an email only when you set it to all or externalOnly. Pyas asks Google to send invitations unless you pass notifyAttendees: false, so the guest gets one on either provider. Booking from a Google service account fails differently: service accounts cannot invite attendees without domain-wide delegation.

Meeting links

Each provider has its own mechanism. Google Meet needs conferenceDataVersion=1 and a createRequest, and Google creates conferences asynchronously, so the first response can say pending. Graph creates a Teams meeting when you set onlineMeetingProvider to teamsForBusiness, and after that "you can't change onlineMeetingProvider again" (event resource). On Outlook.com calendars, the event saves without a Teams link.

In Pyas it is one field, conferencing: { provider }: meet on Google, teams on Outlook work accounts, zoom on either once the host connects Zoom. Pyas creates the Zoom meeting and puts the link on the event. Teams on an Outlook.com account is refused with an error that says why, so offer those hosts Zoom. More in meeting links for Meet, Teams and Zoom.

Reschedules and cancellations happen in the calendar

Your booking record goes stale the moment the host drags the meeting to Thursday in Google Calendar, deletes it in Outlook, or the guest declines. Outlook guests can also propose a new time, because Graph's allowNewTimeProposals defaults to true.

Google's push notifications "do not include a message body", and "there's no automatic way to renew a notification channel" (push guide). Graph subscriptions on Outlook events last at most 10,080 minutes, under seven days. A deleted Google event still reads back, with status cancelled.

Pyas keeps Google's channels and Graph's subscriptions renewed and sends a signed webhook per change, event.updated or event.deleted. Webhooks carry IDs, not previous values, so compare the event with your booking: a different startsAt is a reschedule. Changes made through your own API calls carry request.traceId, so you can skip them.

When your app moves a booking, pass the version you read, so a change the host made in the meantime isn't overwritten:

const current = await pyas.events.get({ accountId, eventId })
await pyas.events.update(
    { accountId, eventId, startsAt: newSlot.startsAt, endsAt: newSlot.endsAt },
    { ifMatch: current.version },
)

On Outlook, updating the description removes the Teams join link, so leave the description alone on a reschedule unless you rebuild it.

Connecting hosts

With Pyas Auth you skip Google's OAuth review, but under Microsoft's default consent policy, work accounts can still need an administrator's approval. When a host's connection stops working, connection.broken fires; stop offering their slots until they reconnect.

What you build yourself

Pyas is an API. It has no booking pages and no round-robin, and beyond the calendar invitation it sends no email. The booking page, the guest form, confirmations, reminders, payments and routing between hosts are yours. It covers Google Calendar, Microsoft 365, Outlook.com and Zoom, not iCloud or on-premises Exchange.