A Google Calendar chatbot integration should do three things reliably: read busy periods without exposing private event details, create a confirmed event exactly once, and preserve the same meeting instant for people in different time zones. OAuth is only the connection step; production quality comes from everything around it.
This guide explains the architecture for business owners and implementers. It also separates a chatbot integration from Google Calendar’s own appointment schedule feature, because the two solve related but different problems.
Chatbot integration or Google booking page?
| Need | Google appointment schedule | Calendar-connected chatbot |
|---|---|---|
| Pick a known service and open slot | Strong fit | Strong fit |
| Ask questions before booking | Visitor leaves the conversation for a booking page | Assistant can answer and qualify in context |
| Collect dynamic intake | Configured booking-page fields | Fields can vary by service and conversation |
| Book through voice | Not the primary interaction | Can share the same structured booking workflow |
| Keep chat transcript with lead | Separate system | Can link conversation, lead, and appointment |
Google’s appointment schedules let businesses publish availability, embed a booking page, block busy times, and add confirmed appointments to Calendar. See Google’s official appointment schedules overview. A chatbot integration is valuable when the visitor needs guidance before choosing a slot or when chat and voice should use one intake flow.
The production architecture
- The signed-in business owner starts OAuth from the assistant’s settings.
- The server verifies a short-lived, signed OAuth state tied to that owner and assistant.
- Calendar credentials are stored server-side and never sent to the visitor widget.
- The widget asks your application’s availability endpoint for one service, date, and visitor time zone.
- The server combines business rules, internal bookings, and external busy periods.
- After explicit visitor approval, the server verifies the slot again and creates the internal booking.
- The calendar event is created with the canonical instant, attendee details, and a stable provider identifier.
Use the narrowest useful Google permissions
Request only the scopes needed for the promised behavior. Reading free/busy information and creating events is different from unrestricted calendar management. Explain the reason before sending the owner into Google’s consent flow and show the connected account afterward.
- Bind the OAuth callback to the initiating user and assistant.
- Reject expired, tampered, or replayed state.
- Encrypt refresh tokens at rest and keep them out of logs.
- Provide an explicit disconnect action.
- Treat revoked access as a visible integration state, not an endless retry loop.
Read availability without leaking event data
A visitor needs to know that 2:30 PM is unavailable, not why. Convert provider events into time ranges on the server and return only the resulting bookable slots. Include every calendar that should block the resource, but do not assume a co-host’s calendar is checked automatically.
Google explains that busy events on selected calendars remove those times from availability, while calendars excluded from conflict checking do not. Its guide to availability across calendars is a useful configuration reference.
| Source | What it contributes |
|---|---|
| Business schedule | Working periods, service duration, notice, horizon, and buffers |
| Internal bookings | Appointments created even if the provider sync is delayed |
| Google busy periods | Meetings and blocks created outside the chatbot |
| Blocked dates | Holidays, leave, and one-off closures |
Keep time-zone handling explicit
Store the appointment as an absolute instant and retain both the business and visitor IANA time-zone identifiers. The Google Calendar API uses IANA identifiers for calendar and event time zones, as described in its calendar and events documentation.
- Resolve natural-language dates only after the visitor time zone is known.
- Validate that the requested wall-clock time exists; some local times disappear during daylight-saving changes.
- Never convert by manually adding or subtracting a fixed number of hours.
- Render confirmation text separately for the visitor and business owner.
- Use the same canonical instant in the database, provider event, email, and calendar attachment.
Prevent duplicates and race conditions
Two visitors can view the same slot before either confirms it. A correct availability response is not a reservation. At confirmation, acquire a database-level guarantee or perform an atomic conflict check before inserting the booking. Then reuse one idempotency key for every retry of that confirmed draft.
| Failure | Safe response |
|---|---|
| Slot became busy | Keep entered details and offer fresh alternatives |
| Internal booking succeeded, Google timed out | Report sync status internally and retry without duplicating the booking |
| Google event succeeded, response was lost | Reconcile by provider/idempotency identifier before creating another event |
| Refresh token revoked | Mark integration disconnected and stop claiming external availability is checked |
What Chirps does when Google Calendar is optional
Internal calendar first, external calendar when connected
Chirps always records confirmed appointments in its own booking calendar. When Google Calendar is connected, availability also considers external busy periods and confirmed meetings can be synchronized. If external availability cannot be verified, the booking endpoint fails safely instead of publishing guessed slots.
The conversational layer can prefill a booking artifact, but the server remains responsible for dates, availability, access control, and final confirmation. See the booking configuration guide.
Go-live test matrix
- Owner connects the intended Google account and returns to the correct assistant.
- A private Google event blocks time without revealing its title.
- An internal Chirps booking blocks time before external synchronization completes.
- A visitor in another region sees the correct local time.
- A daylight-saving boundary preserves the same instant for both attendees.
- A repeated confirmation creates one booking and one Google event.
- Revoked Google access produces a clear reconnect state.
- Disconnecting Google leaves the internal booking calendar usable.