Skip to main content

Square Appointments Integration

Square Appointments

Connect your Voka AI assistant to Square Appointments for seamless appointment booking, customer management, and real-time availability checking.

What is Square Appointments?​

Square Appointments is a comprehensive booking and scheduling platform built into the Square ecosystem, perfect for:

  • 💇 Salons & Spas - Hair, nails, massage, beauty services
  • 🛍️ Retail Services - Personal shopping, consultations
  • 💼 Professional Services - Consulting, coaching, financial advising
  • 🏋️ Fitness & Wellness - Personal training, yoga, therapy
  • 🏥 Healthcare - Clinics, practitioners, medical offices
Perfect for Square Users

Already using Square POS or payments? Square Appointments integrates seamlessly with your existing Square account!

What Your Assistant Can Do​

When connected to Square Appointments, your AI assistant can:

✅ Real-Time Availability​

  • Check live availability across all team members
  • Query open slots by date and time
  • Respect business hours and staff schedules
  • Account for blocked time and breaks

✅ Appointment Booking​

  • Book new appointments during calls
  • Select specific services
  • Assign to available staff members
  • Confirm appointment details

✅ Appointment Management​

  • Modify existing appointments
  • Reschedule bookings
  • Cancel appointments
  • Update appointment notes

✅ Customer Management​

  • Look up existing customers
  • Create new customer records
  • Update customer information
  • Access customer history

✅ Service Information​

  • List available services
  • Provide service descriptions
  • Share service duration
  • Quote pricing

✅ Staff Coordination​

  • Check staff availability
  • Route to preferred staff member
  • Handle multi-staff businesses
  • Respect staff schedules

How It Works​

During a Call​

Customer: "I'd like to book a haircut for tomorrow"

Assistant:

  1. Queries Square Appointments for available haircut slots tomorrow
  2. Receives real-time availability data
  3. Offers available times to customer
  4. Books the appointment when customer confirms
  5. Creates/updates customer record in Square
  6. Confirms details back to customer

Result: Appointment appears in your Square Appointments dashboard immediately!

Behind the Scenes

The integration uses Square's official API to communicate securely with your account. All data stays synced in real-time.

Setup Guide​

Video Tutorial Available

Video ID: VIDEO-SQUARE-001 Title: Connecting Square Appointments to Voka AI Duration: 6-7 minutes Description: Step-by-step walkthrough of the complete Square integration setup Status: 🔴 Not recorded yet

Prerequisites​

Before you begin, make sure you have:

  • ✅ Active Voka AI account
  • ✅ Active Square Appointments account
  • ✅ Services configured in Square Appointments
  • ✅ Staff members set up in Square (if applicable)
  • ✅ Business hours configured in Square

Step 1: Connect Square Account​

  1. Log in to your Voka AI Dashboard
  2. Navigate to Integrations from the left sidebar
  3. Find Square Appointments in the list
  4. Click "Connect to Square"

Integrations overview page showing available integrations

Step 2: Authorize Access​

  1. You'll be redirected to Square's authorization page
  2. Log in with your Square account credentials
  3. Review the permissions requested:
    • Read appointments
    • Create and modify appointments
    • Read customer information
    • Create and update customers
    • Read services and staff
  4. Click "Authorize" or "Allow Access"
Screenshot Needed

Screenshot ID: SQUARE-002 Filename: SQUARE-002_square-authorization.png Description: Square's OAuth authorization screen showing Voka AI permissions request Status: 🔴 Not started

Step 3: Confirm Connection​

  1. You'll be redirected back to Voka AI
  2. You should see a green checkmark next to Square Appointments
  3. Status should show "Connected"
  4. Your Square business name should appear

Integration connection example showing connected status

Step 4: Enable for Your Assistant​

  1. Go to AI Assistants in the dashboard
  2. Select the assistant you want to enable Square for
  3. Click the Agent Tab
  4. Scroll to the Integrations section
  5. Toggle ON the switch for Square Appointments
  6. Click "Save Assistant"
Screenshot Needed

Screenshot ID: SQUARE-004 Filename: SQUARE-004_enable-toggle.png Description: Agent tab showing Square Appointments integration toggle switched to ON Status: 🔴 Not started

Step 5: Configure Instructions​

Update your assistant's instructions to utilize Square:

You are a scheduling assistant for [Business Name]. You have access to our Square Appointments system.

When customers want to book appointments:
1. Ask what service they need
2. Ask their preferred date and time
3. Check Square for availability
4. Offer available time slots
5. Book the appointment when they confirm
6. Confirm the booking details

Available services:
- [Service 1] - [Duration] - [Price]
- [Service 2] - [Duration] - [Price]
- [Service 3] - [Duration] - [Price]

Always be friendly and confirm all details before booking.
Template Available

Use the "Square Appointments Manager" template when creating your assistant for pre-configured Square integration instructions!

Step 6: Test the Integration​

  1. Call your assistant's phone number
  2. Request to book an appointment
  3. Go through the booking process
  4. Check your Square Appointments dashboard
  5. Verify the appointment appears correctly

See Testing Guide for comprehensive testing instructions.

Use Cases​

Salon & Spa Booking​

Scenario: Customer calls for a haircut appointment

Assistant capabilities:

  • "What service are you looking for today?"
  • Check availability for specific stylist or any available
  • "I have availability tomorrow at 2pm, 3pm, or 4pm with Sarah"
  • Book and confirm appointment
  • Send confirmation SMS

Square sync:

  • Appointment appears in Square calendar
  • Staff member sees booking
  • Customer record created/updated
  • Service assigned correctly

Multi-Location Retail​

Scenario: Customer wants consultation at specific location

Assistant capabilities:

  • Identify which location customer prefers
  • Check availability at that specific location
  • Route to appropriate staff member
  • Book location-specific appointment

Square sync:

  • Correct location assigned
  • Location-specific staff assigned
  • Customer can see location in confirmation

Professional Services​

Scenario: Client needs recurring consultation appointments

Assistant capabilities:

  • Book initial appointment
  • Discuss recurring schedule
  • Create multiple appointments
  • Assign to preferred consultant

Square sync:

  • All appointments appear in Square
  • Recurring series visible
  • Consultant assigned to all

Configuration Options​

Multi-Location Setup​

If you have multiple Square locations:

  1. In Voka AI Integrations settings
  2. Click "Configure" next to Square Appointments
  3. Select which location(s) this integration should access
  4. Save configuration

Different assistants can be assigned to different locations!

Service Filtering​

Limit which services the assistant can book:

  1. In Agent Tab → Integrations → Square Settings
  2. Click "Configure Services"
  3. Select which services to make available
  4. Uncheck services that shouldn't be bookable by phone
Why Filter Services?

Some services may require in-person consultation first, or may not be suitable for phone booking.

Staff Assignment​

Control staff assignment behavior:

Option 1: Any Available Staff

  • Assistant books with whoever is available
  • Best for customers with no preference

Option 2: Specific Staff Member

  • Customer can request specific person
  • Assistant checks that person's availability
  • Falls back to alternatives if requested person unavailable

Option 3: Round Robin

  • Distribute appointments evenly
  • Good for salons with multiple stylists

Configure in Agent Tab → Integrations → Square Settings

Deposit & No-Show Protection​

Reduce no-shows by having your assistant collect a deposit (or the full amount) at the time of booking — without ever taking a card number over the phone.

How it works

When a caller books a service that requires payment, your assistant sends a real Square invoice to the customer's phone via text message. The customer pays through Square's own secure, hosted payment page. Voka AI and your assistant never see or touch card details — the call never asks for a card number.

What Your Assistant Can Do​

  • Let the caller know up front that a deposit (or full payment) is required for the service they're booking
  • State the exact deposit amount or the full price, based on your configuration
  • Book the appointment as usual
  • Text a secure Square-hosted payment link to the caller's phone immediately after booking

Enabling It​

  1. Go to Integrations → Square → Manage
  2. Find Payment Collection
  3. Choose a mode:
    • Deposit only — collect a partial deposit now; the remaining balance is scheduled on the same invoice, due later
    • Full payment only — collect the entire service cost at time of booking
    • Both — deposit or full payment, depending on service
  4. Set the deposit amount as either a percentage of the service price or a fixed dollar amount
  5. Choose which services require payment collection — you don't have to apply it to everything you offer
  6. Save your changes — they take effect on the very next call, no need to edit or resave your assistant
Requirements

Payment Collection requires:

  • The SMS add-on enabled on your account (the payment link is delivered by text)
  • A verified toll-free number on the assistant taking the call

Without both of these, the assistant will not offer to collect payment.

The Caller Experience​

Customer: "I'd like to book a haircut for tomorrow at 2pm"

Assistant:

  1. Confirms the appointment slot
  2. Lets the caller know payment is required — for example, "This service requires a $50 deposit, with the remaining $200 due at your appointment"
  3. Books the appointment in Square
  4. Sends a text with a secure Square payment link
  5. Confirms the booking and lets the caller know to check their texts to complete payment

The customer completes payment on Square's own hosted page, on their own time, after the call ends.

What the Invoice Looks Like​

This is a true deposit, not a placeholder charge. For a $250 service configured with a $50 deposit, the invoice shows:

  • Full service total: $250
  • Deposit due now: $50 (payable immediately via the texted link)
  • Balance due: $200 (scheduled, due at time of service)

Both amounts live on the same Square invoice, so you and your customer always see the complete picture — what's owed today and what's owed later.

Behind the Scenes

The invoice is delivered by link (Square's SHARE_MANUALLY delivery method) rather than emailed automatically by Square, since Voka AI sends it directly via SMS. Voka AI's Square permissions do not include the ability to write or process payments directly (PAYMENTS_WRITE) — all payment collection happens on Square's own hosted checkout, under Square's PCI compliance.

Square only, for now

Deposit and no-show protection is currently available for Square Appointments integrations. If you use Acuity Scheduling, ask your account manager about Acuity's separate deposit workflow.

Best Practices​

1. Keep Square Updated​

Your assistant is only as good as your Square data!

✅ Do this:

  • Update business hours in Square when they change
  • Mark staff as unavailable when out
  • Keep service listings current
  • Update pricing in Square regularly

❌ Avoid:

  • Managing schedules outside Square
  • Manual calendar adjustments not reflected in Square
  • Outdated service descriptions

2. Configure Buffer Times​

Set buffer time between appointments in Square to allow for:

  • Cleanup
  • Preparation
  • Running over
  • Travel time (mobile services)

Your assistant will respect these buffers automatically.

3. Handle Edge Cases in Instructions​

Add to your assistant's instructions:

If no availability exists for requested date:
- Offer alternative dates nearby
- Ask if they want to check a different service
- Offer to add them to a waitlist (take message)

If customer requests specific staff member who isn't available:
- Check that person's next availability
- Offer alternative staff members
- Let customer decide

4. Use Customer Notes​

Enable your assistant to capture important details:

When booking appointments, ask:
- First time customer or returning?
- Any allergies or sensitivities? (for spa/salon)
- Special requests or preferences?

Add these as notes to the Square appointment.

5. Sync Regularly​

The integration syncs in real-time, but:

  • Manual changes in Square appear immediately
  • Changes in Voka AI trigger instant Square updates
  • If connection drops, reconnect to restore sync

Check Integrations page for connection status indicator.

Troubleshooting​

"Square integration not working"​

Check these:

  1. ✅ Integration shows "Connected" (green checkmark)
  2. ✅ Integration is toggled ON for this assistant
  3. ✅ Square account is active and in good standing
  4. ✅ Services are configured in Square Appointments
  5. ✅ Business hours are set in Square

Still not working?

  • Disconnect and reconnect the integration
  • Check Square's service status: https://status.squareup.com
  • Contact support with call transcript showing the error

"Appointments not appearing in Square"​

Possible causes:

  1. Wrong location selected

    • Check location settings in integration config
    • Verify assistant is configured for correct location

  2. Service not found

    • Ensure service name in assistant instructions matches Square exactly
    • Check service is active in Square

  3. Staff member unavailable

    • Verify staff member schedule in Square
    • Check staff member hasn't been deleted

Debug:

  • Check call transcript to see what data was sent
  • Verify manually creating appointment works in Square
  • Test with simplest possible booking (any service, any time)

"Customer data not syncing"​

Square customer matching:

  • Square matches by phone number first
  • Then by email address
  • Then by name

To ensure proper matching:

  1. Assistant should capture phone number clearly
  2. Ask for email if creating new customer
  3. Confirm customer name spelling

Duplicate prevention:

  • Square may create duplicate if contact info doesn't match existing record
  • Clean up duplicates in Square dashboard
  • Update customer records to have accurate contact info

"Integration disconnected"​

Why this happens:

  • Square authorization token expired (usually after 30-90 days)
  • Square account password changed
  • Permissions were revoked in Square

How to fix:

  1. Go to Integrations page
  2. Click "Reconnect" next to Square Appointments
  3. Re-authorize access
  4. Integration will resume working
Auto-Reconnect

Future feature: Voka AI will email you when Square authorization is about to expire, so you can reconnect proactively!

Pricing & Limits​

Voka AI Side​

  • ✅ Square integration included in all plans
  • ✅ No per-booking fees from Voka AI
  • ✅ No API call limits

Square Side​

  • You need active Square Appointments subscription
  • Square may have API rate limits (very high, unlikely to hit)
  • Standard Square Appointments pricing applies

See Voka AI Pricing for plan details.

Security & Privacy​

Data Security​

  • ✅ OAuth 2.0 secure authorization
  • ✅ Encrypted API connections (HTTPS/TLS)
  • ✅ No passwords stored by Voka AI
  • ✅ Tokens encrypted at rest

Data Access​

What Voka AI can access:

  • Appointment data (to check availability and book)
  • Customer information (name, phone, email)
  • Service listings
  • Staff schedules
  • Business hours
  • Order and invoice creation (only when Payment Collection is enabled — used solely to create deposit/full-payment invoices)

What Voka AI CANNOT access:

  • Credit card numbers or other card details
  • The ability to process or capture a payment directly (PAYMENTS_WRITE)
  • Square POS transactions (unrelated to appointments)

Even with Payment Collection enabled, all actual payment is completed by the customer on Square's own hosted checkout page — Voka AI only creates the invoice and sends the link.

Disconnecting​

  • You can disconnect anytime in Integrations page
  • Disconnecting revokes all access immediately
  • Previously synced data remains in both systems
  • No data is deleted from either system

Advanced: Multiple Assistants with Square​

Scenario: Multi-Location Business​

Setup:

  • Assistant 1: Downtown location only
  • Assistant 2: Uptown location only
  • Assistant 3: Both locations (scheduling hotline)

Configuration:

  1. Connect Square once in Integrations

  2. Create 3 separate assistants

  3. Configure each assistant's Square settings:

    • Assistant 1 → Downtown location only
    • Assistant 2 → Uptown location only
    • Assistant 3 → All locations

  4. Update instructions to reference correct location

Assign different phone numbers to each assistant!

API Details (For Developers)​

The Square integration uses:

  • Square Appointments API v2
  • OAuth 2.0 for authorization
  • Webhook subscriptions for real-time updates (coming soon)

Permissions requested:

  • APPOINTMENTS_READ
  • APPOINTMENTS_WRITE
  • APPOINTMENTS_BUSINESS_SETTINGS_READ
  • CUSTOMERS_READ
  • CUSTOMERS_WRITE
  • ORDERS_READ / ORDERS_WRITE — only used to create the order backing a deposit or full-payment invoice, when Payment Collection is enabled
  • INVOICES_READ / INVOICES_WRITE — only used to create and share the invoice, when Payment Collection is enabled

Voka AI never requests PAYMENTS_WRITE — invoices are shared for the customer to pay directly through Square's hosted checkout (delivery method SHARE_MANUALLY), not processed by Voka AI.

Rate limits: Square's standard API limits apply (very high for typical use)

For custom integration needs, see Custom MCP Servers.

What's Next?​

Now that Square is connected:

  1. Test thoroughly - Make test bookings
  2. Go live - Start taking real bookings!
  3. Monitor analytics - Track booking success rate

Need Help?​

Frequently Asked Questions​

Can I use Square POS without Square Appointments?​

No, this integration specifically requires Square Appointments. Square POS alone doesn't have appointment booking functionality.

However, Square POS and Square Appointments work great together! Appointments sync to the same Square ecosystem.

Does this work with Square for Retail?​

Yes! If you're a retail business using Square Appointments for consultations, personal shopping, or services, this works perfectly.

Can customers book classes or group sessions?​

Currently, the integration supports 1-on-1 appointments. Group classes and events are not yet supported. This is planned for a future update.

What if I have custom fields in Square?​

Standard fields sync automatically. Custom fields are not yet supported but are on the roadmap.

Can I limit booking to certain times only?​

Yes! Set this in your Square Appointments business hours and availability settings. Your assistant will only offer times you've marked as available.

Does it handle deposits or payments?​

Yes. When Payment Collection is enabled for a service (see Deposit & No-Show Protection), the assistant books the appointment and then texts the customer a secure Square-hosted pay link — no card is ever taken over the phone. The resulting invoice is a true deposit: the full service total, with a deposit due now and the remaining balance scheduled for later. This requires the SMS add-on and a verified toll-free number on the assistant.

Connected to Square? 🎉 Your assistant is now a powerful booking machine! Test it out and watch appointments flow in automatically.