Text AI Booking Configuration

Overview

To enable your AI agent to book appointments automatically, you need to configure two things:

1. Instructions (Instructions tab) - Tell the agent WHEN it's appropriate to book (after the user provides xyz information) and how to refer to your appointments (i.e. "a quick 15 minute phone call" or "an onsite estimate appointment")
2. Booking Configuration (Booking/Goal tab) - Tell the agent HOW to book (which calendar, which user)

This guide focuses on the Booking/Goal tab configuration, specifically the powerful AI Calendar Selection mode.

Prerequisites

Before configuring booking:

• At least one calendar must exist (Appointments & Calendars page)
• Calendar must have team members assigned
• Calendar must have availability configured
• Agent must have instructions about booking in the Instructions tab

Important: Just configuring booking options isn't enough. Your agent's instructions must tell it when to book appointments.

Example instruction snippet:

3) **Book Appointment**
- After gathering service details and address, tell the user: 
  "Great, sounds like we can help. Let's find a time for one of our 
  specialists to come out. I see these two times available (insert 2 
  available slots). Do either of those work?"

Goal Modes

Neither - No Booking or Goal (Default)

• Agent cannot book appointments
• Use for: Agents that don't need booking capability

Calendar Booking

• Agent can book appointments
• Use for: Agents who need to be able to set appointments on calendars

Completion Goal

• Agent cannot book appointments, but is tasked with some other goal defined by you (ie, gather certain information)
• Use for: Agents that need to qualify without booking, accept service requests, any goal you define, etc.
• See help doc on Completion Goals for more.

Booking Modes (when calendar booking is selected)

Account Default Calendar

• Books into your account's default calendar
• Uses available team members in that calendar
• Distributes appointments based on calendar's user selection strategy

Configuration:

1. Set default calendar in Settings > Business > Defaults
2. Select "Account Default Calendar" as booking mode
3. Save agent

Use When:

• You have one main calendar for all bookings
• Simple, straightforward booking needs
• Want centralized calendar management

Specific Calendar

• Books into one designated calendar
• Uses available team members in that calendar
• Distributes appointments based on calendar's user selection strategy

Configuration:

1. Select "Specific Calendar" as booking mode
2. Choose which calendar from dropdown
3. Save agent

Use When:

• This agent always books into the same calendar
• Simple service-specific calendar (e.g., "HVAC Calendar")
• No complex routing logic needed

AI Calendar Selection

• AI intelligently chooses which calendar to book into (and optionally which user)
• Based on rules you define using contact data
• Most powerful and flexible option

Use When:

• Multiple calendars for different services, territories, or appointment types
• Need to route based on contact information (zip code, service type, etc.)
• Want to select specific users based on criteria
• Complex appointment routing logic

AI Calendar Selection - Detailed Guide

AI Calendar Selection allows you to write rules that the AI follows to determine which calendar and with whom to book appointments.

Accessing Variables

While typing in the "Calendar Selection Instructions field", press the curly bracket key { on your keyboard to open the variable selector.

Available Variables:

Contact Fields:

• Any contact field can be used to make a decision, eg {contact.state}, {contact.zip_code}, or {contact.custom_field_you_created}

Calendars:

• List of all your calendars with their IDs
• Insert calendar ID directly into instructions

Users:

• List of all team members with their IDs
• Insert user ID when you want to book with specific person

User Appointment Counts:

• {users.appointment_counts} gives access to each user's appointment count over a rolling 30-day period across all calendars
• {users.appointment_counts_by_zip} gives access to each user's rolling 30-day appointment counts broken down by the booked contact's zip code
• Use appointment counts when the decision should be based on how many appointments certain users have

AI Selection Scope

Choose what the AI can select:

Calendar Only (Default)

• AI selects which calendar to book into
• Calendar's user selection strategy distributes to team members in that calendar
• Simpler, recommended for most use cases

Calendar and User

• AI selects both calendar AND specific user
• Gives you complete control over routing
• Required if you want user-specific rules

When to Use Each:

Calendar Only:

• Territory-based routing (different calendars per region)
• Service-based routing (different calendars per service type)
• Let calendar distribute among available users automatically

Calendar and User:

• Specific technician specialties
• Workload balancing with custom ratios
• VIP customer routing to senior staff
• Complex assignment logic

Writing Calendar Selection Instructions

Your instructions tell the AI how to choose. Be clear and specific.

Example 1: Territory-Based (Zip Code Routing)

Instructions:

If the contact's zip code ({contact.zip_code}) is one of the following:
11706, 11707, 11708, 11709

Then book into {Calendar ID: abc-123-xyz} (West Territory Calendar)

If the contact's zip code is one of the following:
11710, 11711, 11712, 11713

Then book into {Calendar ID: def-456-uvw} (East Territory Calendar)

Otherwise, book into {Calendar ID: ghi-789-rst} (General Calendar)

Key Points:

• Use the actual contact variable {contact.zip_code}
• Insert calendar IDs using the variable selector (while typing, press { to access)
• Always provide a fallback "otherwise" option

Example 2: Service-Based Routing

Instructions:

If the {contact.service_type} custom field is "HVAC" or contains "air conditioning" or "heating"

Then book into {Calendar ID: abc-123} (HVAC Calendar)

If the {contact.service_type} is "Plumbing" or contains "water" or "drain"

Then book into {Calendar ID: def-456} (Plumbing Calendar)

If the {contact.service_type} is "Electrical"

Then book into {Calendar ID: ghi-789} (Electrical Calendar)

Otherwise, book into {Calendar ID: jkl-012} (General Services Calendar)

Example 3: Calendar + Specific User Selection

Instructions (Scope: Calendar and User):

If the {contact.service_type} is "New Build"

Then book with {User ID: john-123} (John Smith) in {Calendar ID: abc-456} (New Build Calendar)

If the {contact.service_type} is "Remodel" or "Renovation"

Then book with any available user in {Calendar ID: def-789} (Remodel Calendar)

Otherwise, book into {Calendar ID: ghi-012} (General Calendar) with any available user

Key Points:

• Can specify exact user for some scenarios
• Can use "any available user" for others
• Mix specific user selection with automatic distribution

Example 4: Workload Balancing (Advanced)

Instructions (Scope: Calendar and User):

Determine which user to book with based on appointment counts.

{User ID: john-123} (John Smith) should always have 2 more appointments 
than {User ID: joe-456} (Joe Brown).

Book all appointments into {Calendar ID: abc-789} (Main Calendar)

What Happens:

• AI checks current appointment counts
• Books with appropriate user to maintain balance

Load Distribution Variables:

• {users.appointment_counts} should be used for general appointment balancing across all recent appointments.
• {users.appointment_counts_by_zip} should be used when the balancing should only consider appointments from a specific zip list, territory, or zone.

For example, if a territory includes zip codes 11706, 11707, and 11708, {users.appointment_counts_by_zip} lets the script compare how many appointments each user has received in those zip codes only.

Example 5: Mixed Logic (Territory + User Specialty)

Instructions (Scope: Calendar and User):

First, determine territory based on zip code:

If {contact.zip_code} is: 11706, 11707, 11708
Use North Territory

If {contact.zip_code} is: 11709, 11710, 11711  
Use South Territory

Within each territory, if {contact.service_type} contains "commercial":
- North Territory: Book with {User ID: alice-123} in {Calendar ID: north-abc}
- South Territory: Book with {User ID: bob-456} in {Calendar ID: south-def}

For residential ({contact.service_type} does not contain "commercial"):
- North Territory: Book with any user in {Calendar ID: north-abc}
- South Territory: Book with any user in {Calendar ID: south-def}

Otherwise (zip not in any territory), book into {Calendar ID: general-789}

Requirements for AI Selection

Minimum Requirements:

For Calendar Only Scope:

• At least 1 calendar ID must be specified in instructions
• Fallback "otherwise" rule recommended

For Calendar and User Scope:

• At least 1 calendar ID must be specified for every user (you cannot just tell the AI 'book with Joe', you need to tell the AI 'Book with Joe in Calendar XYZ')
• At least 1 specific user selection rule
• Otherwise, just use Calendar Only scope
• When specifying users, ensure users are actually selected in the calendars you are telling the AI to book appointment for them in.

Critical: Data Dependencies

If your booking decision is based on contact data (like zip_code or service_type), you MUST:

1. Configure agent instructions to gather that information

   • Example: "Can you provide your zip code?"

2. Add field extractor to save it

   • Field: zip_code
   • Description: "the user's 5-digit zip code"

Why: If the contact field is empty, the AI can't make the booking decision. The AI will gather the info, field extractor will save it, then AI can book using the rules.

The AI Selection Workflow

Step 1: Write Your Instructions

In the Calendar Selection Instructions field:

1. Press { to access variables
2. Insert contact fields you'll evaluate
3. Insert calendar IDs for booking destinations
4. Insert user IDs if using Calendar and User scope
5. Write clear if/then logic
6. Always include "otherwise" fallback

Step 2: Generate Script

Click "Generate Script" button

The AI will:

1. Analyze your plain-English instructions
2. Explain them back to you to ensure understanding
3. Ask clarifying questions if needed
4. Generate Python code that executes your logic
5. Let you know the script is ready for testing

Step 3: Review AI's Understanding

The AI will explain:

• What variables it's using
• What logic it's implementing
• Which calendars/users it will select in different scenarios

Review Carefully:

• Does it understand your rules correctly?
• Are calendar IDs correct?
• Is the logic what you intended?

Step 4: Test the Script

Click "Test" button

Enter test scenarios:

• Different zip codes
• Different service types
• Edge cases

Verify:

• Correct calendar is selected
• Correct user is selected (if applicable)
• Fallback works correctly

Step 5: Save the Script

Click "Save Script"

The script is now active and will execute in real-time when the AI books appointments.

Step 6: Further Testing (After Saving)

Use the "Test Saved Script" button to run additional tests:

• Test with actual contact data scenarios
• Verify edge cases
• Ensure fallback logic works

Step 7: Save the Agent

After script is saved and tested, click "Save Changes" to save the agent.

Real-Time Script Execution

When the AI books an appointment:

1. Contact provides booking criteria (zip code, service type, etc.)
2. Field extractors save data to contact record
3. AI requests availability from the calendar system
4. Script executes instantly using current contact data
5. AI gets availabilble appointment to present to the user that fall within your rules (correct calendar and user)
6. Contact agrees to proposed time
7. AI sends request to calendar system to book appointment
8. Script executes instantly ensuring booking goes to correct calendar (and user if applicable), Appointment is created.
9. AI gets confirmation that appointment was booked > confirms to contact that appointment is set.

Performance:

• Script runs in milliseconds
• No delay for contact
• Booking happens seamlessly
• Eliminates chance of AI hallucinating during critical task of determining appropriate calendar to book into

Common AI Selection Scenarios

Scenario 1: Territory Routing by Zip Code

Setup:

• 3 calendars (West, East, Central)
• Each serves different zip codes

Instructions:

If {contact.zip_code} is: 90001, 90002, 90003, 90004
Book into {Calendar: West Territory}

If {contact.zip_code} is: 90010, 90011, 90012, 90013
Book into {Calendar: East Territory}

Otherwise book into {Calendar: Central Territory}

Agent Instructions Must Include:

• Gathering zip code
• Field extractor for zip_code

Scenario 2: Service Type Routing

Setup:

• Different calendars per service
• Custom field: service_type (you can create any custom field you like in Settings > Custom Fields)

Instructions:

If {contact.service_type} contains "HVAC" or "air conditioning" or "heating"
Book into {Calendar: HVAC Services}

If {contact.service_type} contains "plumbing" or "water" or "drain"
Book into {Calendar: Plumbing Services}

If {contact.service_type} contains "electrical" or "wiring"
Book into {Calendar: Electrical Services}

Otherwise book into {Calendar: General Services}

Agent Instructions Must Include:

• Asking about service needed
• Field extractor for service_type

Scenario 3: Specialist Assignment (Calendar + User)

Setup:

• Senior tech handles complex jobs
• Regular techs handle standard jobs

Instructions (Scope: Calendar and User):

If {contact.service_description} contains "commercial" or "industrial"
Book with {User: Alice Johnson - Senior Tech} in {Calendar: Commercial Jobs}

Otherwise
Book with any available user in {Calendar: Residential Jobs}

Agent Instructions Must Include:

• Gathering service description
• Field extractor for service_description

Scenario 4: Workload Balancing

Instructions (Scope: Calendar and User):

Determine which user to book with based on their appointment counts.

Appointment counts: {users.appointment_counts}

{User: John Smith} should always have 2 more appointments than {User: Joe Brown}

Book into {Calendar: Main Services Calendar}

What Happens:

• AI checks John's appointment count: 10
• AI checks Joe's appointment count: 4
• John should have 2 more than Joe (target: Joe + 2)
• Joe only has 4, so book with Joe to target correct ratio

For territory-specific balancing, use {users.appointment_counts_by_zip} instead of {users.appointment_counts}. This is useful when each territory has its own team and the counts should only compare appointments from that territory's zip codes.

Scenario 5: Complex Multi-Factor

Instructions (Scope: Calendar and User):

First check zip code for territory:

If {contact.zip_code} is 11706, 11707, 11708 (North Territory):
  - If {contact.service_type} is "Emergency": Book with {User: On-Call North} in {Calendar: North Emergency}
  - If {contact.service_type} is "Standard": Book any user in {Calendar: North Standard}

If {contact.zip_code} is 11709, 11710, 11711 (South Territory):
  - If {contact.service_type} is "Emergency": Book with {User: On-Call South} in {Calendar: South Emergency}
  - If {contact.service_type} is "Standard": Book any user in {Calendar: South Standard}

Otherwise: Book into {Calendar: General Queue} with any available user

Best Practices

Always Include "Otherwise" Fallback

Required:

If {contact.zip_code} is 11706, 11707
Book into {Calendar A}

Otherwise
Book into {Calendar B}

Why:

• Ensures booking never fails due to unexpected data
• Handles edge cases
• Provides safety net

Match Data Collection to Booking Logic

If booking decision based on zip_code:

In Instructions Tab:

2) **Address: street address, city, zip**
- policy: always_ask
- example: "Can you provide your zip code?"

In Field Entry Tab:

• Add extractor for zip_code
• Description: "the user's 5-digit zip code"

In Booking Tab:

• Use {contact.zip_code} in selection logic

Critical: If you don't gather and save the zip code, the AI can't use it for booking decisions!

Use Specific Values, Not Partial Matching (When Possible)

Better:

If {contact.zip_code} is: 11706, 11707, 11708

Less Predictable:

If {contact.zip_code} starts with "117"

Why: Exact matching is more predictable and less error-prone.

Start with Calendar Only Scope

Unless you specifically need to assign to particular users:

• Use Calendar Only scope
• Let calendar's user selection strategy handle distribution
• Simpler and less to manage

Upgrade to Calendar and User when:

• Specific specialists for specific jobs
• Custom workload balancing needed
• VIP routing to senior staff

Test Thoroughly

Before Going Live:

1. Write instructions
2. Generate script
3. Review AI's explanation
4. Test with multiple scenarios
5. Save script
6. Test saved script with edge cases
7. Use agent test feature for end-to-end testing

Keep Instructions Clear and Organized

Good Structure:

[Territory Check]
If zip code is X → Calendar A
If zip code is Y → Calendar B

[Service Type Check]  
If service is HVAC → Calendar C
If service is Plumbing → Calendar D

[Fallback]
Otherwise → Calendar E

Harder to Parse:

Complex nested logic with multiple ands/ors in single rules. (Your rules can be as complex as you like, just be sure you understand them)

Use Custom Fields for Complex Routing

If routing logic is complex, create custom fields:

• service_type - Field with specific service options
• appointment_type - "Consultation", "Installation", "Repair"
• customer_tier - "Standard", "VIP", "Commercial"

In your field extractor tools for these fields specify to the AI the exact values it should save. (E.g. service_type. "The general category of service the user needs based on their description of their issue. Fill exactly with either 'Installation', 'Repair', or 'Maintenance' ONLY.")

Then route based on those structured values.

Common Mistakes to Avoid

Mistake 1: Not Gathering Required Data

❌ Selection logic uses {contact.zip_code} but agent doesn't ask for it

✅ Agent asks for zip code + field extractor saves it + selection logic uses it

Mistake 2: No Fallback

❌

If zip is 11706 → Calendar A
If zip is 11707 → Calendar B
(no otherwise)

✅

If zip is 11706 → Calendar A
If zip is 11707 → Calendar B
Otherwise → Calendar C

Mistake 3: Wrong Scope for Use Case

❌ Using Calendar and User scope but only have calendar selection rules

✅ If only selecting calendars, use Calendar Only scope

Mistake 4: Not Testing

❌ Write instructions, generate script, save, deploy

✅ Write → Generate → Review → Test → Save → Test Again → Deploy

Mistake 5: Calendar IDs Not Inserted

❌ "book into Main Calendar" (plain text)

✅ "book into {Calendar ID: abc-123-xyz}" (using variable selector)

Why: AI needs exact calendar ID, not just the name (variable shows name AND provides AI with ID).

Mistake 6: Users Not in Selected Calendar

❌ Instructions say: "Book with John in Calendar A" but John isn't in Calendar A

✅ Verify all specified users are actually in the calendars you designate

If mismatch: Booking will fail. Ensure users are added to calendars in Appointments & Calendars > Calendar Settings.

Mistake 7: Rule based on number of appointments without including appointment counts

❌ Instructions say: "Book 3 appointments with John before booking any with Joe, then book evenly maintaining John's lead"

✅ "Book 3 appointments with John before booking any with Joe, then book evenly maintaining John's lead. Appointment Counts: {users.appointment_counts}"

Mistake 8: Using global appointment counts for territory-specific balancing

❌ "For North Territory zip codes, book with the user who has the fewest appointments in that territory. Appointment Counts: {users.appointment_counts}"

✅ "For North Territory zip codes, book with the user who has the fewest appointments in that territory. Appointment Counts by Zip: {users.appointment_counts_by_zip}"

Calendar Triggers for Journey Stages

Critical Setup:

If your AI agent can book into multiple calendars, you MUST add calendar triggers to your journey's Appointment Scheduled stage for each calendar. (unless doing booking with a Global Agent - not typically recommended for most use-cases)

Example: Agent can book into:

• HVAC Calendar
• Plumbing Calendar
• Electrical Calendar

Your Appointment Scheduled stage must have 3 calendar triggers:

• Calendar: HVAC Calendar, Event: Appointment Created
• Calendar: Plumbing Calendar, Event: Appointment Created
• Calendar: Electrical Calendar, Event: Appointment Created

Why:

• Without the trigger, opportunity won't move to next stage
• Follow-ups won't end when appointment is booked
• Journey flow breaks

Configure Triggers:

1. Open journey
2. Click Appointment Scheduled stage
3. Add calendar trigger for each calendar AI might book into
4. Save Journey

Advanced Examples

Example: Multi-Factor with Custom Appointment Ratio

Instructions (Scope: Calendar and User):

First determine service tier from {contact.service_description}:

If description contains "commercial" or "business" or "industrial":
  - Route to Commercial Team
  - {User: Alice Senior} should get 60% of commercial appointments
  - {User: Bob Senior} should get 40% of commercial appointments
  - Book into {Calendar: Commercial Services}

  Appointment Counts are {users.appointment_counts}

For residential customers:
  - If {contact.zip_code} is 11706, 11707, 11708:
    - Book with {User: Dave} in {Calendar: North Residential}
  - If {contact.zip_code} is 11709, 11710, 11711:
    - Book with {User: Tom} in {Calendar: South Residential}
  - Otherwise:
    - Book any user in {Calendar: General Residential}

If cannot determine service tier, book into {Calendar: General Queue}

Example: Time-Sensitive Routing

Instructions:

If {contact.service_description} contains "emergency" or "urgent" or "asap":
Book into {Calendar: Emergency Response} (1-hour appointment slots)

Otherwise:
Book into {Calendar: Standard Appointments} (2-hour appointment slots)

Note: Different calendars can have different appointment durations configured.

Troubleshooting

Problem: Script generation failing

Solution:

• Simplify instructions
• Ensure at least 1 calendar ID is specified
• Check that all calendar IDs are valid (using variable selector)
• Verify instructions are clear and parseable
• Try breaking complex logic into simpler steps

Problem: AI booking into wrong calendar

Solution:

• Review generated script logic
• Test script with specific scenarios
• Check contact record has the field data script needs
• Verify calendar IDs in instructions are correct
• Ensure field extractors are working (check contact record)

Problem: Booking failing for some contacts

Solution:

• Check contact has required data (zip_code, service_type, etc.)
• Verify fallback "otherwise" rule exists
• Test script with edge case data
• Review AI logs for booking errors
• Ensure all specified calendars still exist

Problem: User assignment not working

Solution:

• Verify scope is set to "Calendar and User"
• Check specified users are in the selected calendars
• Ensure user IDs are correct (use variable selector)
• Test with different user availability scenarios

Problem: Script says it will select Calendar A but books in Calendar B

Solution:

• Re-generate script (may have been outdated)
• Test saved script again
• Check if contact data changed between test and actual booking
• Review AI Text Agent logs for actual selection reasoning

Problem: Can't test script - no calendars showing

Solution:

• Verify at least one calendar exists
• Check calendars have users assigned
• Refresh page and try again
• Ensure calendars have availability configured

Important Reminders

Data Must Be Collected First

The AI can only use data that exists in the contact record:

• Ask for information in instructions
• Use field extractors to save it
• Then use it in booking logic

Script Executes in Real-Time

• No pre-processing or caching
• Always uses current contact data
• Instant execution (milliseconds)
• Can handle dynamic data

Scope Setting Matters

Wrong scope = booking failures:

• If you specify users but scope is "Calendar Only" → Will ignore user specs
• If scope is "Calendar and User" but no user rules → May cause issues

Match scope to your instructions.

Calendar Triggers Are Required

Never forget to add calendar triggers to your journey stage:

• One trigger per calendar the AI might book into
• Event: Appointment Created
• Without this, journey automation breaks
• Not applicable if you are doing booking with a Global Agent (not recommended if you want to track conversion/success rates) > Better approach: have Global agent determine if user needs to book > handoff to Journey agent to do the booking.

Changes Require Re-Generation

If you modify your instructions:

1. Update the text
2. Click "Generate Script" again
3. Review new script
4. Test
5. Save

Old script won't automatically update when instructions change.

Related Features

• AI Text Agents Overview - Main agent configuration guide
• Calendars and Appointments - Creating and configuring calendars
• Field Extractors - Saving conversation data to contact fields
• Customer Journeys - Setting up calendar triggers for stages