Skip to Content

Square Appointments

Let your agent check availability and book, reschedule, or cancel appointments in your Square Appointments  account — using the caller’s phone number to find or create their Square customer record.

Setup

  1. Integrations → Add integration → Square Appointments.
  2. Name it (e.g. “Square booking”).
  3. Optionally set:
    • a default location ID — the Square location to use when a call doesn’t specify one (find it under Square Dashboard → Account & Settings → Business → Locations). If you leave it blank, list_services returns your locations so the agent can pick one;
    • a timezone used to format times.
  4. Click Continue to connect and grant access to your appointments, customers and catalog. You’ll be redirected back to the Integrations page when done.

The integration shows Connected once the Square grant completes, and its tools are discovered automatically. Use Reconnect at any time if the grant expires or you want to switch accounts.

Writing bookings by phone (create, reschedule, cancel) requires the business to be on the Square Appointments Plus or Premium plan. On the free plan those writes are rejected by Square and the agent can only check availability. Square surfaces this as a “plan required” error.

How the caller is matched

When the agent books, it uses the caller’s phone number to look up an existing Square customer (an exact phone match) and, if none exists, creates a new customer record from the caller’s name and phone. This means repeat callers are recognized automatically and their bookings stay under one profile.

Tools

Once connected, the agent can (prefixed with your integration’s slug):

  • …_list_services — list bookable services with durations and prices
  • …_get_availability — open appointment times for a service (each slot carries the team member to book with)
  • …_create_booking — book an appointment (finds or creates the customer by phone)
  • …_reschedule_booking — move an existing booking to a new time
  • …_cancel_booking — cancel a booking
  • …_find_customer — find a customer by phone and list their upcoming bookings

Enable the ones you want per agent version in the builder’s Integration tools card. For booking flows, pair them with clear instructions: which services you offer, which hours are bookable, and what details to collect from the caller.

OAuth

Square uses a confidential-client OAuth flow: you connect once by granting Ciaomatic access to your Square account, and the access token is refreshed automatically as needed. No API keys are pasted — the grant is stored encrypted per workspace and never shown to the agent, the model, or the browser.

Last updated on
Quickstart