📅 Google Calendar Appointment AI Agent

An intelligent, conversational appointment booking system that integrates with Google Calendar and Google Sheets — built with n8n, OpenAI GPT-4o-mini, and Google Workspace APIs.

---

📌 Project Overview

This project is a fully functional AI-powered appointment scheduling agent designed for healthcare and service-based businesses. Patients interact with a natural language chat interface to book, check, and manage appointments. The agent validates real-time availability on Google Calendar, confirms bookings with the patient before finalizing, and automatically logs patient records to Google Sheets — all without any manual intervention.

Built as part of an applied AI consulting portfolio under the Black Elephant AI Learning Ecosystem.

---

🎯 Key Features

• 💬 Conversational Booking Flow — Patients book appointments through a friendly chat interface powered by GPT-4o-mini
• 📆 Real-Time Availability Check — Queries Google Calendar live to confirm open slots before booking
• ✅ Confirmation-First Logic — Agent never books without receiving explicit patient confirmation
• 🗓️ Automatic Calendar Event Creation — Creates Google Calendar events instantly upon confirmation
• 📊 Patient Records Logging — Appends Name, Phone Number, and Appointment Date/Time to Google Sheets automatically
• 🌍 Timezone-Aware Scheduling — Fully configured for Asia/Kuwait (UTC+3) timezone
• 🧠 Session Memory — Window Buffer Memory maintains context across a multi-turn conversation
• 🔒 Office Hours Enforcement — Agent only offers slots within defined working hours (Mon–Fri 9AM–8PM, Sat 9AM–1PM)
• 🚫 Conflict Prevention — 15-minute buffer between consultations built into availability logic

---

🏗️ Architecture

Patient Chat UI (n8n Public Webhook)
        │
        ▼
┌─────────────────────────────────────────────────────┐
│                    AI Agent Node                    │
│           (GPT-4o-mini + System Prompt)             │
│                                                     │
│  ┌──────────────┐  ┌───────────┐  ┌─────────────┐  │
│  │    Check     │  │   Create  │  │   Add Data  │  │
│  │ Availability │  │   Event   │  │  (Sheets)   │  │
│  │  (GCal Tool) │  │(GCal Tool)│  │(Sheets Tool)│  │
│  └──────────────┘  └───────────┘  └─────────────┘  │
└─────────────────────────────────────────────────────┘
        │                    │                │
        ▼                    ▼                ▼
 Google Calendar      Google Calendar    Google Sheets
 (Availability)       (Event Created)   (Patient Record)

Memory: Window Buffer Memory (session-scoped conversation history)

---

🛠️ Tech Stack

Component	Technology
Workflow Orchestration	n8n (Self-Hosted, Docker)
AI / LLM	OpenAI GPT-4o-mini
Calendar Integration	Google Calendar API (OAuth2)
Records Storage	Google Sheets API (OAuth2)
File Access	Google Drive API (OAuth2)
Memory	n8n Window Buffer Memory
Deployment	Docker (local), n8n Webhook (public chat UI)

---

🔄 Workflow Breakdown

Trigger

• Chat Trigger Node — Exposes a public webhook URL with a chat UI (/webhook/.../chat). Patients interact here in real time.

AI Agent

• Powered by GPT-4o-mini with a detailed system prompt defining:
  • Office hours and consultation rules
  • Booking process steps (collect info → check → confirm → book)
  • Tool usage instructions
  • Timezone enforcement (Asia/Kuwait, UTC+3)
  • Date formatting requirements (YYYY-MM-DDTHH:mm:ss+03:00)

Tools Available to the Agent

Tool	Node Type	Purpose
Check Availability	Google Calendar Tool	Queries free/busy slots for a given time range
Creat event	Google Calendar Tool	Creates a 1-hour appointment event
Add data	Google Sheets Tool	Appends patient record row to Sheet1

Memory

• Window Buffer Memory — Keyed by sessionId from the chat trigger, enabling multi-turn conversations without losing context.

---

⚙️ Setup & Configuration

Prerequisites

• n8n instance (self-hosted via Docker recommended)
• OpenAI API key
• Google Cloud Project with the following APIs enabled:
  • Google Calendar API
  • Google Sheets API
  • Google Drive API
• OAuth2 credentials configured in Google Cloud Console
• A Google Sheet named AI_records with headers: Name | Number, | Date/Hours.

n8n Docker Setup

# Start existing container
docker start n8n

# Or create fresh (with persistent volume)
docker run -d \
  --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

# Access at
http://localhost:5678

Import Workflow

1. Open n8n → Workflows → Import from file
2. Upload Appointment-AI-Agent.json
3. Configure credentials:
   • OpenAI API key
   • Google Calendar OAuth2 account
   • Google Sheets OAuth2 account
4. Update the calendar field in Check Availability and Creat event nodes to your Google Calendar email
5. Update the documentId in Add data to your Google Sheet ID
6. Publish the workflow to activate the public webhook

Google Cloud OAuth Setup

1. Create a project in Google Cloud Console
2. Enable: Google Calendar API, Google Sheets API, Google Drive API
3. Create OAuth 2.0 Client ID (Web Application type)
4. Add Authorized Redirect URI: http://localhost:5678/rest/oauth2-credential/callback
5. Add scopes: calendar, spreadsheets, drive
6. Connect credentials in n8n via Settings → Credentials

---

🤖 Agent System Prompt Highlights

🕒 Office Hours
Monday - Friday: 9:00 AM - 8:00 PM
Saturday: 9:00 AM - 1:00 PM
Sunday: ❌ Closed

Consultation Duration: 1 hour
Break Between Patients: 15 minutes

🌍 Timezone: Asia/Kuwait (UTC+3)
Date format: YYYY-MM-DDTHH:mm:ss+03:00

The agent is instructed to:

1. Collect Full Name, Phone Number, and Desired Date/Time
2. Check real availability via Google Calendar
3. Never confirm without patient approval
4. Book the event and log the record simultaneously

---

📸 Screenshots

Chat Interface

Patients interact via a clean, minimal chat UI served directly from the n8n webhook.

Google Calendar

Appointments appear automatically with event title, description, and duration.

Google Sheets Records

Patient data is logged in real time: Name, Phone Number, Appointment Timestamp.

---

🐛 Known Issues & Resolutions

Issue	Root Cause	Fix
Forbidden - caller does not have permission	Google Drive API not enabled	Enable Drive API in Google Cloud Console
Wrong timezone on calendar events	LLM defaulting to UTC-4	Added timezone instructions + +03:00 format in system prompt
Could not retrieve column data	Google Sheet had no headers	Added header row: Name, Number, Date/Hours
403 - Could not load list	Google Drive API disabled	Enabled Drive API in GCP project

---

🚀 Future Enhancements

• SMS/WhatsApp confirmation via Twilio integration
• Appointment cancellation and rescheduling flow
• Multi-doctor support with separate calendars
• Analytics dashboard (appointment volume, peak hours)
• Email confirmation node post-booking
• Deployment to cloud (Railway / Render) for 24/7 availability

---

👩‍💻 Author

Swati Rai
HR Professional turned AI Entrepreneur | Applied AI Consultant
Building enterprise-grade AI automation solutions

🔗 GitHub

---

📄 License

MIT License — free to use, modify, and distribute with attribution.

---

Built with n8n + OpenAI + Google Workspace as part of the Black Elephant AI Learning Ecosystem applied project curriculum.