Propose, then book
An invite reaches every attendee the moment the event is created, so the order
is fixed: know the user's calendar, find slots, show them, and create the event
only once a slot is chosen.
1. Read the calendar through the question tool
query_email_and_calendar answers "what is on my calendar Thursday", "when is
my next call with Acme", and "am I free Friday afternoon". It reads mail and
calendar together, so it also finds the thread where a meeting was proposed.
The account matters: list_accounts first, and ask with acting_email when
the meeting belongs to an inbox other than the primary one.
2. Find slots, in the right time zone
get_availability takes participant emails, a window, and a duration, and
returns free slots. Pass timezone when the user named one or the participants
span zones, and write the window as RFC3339 with an offset, because a bare date
is a guess. It keeps to 9 to 5 in the user's zone by default; set
working_hours_only: false when the user asked for evenings or another zone's
hours.
Offer two or three slots with the day, time, and zone written out, and stop.
3. Create the event once a slot is chosen
create_or_update_event needs title, start, end, and timezone. Add
attendees for the people to invite, conference: true for a video link, a
description with context from the thread, and location for anything in
person. Attendees go on the event only when the user asked to invite them,
because the invite goes out on creation. Pass event_id to move or edit an
event. A recurrence can only be set when the event is created, and editing a
recurring event changes its first occurrence only. A new event takes up to a
minute to show up in queries, so do not re-query to confirm it.
Report the event as created: title, time with zone, attendees, and whether a
conference link was added.
Anti-patterns
- Creating the event to show the user the options. Proposals are text; the
event is the booking.
- Assuming the user's time zone for someone else. Name the zone in every
slot.
- Inviting the whole thread. Attendees are the people the user named.
- Booking outside the window the user gave. Widen the search only when the
user agrees there was nothing inside it.