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

# Calendar Booking Stage

> Schedule appointments directly within conversations

The **Calendar Booking** stage integrates appointment scheduling into your voice agent. Callers can check availability, book, cancel, or reschedule appointments.

## Overview

Calendar Booking nodes connect to your calendar system to:

* Check available time slots
* Book new appointments
* Cancel existing bookings
* Reschedule appointments
* Look up appointment details

<Info>
  Calendar Booking nodes are colored **green with purple accents** and are inherently global (available throughout the flow).
</Info>

## Configuration

### Enabled Operations

Select which calendar operations this node can perform:

| Operation            | Description                     |
| -------------------- | ------------------------------- |
| `check_availability` | Find available time slots       |
| `book`               | Create a new appointment        |
| `cancel`             | Cancel an existing appointment  |
| `update`             | Reschedule an appointment       |
| `find`               | Look up an existing appointment |

Enable only the operations needed for your use case.

### Duration

Appointment length in minutes (15-480).

```yaml theme={null}
Duration: 30  # 30-minute appointments
```

### Appointment Type

Label for the type of appointment:

```yaml theme={null}
Appointment Type: "Consultation"
# or
Appointment Type: "Demo Call"
# or
Appointment Type: "Support Session"
```

### Confirmation Settings

| Setting                     | Description                                     |
| --------------------------- | ----------------------------------------------- |
| **Require Confirmation**    | Ask caller to confirm before booking            |
| **Auto Check Availability** | Automatically check slots before offering times |
| **Days to Check**           | How far ahead to look (1-90 days)               |

### Business Hours

Define when appointments can be scheduled:

```yaml theme={null}
Business Hours:
  Start: "09:00"
  End: "17:00"
```

### Messages

| Message             | When Used                      |
| ------------------- | ------------------------------ |
| **Success Message** | Booking completed successfully |
| **Failure Message** | Booking could not be completed |

## Transitions

Calendar Booking nodes have operation-specific transitions:

| Transition              | Trigger                         |
| ----------------------- | ------------------------------- |
| `BOOKING_SUCCESS`       | Appointment booked successfully |
| `BOOKING_FAILED`        | Booking operation failed        |
| `SLOT_AVAILABLE`        | Available slots found           |
| `SLOT_UNAVAILABLE`      | No slots available              |
| `APPOINTMENT_FOUND`     | Existing appointment located    |
| `APPOINTMENT_NOT_FOUND` | No matching appointment         |

## Example Configurations

<AccordionGroup>
  <Accordion title="Simple Booking Flow">
    ```yaml theme={null}
    Operations: [check_availability, book]
    Duration: 30 minutes
    Type: "Consultation"
    Require Confirmation: true
    Auto Check: true
    Days to Check: 14
    Business Hours: 09:00 - 17:00

    Success Message: |
      Your appointment is confirmed for {{appointment_time}}.
      You'll receive a confirmation email shortly.

    Failure Message: |
      I'm sorry, I couldn't complete the booking.
      Would you like to try a different time?

    Transitions:
      - BOOKING_SUCCESS → End Call (Success)
      - BOOKING_FAILED → Conversation (Retry)
      - SLOT_UNAVAILABLE → Conversation (Alternatives)
    ```
  </Accordion>

  <Accordion title="Full Calendar Management">
    ```yaml theme={null}
    Operations: [check_availability, book, cancel, update, find]
    Duration: 60 minutes
    Type: "Service Appointment"
    Require Confirmation: true
    Auto Check: true
    Days to Check: 30
    Business Hours: 08:00 - 18:00

    Success Message: |
      Done! Your appointment details have been updated.

    Failure Message: |
      I encountered an issue. Let me connect you with
      our scheduling team.

    Transitions:
      - BOOKING_SUCCESS → Confirmation Node
      - BOOKING_FAILED → Human Transfer
      - APPOINTMENT_NOT_FOUND → Data Extraction (get details)
    ```
  </Accordion>

  <Accordion title="Availability Check Only">
    ```yaml theme={null}
    Operations: [check_availability]
    Duration: 45 minutes
    Days to Check: 7
    Business Hours: 10:00 - 16:00

    Transitions:
      - SLOT_AVAILABLE → Data Extraction (collect info)
      - SLOT_UNAVAILABLE → Conversation (offer callback)
    ```
  </Accordion>
</AccordionGroup>

## Conversation Flow Example

Here's how a typical booking conversation flows:

```
Agent: "I can help you schedule an appointment. What day works best for you?"
Caller: "How about next Tuesday?"
Agent: "Let me check availability for Tuesday... I have openings at 10 AM,
        2 PM, and 4 PM. Which would you prefer?"
Caller: "2 PM works"
Agent: "Great! I have you down for Tuesday at 2 PM for a 30-minute
        consultation. Should I confirm this booking?"
Caller: "Yes, please"
Agent: "Your appointment is confirmed for Tuesday, January 15th at 2 PM.
        You'll receive a confirmation email shortly. Is there anything else?"
```

## Integrating with Data Extraction

Combine Calendar Booking with Data Extraction for complete flows:

```
┌─────────────────┐
│  Data Extract   │
│  - name         │
│  - email        │
│  - date pref    │
└────────┬────────┘
         │ all_extracted
         ▼
┌─────────────────┐
│Calendar Booking │
│  check & book   │
└────────┬────────┘
         │ BOOKING_SUCCESS
         ▼
┌─────────────────┐
│    End Call     │
│  Confirmation   │
└─────────────────┘
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Confirm Before Booking" icon="circle-check">
    Always enable confirmation to prevent accidental bookings.
  </Card>

  <Card title="Offer Alternatives" icon="list">
    When preferred times aren't available, suggest 2-3 alternatives.
  </Card>

  <Card title="Set Realistic Windows" icon="clock">
    Don't offer times too far in advance. 2 weeks is usually sufficient.
  </Card>

  <Card title="Handle Failures" icon="shield">
    Always have a fallback path for booking failures (human transfer or callback).
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card title="Data Extraction" icon="clipboard-list" href="/agent-builder/stages/data-extraction">
    Collect customer info before booking
  </Card>

  <Card title="Transitions" icon="arrow-right" href="/agent-builder/transitions">
    Handle booking outcomes
  </Card>

  <Card title="End Call" icon="phone-slash" href="/agent-builder/stages/end-call">
    Confirm successful bookings
  </Card>
</CardGroup>