> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Appointment Booking

> Check calendar availability and book appointments directly during a voice call.

# Appointment Booking

The **Appointment Booking** tool lets your voice agent check calendar availability and book appointments in real time during a call. It integrates with Google Calendar or your own scheduling API.

## How It Works

```
Caller: "I'd like to schedule a consultation."
Agent: "I'd be happy to help! What date works best for you?"
Caller: "How about next Tuesday?"
-> Agent calls check_availability with date="2026-03-10"
Agent: "I have slots available at 9:00 AM, 10:00 AM, 11:00 AM, 2:00 PM, and 3:00 PM. Which works best?"
Caller: "2 PM please."
Agent: "And may I have your name and email?"
Caller: "John Smith, john@example.com"
-> Agent calls book_appointment with date, time, name, email
Agent: "Your consultation is confirmed for Tuesday, March 10th at 2:00 PM. You'll receive a confirmation email shortly."
```

## Configuration

```json theme={null}
{
  "appointmentBookingEnabled": true,
  "appointmentCalendarId": "primary",
  "appointmentDuration": 30,
  "appointmentTimezone": "America/New_York",
  "appointmentBufferMinutes": 15,
  "appointmentConfirmationMessage": "Your appointment has been booked for {date} at {time}."
}
```

| Setting                          | Type    | Default                                                    | Description                                     |
| -------------------------------- | ------- | ---------------------------------------------------------- | ----------------------------------------------- |
| `appointmentBookingEnabled`      | boolean | `false`                                                    | Enable appointment booking                      |
| `appointmentCalendarId`          | string  | —                                                          | Google Calendar ID or custom calendar reference |
| `appointmentDuration`            | integer | `30`                                                       | Default appointment duration in minutes         |
| `appointmentTimezone`            | string  | `America/New_York`                                         | Timezone for scheduling                         |
| `appointmentBufferMinutes`       | integer | `15`                                                       | Buffer between appointments                     |
| `appointmentConfirmationMessage` | string  | `"Your appointment has been booked for {date} at {time}."` | Confirmation message template                   |

## LLM Tools

### `check_availability`

Check available appointment slots for a given date.

```
Parameters:
  date: string (YYYY-MM-DD format)

Returns: "Available slots for 2026-03-10: 9:00 AM, 10:00 AM, 11:00 AM, 2:00 PM, 3:00 PM (America/New_York). Each slot is 30 minutes."
```

### `book_appointment`

Book an appointment at the specified date and time.

```
Parameters:
  date: string (YYYY-MM-DD format)
  time: string (HH:MM format)
  caller_name: string (attendee's name)
  caller_email: string (optional, for confirmation email)
  notes: string (optional, appointment notes)

Returns: "Your appointment has been booked for 2026-03-10 at 14:00."
```

## Example — Create Agent with Appointment Booking

```bash theme={null}
curl -X POST https://api.thinnest.ai/v1/agents \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Scheduling Assistant",
    "model": "gpt-4o-mini",
    "instructions": "You help callers book consultations. Check availability first, confirm all details (date, time, name, email), then book. Default duration: 30 minutes.",
    "voiceEnabled": true,
    "transcriber": { "provider": "deepgram", "model": "nova-2-conversationalai" },
    "voice": { "provider": "deepgram", "voiceId": "aura-2-thalia-en" },
    "appointmentBookingEnabled": true,
    "appointmentCalendarId": "primary",
    "appointmentDuration": 30,
    "appointmentTimezone": "America/New_York",
    "appointmentBufferMinutes": 15,
    "appointmentConfirmationMessage": "Your appointment has been booked for {date} at {time}."
  }'
```