Google Calendar

The Google Calendar integration allows assistants to check availability and create appointments directly in the conversation, without the user needing to access any other interface.

Available Actions

Action	Description
`CHECK`	Checks if a specific time slot is available
`LIST`	Lists the next available events
`SCHEDULE`	Creates a new event/appointment

`CHECK`: Check Availability

Checks whether a specific time slot is free on the calendar:

json

{
  "type": "GOOGLE_CALENDAR",
  "subtype": "CHECK",
  "start": "startDateTime",
  "end": "endDateTime",
  "calendarId": "calendar_id"
}

The LLM extracts startDateTime and endDateTime from the conversation and the parameters are substituted automatically.

Response returned:

json

{
  "available": true,
  "conflicts": []
}

`LIST`: List Availability

Lists the next available time slots in a range:

json

{
  "type": "GOOGLE_CALENDAR",
  "subtype": "LIST",
  "start": "startDate",
  "end": "endDate",
  "calendarId": "calendar_id",
  "maxResults": 5
}

Response returned:

json

{
  "slots": [
    { "start": "2025-03-10T14:00:00", "end": "2025-03-10T15:00:00" },
    { "start": "2025-03-10T16:00:00", "end": "2025-03-10T17:00:00" }
  ]
}

`SCHEDULE`: Create Appointment

Creates a new event on the calendar:

json

{
  "type": "GOOGLE_CALENDAR",
  "subtype": "SCHEDULE",
  "title": "eventTitle",
  "description": "eventDescription",
  "start": "startDateTime",
  "end": "endDateTime",
  "attendees": ["attendeeEmail"],
  "calendarId": "calendar_id"
}

The Role of `${{horario}}`

The built-in variable ${{horario}} inserts the current date and time into the assistant's prompt. This is essential for the LLM to correctly calculate relative dates:

Assistant's CustomPrompt:
"Current time reference: ${{horario}}

Use this reference to calculate dates when the user says:
'tomorrow', 'next week', 'next Monday', 'in 2 days', etc.

Always convert to ISO 8601 format before calling the trigger."

Without ${{horario}}, the LLM may calculate dates incorrectly because it doesn't know the exact current date.

Full Example: Scheduling Assistant

Prompt:

You are a virtual receptionist for a medical office.
Your goal is to schedule appointments efficiently.

Time reference: ${{horario}}

Process:
1. Ask for the desired specialty
2. Check available time slots (LIST)
3. Present up to 3 options to the patient
4. Confirm name and email
5. Create the appointment (SCHEDULE)
6. Send confirmation to the patient

Trigger 1: Check availability:

json

{
  "name": "check_availability",
  "description": "Lists available time slots for an appointment. Use after the patient informs the desired specialty and when they want to schedule.",
  "parameters": {
    "properties": {
      "specialty": { "type": "string" },
      "preferred_date": { "type": "string", "description": "Date in ISO 8601 format" }
    },
    "required": ["specialty"]
  },
  "action": {
    "type": "GOOGLE_CALENDAR",
    "subtype": "LIST",
    "start": "preferred_date",
    "calendarId": "calendar_$specialty"
  },
  "interpretResponse": true
}

Trigger 2: Create appointment:

json

{
  "name": "confirm_appointment",
  "description": "Creates the appointment after the patient confirms the time slot, name, and email. ONLY use when the patient explicitly confirms.",
  "parameters": {
    "properties": {
      "patient_name": { "type": "string" },
      "patient_email": { "type": "string" },
      "datetime": { "type": "string", "description": "ISO 8601" },
      "specialty": { "type": "string" }
    },
    "required": ["patient_name", "datetime", "specialty"]
  },
  "action": {
    "type": "GOOGLE_CALENDAR",
    "subtype": "SCHEDULE",
    "title": "$specialty Appointment: $patient_name",
    "attendees": ["patient_email"],
    "start": "datetime"
  },
  "interpretResponse": true
}