Documentation Bookings and calendars Square Appointments

Bookings integration

Square Appointments

Square Appointments integration overview
  • CategoryBookings
  • AuthOAuth
  • Scopes7

Overview

Square Appointments connects on /integrations in the MessageMind dashboard. Open the Square card and the "Connect Square" modal explains, "Click connect to sign in with your Square account and authorize MessageMind. You'll be redirected to Square's secure login page, and once approved, you'll choose which appointment types your AI agent can manage." There are no credentials to paste. Clicking connect calls connectSquare({ userId }) in the dashboard, which navigates the browser to the backend /square/connect endpoint; that endpoint hands off to Square's OAuth 2.0 authorization-code flow on connect.squareup.com. On approval Square redirects to /square/callback, which exchanges the authorization code for an access token and refresh token, reads the merchant profile and the seller's locations, and then returns the browser to /integrations?squareSuccess=true (or ?squareSuccess=false on failure). From then on the AI holds a per-seller token pair it rotates automatically and uses to read services, check live availability, and create, reschedule or cancel bookings from inside a conversation. The connector offers eligible free appointment variations only; the initial connection uses the first active Square location.

What MessageMind can do with it

  • Check availability, create bookings, reschedule and cancel appointments on the seller's behalf from inside a WhatsApp, SMS, Instagram or web chat thread.
  • Read the seller's locations and merchant profile, and use the connected active location for bookings.
  • Sync bookable services from the Square Catalog API (APPOINTMENTS_SERVICE items with their eligible free variations and durations) into the MessageMind catalogue.
  • Read team-member booking profiles and limit the AI to the members marked bookable on the chosen location.
  • Search live availability through the Bookings API across a date window for a service variation and an optional team member.
  • Match an existing Square customer by email or phone before creating a new one, so repeat bookings land on the same card.

Requirements

  • A Square seller account with Square Appointments enabled on at least one location.
  • At least one bookable team member with a booking profile on the chosen location.
  • At least one APPOINTMENTS_SERVICE item in the Square catalog (service variations are what the AI books).
  • A MessageMind plan that includes Square (Starter, Professional or Enterprise).
  • Selected service variations must be available for booking, have numeric zero price, have a valid duration and be present at the connected location.

How to connect

  1. In the MessageMind dashboard, open /integrations and click the Square card. The "Connect Square" modal opens.
  2. Click connect. The dashboard calls connectSquare({ userId }), which navigates the browser to the backend /square/connect route and on to Square's secure login page at connect.squareup.com.
  3. Sign in to Square and approve the APPOINTMENTS_READ, APPOINTMENTS_WRITE, APPOINTMENTS_BUSINESS_SETTINGS_READ, ITEMS_READ, CUSTOMERS_READ, CUSTOMERS_WRITE and MERCHANT_PROFILE_READ permissions on Square's consent screen.
  4. Square redirects to /square/callback, which exchanges the authorization code for an access token and refresh token, reads the merchant profile and lists the seller's locations, then sends the browser back to /integrations?squareSuccess=true (or ?squareSuccess=false if anything failed).
  5. Pick which appointment types the AI agent can manage. MessageMind reads the chosen location's team-member booking profiles and the catalog's service variations and marks the integration Enabled.

Authentication and permissions

Mechanism
Square OAuth 2.0 authorization-code flow against connect.squareup.com, started by the dashboard's connectSquare({ userId }) handler via the backend /square/connect route and completed on /square/callback. Access tokens are refreshed automatically before expiry using the stored refresh token; the merchant does not paste or manage any API key.
Credentials
A per-seller access token and refresh token, the merchant id, the selected location id and the token's granted scopes, stored encrypted on your MessageMind tenant. The access token is sent as the Authorization bearer on every call to Square's API.

Required scopes

  • MERCHANT_PROFILE_READ
  • APPOINTMENTS_READ
  • APPOINTMENTS_WRITE
  • APPOINTMENTS_BUSINESS_SETTINGS_READ
  • ITEMS_READ
  • CUSTOMERS_READ
  • CUSTOMERS_WRITE

Available data and actions

Reads

  • The merchant profile (business name, country, default currency, main location) through the Merchants API.
  • Active locations through the Locations API; the initial connection selects the first active location.
  • Team-member booking profiles for the chosen location through the Bookings API (which members are bookable, their appointment types).
  • Eligible free APPOINTMENTS_SERVICE variations from the Catalog API, with their duration and assigned team members.
  • Live availability search results for a service variation (and optional team member) across a date window, honouring Square's business hours and existing bookings.
  • Customer records from the Customers API, matched by email or phone before create.

Writes

  • New bookings created on the seller's calendar through POST /v2/bookings, attached to the matched or newly-created customer.
  • Updated bookings when the conversation reschedules a slot (PUT /v2/bookings/{id}).
  • Cancelled bookings when the conversation cancels (POST /v2/bookings/{id}/cancel).
  • New customers through POST /v2/customers when no match is found for the person messaging.

AI agent use cases

  • A customer asks for the next free slot for a named service on WhatsApp or Instagram; the AI searches Square availability and quotes an opening in the location's time zone and the seller's currency.
  • The customer pins the booking to a specific team member; the AI only offers times that member is actually free.
  • The AI matches the customer to an existing Square record by the chat's own email or phone before creating a new one, so loyalty, past bookings and payment history stay on one card.
  • The customer asks to reschedule or cancel from the same thread; the AI updates or cancels the booking in Square without a human handoff.

Configuration

  • The initial connection chooses the first active Square location. Availability search and booking creation target the connected location.
  • You pick which appointment types the AI agent can manage after approval, as the modal describes; service variations marked not bookable in the Square catalog are synced but excluded from what the AI can offer.
  • Availability searches use windows of up to 31 days. The nearest-slot mode checks the remainder of the current month and then the following month.
  • Rate limits: Square returns 429 with Retry-After when a seller is throttled; MessageMind honours the header and surfaces the wait in-thread rather than retrying blindly.

Example workflows

Connect and first sync

  1. You click the Square card on /integrations and the "Connect Square" modal opens.
  2. You click connect. The dashboard's connectSquare({ userId }) handler navigates to the backend /square/connect route, which redirects to Square's secure login page.
  3. You sign in and approve the Appointments, Customers and Merchant Profile scopes on Square's consent screen.
  4. Square redirects to /square/callback, which exchanges the code for an access and refresh token, reads the merchant profile and locations, then returns to /integrations?squareSuccess=true (or ?squareSuccess=false if anything failed).
  5. Review the connected location and pick the eligible free appointment types the AI may manage. MessageMind syncs team-member booking profiles and service variations and marks the integration Enabled.

Book a service with a specific team member

  1. Customer asks for a service with a named team member on WhatsApp, SMS, Instagram or web chat.
  2. The AI resolves the service variation from the Square catalog and the team member from the location's booking profiles.
  3. The AI calls SearchAvailability for that variation and member across the requested window and quotes the soonest opening.
  4. Customer confirms. The AI searches the Customers API by the chat's own email or phone, or creates a new customer when there is no match.
  5. The AI creates the booking through POST /v2/bookings on the seller's calendar and posts the confirmation into the thread.

Limitations

  • Only service variations tagged as APPOINTMENTS_SERVICE in the Square catalog are bookable through the API. Retail-only or non-appointment items are not offered.
  • A booking's team member must have a booking profile on the chosen location; members without a profile are skipped at sync time.
  • The connector chunks availability searches into windows of up to 31 days.
  • Square refuses a booking on an occupied slot with a 400 CONFLICT; the AI re-reads availability before quoting a replacement.
  • If the merchant revokes the OAuth grant from the Square dashboard, the stored token is invalidated and the integration goes back to Disabled until it is reconnected.
  • Paid service variations are excluded from this connector. Square payment and deposit collection are not performed by the assistant.

Troubleshooting

The browser returns to /integrations?squareSuccess=false after sign-in.

The OAuth callback could not complete. This usually means the consent screen was cancelled, a required scope was declined, or the authorization code could not be exchanged. Open the Square card again and click connect to restart the flow.

Connect succeeds but the AI never offers any slots.

Confirm the chosen location has at least one bookable team member (a booking profile that includes an appointment type) and at least one APPOINTMENTS_SERVICE variation in the Square catalog.

Booking fails with a CONFLICT error even though the slot looked free a moment ago.

Square refuses a double booking at write time. The AI re-reads availability and quotes a replacement slot instead of retrying.

Reads start failing with a credentials error.

The OAuth grant was revoked on the Square side. Reconnect from the Square card on /integrations to issue a fresh token pair.

Disconnect and reconnect

  • In the MessageMind dashboard, open /integrations, Square and choose Disconnect. The backend /square/disconnect route runs: the stored access token, refresh token and location selection are removed from your tenant and MessageMind calls Square's RevokeToken endpoint to invalidate the grant on Square's side.
  • Bookings already written to Square stay on the seller's calendar; disconnecting does not cancel them.
  • To reconnect, re-run the OAuth flow from the Square card and pick the booking location and appointment types again.