Keeping the Booking Calendar and the AI Front Desk in Sync

Four steps, in this order, every time.

1. Read availability with a version token. Fetch free slots and ask the calendar for a token or last-modified value that describes the state you read. Google Calendar exposes this through its API sync tokens and etag values; most scheduling providers offer something similar. Store the token alongside the proposed slots. If the token is missing, you cannot detect a stale read, and the hold in step 2 becomes a guess.

2. Place a short hold. Because step 1 is a read, it guarantees nothing. Two callers can see the same empty slot. A hold marks the slot unavailable for a short window, say 120 seconds, while the agent finishes collecting the caller's name, phone number and reason. Holds live in your own database with a slot_id, hold_id, expires_at and the request that created them. Holds are cheap and self-cleaning: anything past expires_at is ignored on read and swept by a job.

3. Commit with an idempotency key. The commit request carries a key derived from the conversation and the intent, for example a hash of the agent conversation ID plus the chosen slot. The booking service records the key before calling the calendar. If the calendar call times out and the agent retries, the service sees the key, returns the recorded result, and does not create a second event. Stripe documents this pattern clearly for payments: a client generates a unique key, retries with the same key, and the server returns the original response instead of executing again in the Stripe API reference. Booking is the same problem with a different noun. The key is subject to the same rules Stripe states: keys are meant for a single retry of one operation, not for reuse across different bookings.

4. Confirm and write back. After the calendar confirms the event, persist the event ID and ETag, send the confirmation, and record the full request and response. The confirmation message is not decoration: it is your evidence that the agent and the calendar agree.

The same shape applies to cancellations, with the key used in reverse. A cancel request carries a cancel key, the service marks its own record cancelled before calling the calendar, and a retry with the same key finds the record and skips the duplicate call. If you have ever wondered why an API is worth designing around rather than around a screen, the short version is that an API is a defined contract between two programs as AWS describes APIs; a contract you control is what lets you enforce idempotency, holds and confirmations in one place instead of in twelve prompt variations.

A minimal commit handler in pseudo-code:

def commit_booking(request):
    key = request.idempotency_key
    record = store.get_by_key(key)
    if record:                      # a retry, not a new booking
        return record.result
    hold = store.get_hold(request.hold_id)
    if not hold or hold.expires_at < now():
        raise SlotExpired
    store.reserve(key, hold.slot_id)   # write the key BEFORE the call
    event = calendar.create_event(     # may fail or time out
        start_utc=hold.start,
        end_utc=hold.end,
        tz=hold.iana_zone,
        idempotency_key=key,
    )
    store.complete(key, event.id, event.etag)
    return event

The ordering matters. Writing the key before the external call means a crash mid-call leaves a record you can inspect, not a missing booking. A record stuck in reserved state past a timeout is exactly what the reconciliation job is for.

Race conditions and stale reads

A race condition here is two commits for one slot. Holds close most of the window, and the calendar's own conflict response closes the rest if you handle it. Many calendar APIs reject overlapping events on the same resource, or will if configured to. Treat the conflict response as a normal outcome, not an error: release the hold, re-read availability, offer the next slot. A stale read is subtler. The agent saw 9:00 as free because its availability snapshot was taken at call start, and the caller spent four minutes discussing insurance. Re-check slots inside the hold step, not once at the top of the call.

Partial writes

A partial write is when one side of the transaction succeeds. The calendar gets the event but your database loses the response to a timeout; or your database records the booking and the calendar call never landed. You cannot eliminate this without a two-phase commit across two systems you do not both own, so you detect it instead. Every partial write shows up as a mismatch between the agent's request log and the calendar, which is what reconciliation is for.

Time zone and DST edges

Most time zone bugs are not exotic. They come from storing a local time like "Tuesday 3:00" with no zone, then having two systems interpret it differently, or from naively adding days across a daylight saving boundary. Store the zone once, as an IANA identifier (America/New_York, Europe/London, Asia/Kolkata) on the event and in your own record. Do every comparison in UTC: the hold, the slot overlap test, the reminder schedule. Render to the caller's local time only when you speak the confirmation.

DST is where the arithmetic bites. When clocks go back, one wall-clock hour repeats, so 01:30 happens twice locally. When clocks go forward, an hour does not exist. A "24 hours before the appointment" reminder computed as "same wall-clock time yesterday" can land an hour early, an hour late, or on a time that never occurs. The fix is boring: the event's start and end are UTC instants, the reminder is computed in seconds from the start instant, and the zone is attached only for the human-readable label.

Cancellations and no-shows

A cancellation is a write like any other, and it fails like any other. The patient texts "can't make it" at 11:40 PM, the agent cancels, the calendar call times out, the retry duplicates the cancel and the provider returns "event not found," and the slot is still blocked. Idempotent cancel keys plus reconciliation fix this. Also decide up front whether a cancellation frees the slot immediately or puts it back after review; the capability matrix idea of toggling what the agent may do per channel, with cancellations allowed on the phone but held for approval by email, is described well in Elva's write-up on handoff and controls. That is a policy decision, and it belongs in configuration, not in the prompt.

The one control people skip is the last row. Reconciliation is not optional once the agent writes autonomously. It is a job that reads the agent's request log for the window, reads the calendar's events for the same window, and reports records in one and not the other. Run it every few minutes; alert when the mismatch count is above zero for more than one cycle. The reconciliation job also gives you the numbers you need to argue about later, for example how often holds expire without a commit or how many callers hang up during the hold window.

The write path protects the calendar. You also need to protect the caller from an agent that mishears a date. Three controls do most of the work:

1. Spoken confirmation before commit. Read the day, date, time and zone back to the caller and get a yes. This is where "Tuesday the 14th" versus "Thursday the 14th" gets caught.
2. One capability list, per channel. Decide what the agent may do on its own, what it may propose for human approval, and what it must hand off. Receptionist vendors that take handoff seriously structure it this way: capability toggles per channel, review mode where the AI proposes and a person approves before anything writes to the system per this analysis of AI receptionist limits, and defined fallback behavior when a calendar integration is down.
3. A review queue for the first weeks. Route every booking the agent makes to a human-review queue until you have seen a few hundred in production. The insurance isn't that the agent is bad. It is that you learn where it is loose while the blast radius is small; TeleCloud's deployment guidance makes the point that the first bad handoff shows up at the front desk, and that the workflow around the agent decides whether it helps or creates cleanup.

If the agent runs on a model you call over an API, keep the booking tool itself narrow: one function to read availability, one to hold, one to commit, one to cancel. The model's job is to choose intent and fill parameters. Your service's job is to refuse anything that does not fit the contract. If you are wiring several model providers for voice, text and embeddings, Quanta Inference puts them behind one OpenAI-compatible API with prepaid US-dollar pricing, so the integration code does not change when the model does. That is a natural next step once the booking service exists.

If you are starting from nothing this is the sequence that gets you to a trustworthy calendar fastest:

1. The request log. Append-only, one record per agent action, with conversation ID, intent, parameters, idempotency key and outcome. Nothing else works without it.
2. The booking service. Holds, commit, cancel, all with keys. Log every calendar call and its response.
3. The version token and re-check. Availability reads carry a token; commits re-verify inside the hold.
4. UTC everywhere. One conversion layer. Reject any code path that stores a local time without a zone.
5. The reconciliation job. Every few minutes, every mismatch alerted.
6. Review mode. Human approval on writes until you trust the distribution of outcomes.

Step six is the one you remove later. Steps one through five are permanent.

The hidden payoff is the data. Once every booking has a request log, an idempotency key and a reconciliation check, you can answer questions like "how many slots did we lose to expired holds last Tuesday" from the store rather than from a support ticket. That is also the foundation for anything else the front desk wants to automate later, from reminders to follow-ups to a second location with its own time zone.