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.

---

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.