Square Appointments Integration

Last updated March 17, 2026 · 58 views

Square Appointments Integration

Overview

Velaro integrates with Square Appointments to let visitors book services via SMS, WhatsApp, or website chat — without forms or scheduling links. The bot handles the entire booking conversation and creates the appointment directly on the merchant's Square calendar.

Best for: Hair salons, spas, barbershops, fitness studios, yoga instructors, and any service business using Square POS and Appointments.

Go to Integrations > Square Appointments to set up.

---

How to connect Square

Prerequisites: A Square seller account with Square Appointments enabled.

Option A — One-click OAuth (recommended)

1. In Velaro admin: go to Integrations > Square Appointments.

2. Click Connect with Square.

3. You'll be redirected to Square — sign in and authorize Velaro.

4. You'll land back in Velaro with your Square account connected automatically.

5. Select the location where bookings should land, then click Save Configuration.

Option B — Personal Access Token (manual)

1. Go to developer.squareup.com and sign in with your Square account.

2. Open an existing app or click Create Application.

3. Under Credentials, copy the Access Token (use Production for live bookings, Sandbox for testing).

4. In Velaro admin: go to Integrations > Square Appointments.

5. Click Use an access token instead, paste the token, and click Fetch Locations.

6. Select the location, then click Save Configuration.

Velaro validates the token and discovers your merchant name and locations automatically.

---

Services and team members

After connecting, the integration page shows:

  • Bookable Services — services from your Square Catalog with type "Appointments service". Each row shows the service name, duration, and service ID (used in bot workflows).
  • Team Members — active staff at your selected location. Visitors can book with a specific team member or any available staff.

If no services appear, make sure your Square Catalog items are set to type Appointments service in the Square dashboard.

---

How the bot uses Square

The bot calls three endpoints during a booking conversation:

1. Get availability

POST /api/admin/Square/Availability
{
  "serviceVariationId": "<from your service list>",
  "teamMemberId": "<optional>",
  "startAt": "2026-04-01T00:00:00Z",
  "endAt": "2026-04-08T00:00:00Z"
}
Response: { slots: ["2026-04-01T09:00:00Z", "2026-04-01T10:00:00Z", ...] }

2. Book a slot

POST /api/admin/Square/Book
{
  "visitorName": "<<visitorName>>",
  "visitorEmail": "<<visitorEmail>>",
  "visitorPhone": "<<visitorPhone>>",
  "serviceVariationId": "<id>",
  "teamMemberId": "<optional>",
  "startAt": "<<selectedSlot>>",
  "durationMinutes": 60,
  "conversationId": "<<conversationId>>"
}
Response: { bookingId, confirmationMessage }

3. Cancel a booking

POST /api/admin/Square/Cancel
{ "bookingId": "<<bookingEventId>>" }

Use the returned bookingId as the event ID for future cancellations. Store it in a workflow variable (<<bookingEventId>>) so the cancellation flow can reference it.

---

Sample booking workflow (SMS)

A typical bot conversation using Square Appointments:

1. Visitor texts: "I'd like to book a haircut"

2. Bot presents services → visitor picks "Women's Cut — 45 min"

3. Bot checks availability (Availability endpoint) → presents 3 slots

4. Visitor picks "Tuesday at 2pm"

5. Bot calls Book → Square creates the appointment

6. Bot sends confirmationMessage → "Your appointment is confirmed for Tuesday, April 8 at 2:00 PM. See you then!"

7. Square sends its own reminder emails/texts based on your Square Appointments settings

---

Cancellation flow

Set up a cancellation reply rule:

  • Rule triggers on keyword "cancel" + visitor has an active Square booking
  • Workflow calls /api/admin/Square/Cancel with the stored <<bookingEventId>>
  • Bot confirms cancellation: "Your appointment has been cancelled."

---

Sandbox vs. production

  • Sandbox: Use a Sandbox Access Token from Square Developer Dashboard. Bookings are simulated — no real appointments are created. Toggle the Sandbox mode option when saving.
  • Production: Use the Production Access Token. Real appointments are created in your Square calendar.

Start in sandbox mode for testing, then switch to production.

---

Missed Call Text-Back

When a call to your business goes unanswered, your phone system can POST to a Velaro webhook and Velaro automatically sends an SMS booking prompt to the caller.

How to set it up:

1. Go to Integrations > Square Appointments and scroll to Missed Call Text-Back.

2. Click Generate Webhook URL to create a unique URL for your business.

3. Copy the URL and paste it into your phone system's "missed call webhook" setting.

4. Optionally: set a custom Twilio number and customize the SMS message.

Compatible phone systems: SkySwitch, RingCentral, Zoom Phone, 8x8, Vonage, Nextiva, Twilio Studio, and any system that supports webhooks.

What the caller receives: The default SMS is: "Hi! We missed your call. Text back to book your appointment with [your business name]." You can customize this message — use {{merchantName}} to insert your business name automatically.

Caller phone field: The webhook reads the caller's number from From, caller, caller_number, phone, or CalledFrom — covering the field names used by all major phone systems.

Security: The webhook URL acts as a secret token. Anyone with the URL can trigger an SMS, so treat it like a password. If the URL is compromised, use Regenerate URL to invalidate it and generate a new one.

Requirements: Twilio must be configured on your Velaro account (a shared Velaro number is used by default). You can override this with a custom Twilio number in the From Number field.

---

FAQ

Q: Do visitors need a Square account to book?

A: No. The bot collects visitor name, email, and phone, then creates the booking on their behalf. Square handles reminders to both the merchant and the visitor.

Q: Can visitors choose a specific staff member?

A: Yes. Include a "Pick a staff member" question in your bot workflow, collect their choice, and pass the team member ID in the Book request.

Q: What if there are no available slots?

A: The Availability endpoint returns an empty slots array. Add a condition in your workflow: if slots is empty, send "No availability this week" and offer to check next week or connect to an agent.

Q: Can I use this with multiple locations?

A: One Square account can be connected per site. The config stores a single selected location. To support multiple locations, create separate Velaro sites or contact support.

Q: Does Velaro handle Square reminders?

A: Square Appointments sends its own SMS/email reminders based on your Square settings. Velaro does not duplicate these — it just creates the booking.

Q: What if the booking fails?

A: Use an error branch on the HTTP Request node in your workflow (Workflows editor → HTTP node → Enable error branch). Connect it to a "Transfer to agent" node so visitors don't get left waiting.

---

Square Retail & Commerce AI Skills

In addition to appointments, the Square integration includes 20 AI skills covering retail, orders, customers, loyalty, and gift cards. These skills activate automatically when Square is connected — no additional configuration required.

Skill categories:

  • Appointments (6): check availability, book, cancel, reschedule, list services, get customer bookings
  • Catalog & Inventory (4): search catalog, get catalog item, list categories, check inventory
  • Orders (3): search orders, get order details, cancel order
  • Customers (3): get customer, create customer, update customer
  • Loyalty & Gifts (3): get loyalty balance, get loyalty rewards, check gift card
  • Payments (1): get payment history

Skills are visible in Integrations > Square > AI Skills tab.

---

Square Retail API Endpoints

These endpoints are available for HTTP Request nodes in bot workflows:

Catalog & Inventory

  • POST /api/admin/Square/Catalog/Search — search catalog by keyword ({ query, limit })
  • GET /api/admin/Square/Catalog/{itemId} — get full item details with variations
  • GET /api/admin/Square/Categories — list all catalog categories
  • POST /api/admin/Square/Inventory/Check — check stock ({ catalogObjectId })

Orders

  • POST /api/admin/Square/Orders/Search — search orders ({ customerId, startAt, endAt, limit })
  • GET /api/admin/Square/Orders/{orderId} — get full order details

Customers

  • POST /api/admin/Square/Customer/Search — find customer by email or phone ({ email, phone })

Gift Cards

  • POST /api/admin/Square/GiftCard/Balance — check gift card balance by GAN ({ gan })

Loyalty (existing)

  • POST /api/admin/Square/CustomerLookup — find customer by phone
  • POST /api/admin/Square/LoyaltyBalance — get loyalty point balance

---

Retail Workflow Templates

Launch the Retail Wizard (Integrations > Square > Launch Wizard) to get three pre-built templates:

1. Square Retail Assistant — product discovery bot that searches catalog, checks stock, and handles order lookups. Best for boutiques, retail shops, and online stores.

2. Order Status Bot — customer asks "where is my order?" — bot identifies them by email, pulls recent orders from Square, and returns status, items, and fulfillment info. Eliminates the most common support inquiry.

3. Loyalty & Rewards Bot — check points balance, explain available rewards, tell customers how close they are to the next reward tier. Also handles gift card balance checks.

---

OAuth Scopes

When connecting via OAuth, Velaro requests the following Square scopes:

APPOINTMENTS_READ, APPOINTMENTS_WRITE, CATALOG_READ, CATALOG_WRITE, MERCHANT_PROFILE_READ, TEAM_READ, ORDERS_READ, CUSTOMERS_READ, CUSTOMERS_WRITE, INVENTORY_READ, PAYMENTS_READ, LOYALTY_READ, GIFTCARDS_READ

If connecting via Personal Access Token, make sure the token belongs to a Square application with access to the APIs you plan to use.

Was this article helpful?