Step 4 — Calendar booking

#Setting up calendar booking

#Step 1: Google Calendar API

1. Go to console.cloud.google.com
2. Create a new project → Enable Calendar API
3. Create OAuth 2.0 credentials
4. Download the credentials.json file

#Step 2: The booking function

from googleapiclient.discovery import build
from google_auth_oauthlib.flow import InstalledAppFlow
import datetime

SCOPES = ["https://www.googleapis.com/auth/calendar"]

def book_viewing(lead, agent_email):
    flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
    creds = flow.run_local_server(port=0)
    service = build("calendar", "v3", credentials=creds)

    # Check agent's availability for next 3 days
    now = datetime.datetime.utcnow().isoformat() + "Z"
    events = service.events().list(
        calendarId=agent_email,
        timeMin=now,
        maxResults=10,
        singleEvents=True,
        orderBy="startTime",
    ).execute()

    free_slots = find_free_slots(events["items"], lead["timeline"])

    # Create the event
    event = {
        "summary": f"Property viewing — {lead['name']}",
        "location": lead["property_address"],
        "description": f"Viewing for {lead['name']} (Bayut lead). Budget: {lead['budget']}.",
        "start": {
            "dateTime": free_slots[0].isoformat(),
            "timeZone": "Asia/Dubai",
        },
        "end": {
            "dateTime": (free_slots[0] + datetime.timedelta(hours=1)).isoformat(),
            "timeZone": "Asia/Dubai",
        },
        "attendees": [{"email": lead["email"]}, {"email": agent_email}],
        "reminders": {
            "useDefault": False,
            "overrides": [
                {"method": "email", "minutes": 24 * 60},
                {"method": "popup", "minutes": 10},
            ],
        },
    }

    event = service.events().insert(calendarId=agent_email, body=event).execute()
    return event.get("htmlLink")

#Step 3: What times to offer

Don't ask the lead "when are you free?" — that creates back-and-forth. Instead, offer 3 specific times:

1. Today 3pm or 5pm (urgent — creates scarcity)
2. Tomorrow 10am (backup option)
3. Tomorrow 2pm (alternative)

The AI should say: "I can get you in today at 3pm or 5pm, or tomorrow at 10am. Which works?"

#Gotchas

1. Time zone — always use Asia/Dubai explicitly
2. Working hours — only offer 9am–8pm slots (agents' active hours)
3. Conflict detection — check the agent's calendar for conflicts before proposing
4. Rescheduling — include a reschedule link in the calendar invite (Google Calendar has built-in rescheduling)
5. Property address — you need the actual property address, not just the reference number. Parse it from the portal email or scrape it from the listing page.

#The handoff rule

After booking, send:

• Calendar invite to the lead
• SMS confirmation (Twilio) with the agent's name and property address
• CRM record with all conversation history
• Agent notification email with lead details + viewing link

This triple-channel confirmation has a 94% attendance rate for booked viewings.