Managed Agents at Previously $0.06 $0.03/minManaged Agents are Previously $0.06 $0.03/min.
Webhook tool

Square Appointments AI receptionist that fills your book by phone

The agent finds open times for a service and books the caller in Square Appointments, through a small service of yours that calls the Bookings API.

Start buildingRead the docs

Appointment booking agent

Offers open times and books Square appointments.

Instructions

Ask which service the caller wants and when. Offer two open times from the availability tool, with the team member's name, and book the one they pick. Read the day, time and team member back. Transfer questions about prices, products or anything else to the shop.

Handoff
Shop

Connected tools

  • Find open timesWebhook
  • Book appointmentWebhook
  • Transfer to shopTransfer

What a Square Appointments AI voice agent can do

Open one to watch a call. The grey lines are the tools the agent calls mid-sentence.

Your service runs SearchAvailability for the service and location, and the agent reads two open times on the day the caller wants.

Tool definitions

Webhook tools go to POST /v1/agents/tools. Transfers are a system tool on the agent. Replace the placeholder values in capitals with your own.

Webhook

Find open times

Asks your service for open times for a service on a date.

Show the JSON definition
find_open_times
{
  "type": "webhook",
  "name": "find_open_times",
  "description": "Lists open appointment times for a service on one date. Use it before offering times.",
  "pre_tool_speech": "auto",
  "execution_mode": "immediate",
  "response_timeout_secs": 20,
  "api_schema": {
    "url": "https://api.your-company.com/square/availability",
    "method": "GET",
    "query_params_schema": {
      "properties": {
        "date": {
          "type": "string",
          "description": "Date to search, YYYY-MM-DD."
        },
        "service": {
          "type": "string",
          "description": "The service the caller asked for, such as haircut or color."
        }
      },
      "required": [
        "date",
        "service"
      ]
    },
    "authentication": {
      "mode": "bearer",
      "token": {
        "type": "secret",
        "secret_value": "YOUR_SERVICE_TOKEN"
      }
    }
  }
}

Webhook

Book appointment

Asks your service to find or create the customer and create the booking.

Show the JSON definition
book_appointment
{
  "type": "webhook",
  "name": "book_appointment",
  "description": "Books one of the times returned by find_open_times for the caller.",
  "pre_tool_speech": "auto",
  "execution_mode": "immediate",
  "response_timeout_secs": 20,
  "api_schema": {
    "url": "https://api.your-company.com/square/bookings",
    "method": "POST",
    "request_body_schema": {
      "type": "object",
      "properties": {
        "slot_id": {
          "type": "string",
          "description": "The ID of the chosen time, from find_open_times."
        },
        "given_name": {
          "type": "string",
          "description": "Caller's first name."
        },
        "family_name": {
          "type": "string",
          "description": "Caller's last name."
        },
        "phone": {
          "type": "string",
          "dynamic_variable": "system__caller_id"
        }
      },
      "required": [
        "slot_id",
        "given_name",
        "family_name"
      ]
    },
    "authentication": {
      "mode": "bearer",
      "token": {
        "type": "secret",
        "secret_value": "YOUR_SERVICE_TOKEN"
      }
    }
  }
}

Transfer

Transfer to shop

Cold transfer to the shop's phone.

Show the JSON definition
transfer_to_shop
{
  "config": {
    "system_tools": {
      "transfer_to_number": {
        "description": null,
        "pre_tool_speech": "auto",
        "transfers": [
          {
            "destination": {
              "type": "phone",
              "phone_number": "+14155550133"
            },
            "condition": "The caller asks about prices or products, wants a service the agent can't book, or asks for a person."
          }
        ]
      }
    }
  }
}

Set it up

No native connector. Webhook tools call a service of yours, which holds a Square access token and calls the Bookings and Customers APIs. Vendor details read in November 2026.

  1. Get an access token

    For your own Square account, a personal access token works. An app that books for many sellers uses OAuth with the APPOINTMENTS scopes instead.

  2. Collect the IDs

    ListLocations gives the location ID, SearchCatalogItems the service variation ID and version, and ListTeamMemberBookingProfiles the bookable team members.

  3. Run the two endpoints

    Your service calls SearchAvailability for a 24-hour window, then SearchCustomers or CreateCustomer and CreateBooking with an idempotency key.

  4. Test in the sandbox

    Point your service at connect.squareupsandbox.com, book from a test call, and check the booking on the sandbox seller's calendar.

Documentation

Before you build

Seller-level writes need a paid plan

Square says seller-level booking writes need a paid Appointments plan. Check support_seller_level_writes on the business booking profile first.

Why a service sits in between

CreateBooking needs a customer ID whose record has a phone number, plus the location and appointment segments. Your service fills those in from your Square IDs.

Use cases for teams on Square Appointments

Appointment scheduling

Book, reschedule and confirm appointments on your calendar, 24/7.

See the use case

Customer support

Resolve support calls on the first try, refund and credit within your rules, and keep customers who call to cancel.

See the use case

More integrations

All integrations
Webhook tool

Mindbody

Read a studio's Mindbody class schedule and book callers into class, through a service of yours that calls the Public API.

  • Managed Agents
See the integration
Webhook tool

Calendly

Webhook tools that let a Cartesia voice agent offer Calendly times and book the meeting.

  • Managed Agents
See the integration
Webhook tool

Cal.com

Two webhook tools for Cal.com's API: read slots and create bookings from a phone call.

  • Managed Agents
See the integration

Enterprise-grade security

  • HIPAA compliant badge

    HIPAA compliant

  • SOC 2 Type 2 badge

    SOC 2 Type 2

  • GDPR badge

    GDPR

Square Appointments AI voice agent FAQs

Can an AI receptionist book Square Appointments?

Yes, through Square's Bookings API. A Cartesia agent calls a service of yours, which runs SearchAvailability for the service and location, finds or creates the customer, and calls CreateBooking, so the booking shows on the seller's calendar. There is no native connector, and a transfer sends other calls to the shop.

How is this different from Square AI phone ordering?

Square AI answers calls to a Square-provided business number and takes orders against your online ordering profile, on Square Plus, Premium or Messages Plus. Square's help article says it isn't trained for reservations. A Cartesia agent books appointments through the Bookings API on a number you choose.

Does AI booking work on the free Square Appointments plan?

Only partly. Square says seller-level bookings need a paid Appointments plan, while the free plan still allows buyer-level bookings through the API. Check support_seller_level_writes on the business booking profile before you build.

Why does a service sit between the agent and Square?

CreateBooking needs a customer ID whose record has a phone number, plus the location and appointment segments. Your service looks those up and fills them in, so the agent only passes the chosen time and the caller's name.

Can I test a Square Appointments voice agent in the sandbox?

Yes. Point your service at connect.squareupsandbox.com, book from a test call, and check the booking on the sandbox seller's calendar. Switch to connect.squareup.com/v2 with a production token when it works.

What does a Square Appointments voice agent cost to run?

Agents run at $0.03/min, plus LLM usage and telephony. Square bills its own Appointments plan. Transfers need a Twilio or SIP trunk number, per Cartesia's docs, so put the number on Twilio or a SIP trunk if the agent hands callers to staff.

Get started today

Talk to an expert.

Connect with a member of our team and learn how Cartesia can help you build world-class voice experiences.

Contact Sales

Start building.

Access our models via API and bring a voice agent into production in minutes.

Try Cartesia