This guide explains how to connect your Square account to Newo.ai. By configuring this integration, your AI Employee can check real-time appointment availability, book and cancel appointments, and automatically sync your Square service catalog — all through your existing Square Bookings setup.

This integration is designed for service businesses such as salons, spas, and healthcare providers who need automated appointment scheduling.

Requirements

Before you begin, confirm the following:

An active Square account with Bookings enabled
A Square OAuth App with an Application ID (Client ID) and Application Secret (Client Secret)
At least one location configured in Square
Services defined in your Square Catalog with the product type APPOINTMENTS_SERVICE

Step 1: Authorize in Square

The Square integration uses OAuth 2.0 to connect Newo.ai to your Square account. You will generate a one-time authorization code and paste it into the Builder to complete the connection.

In the Newo.ai Builder, navigate to Attributes and set square_client_id and square_secret_id using the Application ID and Application Secret from your Square OAuth App.
Click Save on both attributes.
In the square_oauth_code attribute description, click the Square authorization link provided by the platform.
Log in to your Square account and select the sub-account you want to connect.
Review the requested permissions (appointments, customers, items, employees, and merchant profile) and click Allow to authorize the Newo app.
After authorization, you are redirected to a URL containing the authorization code. Copy the code from the URL.
Return to the Builder and paste the code into the square_oauth_code attribute field.
Click Save.

⚠️ CAUTION

The OAuth authorization code is single-use. If it expires or you navigate away before saving, you must repeat the entire authorization flow to generate a new code.

Step 2: Configure attributes and publish

After saving your OAuth code, configure the remaining integration attributes and publish to finalize the connection.

Open Newo.ai and navigate to your project in Builder > Attributes.
Set the following attributes:

Attribute	Required	Description
`square_client_id`	Yes	OAuth2 Application ID from your Square OAuth App
`square_secret_id`	Yes	OAuth2 Application Secret from your Square OAuth App
`square_oauth_code`	Yes	One-time OAuth authorization code from Step 1
`square_locations`	Yes	The Square location to use (auto-populated as a dropdown after authorization)
`square_base_url`	No	API base URL (default: `https://connect.squareup.com`)
`square_login_url`	No	Login URL (default: `https://app.squareup.com`)
`square_enable_slot_check`	No	Enable availability checking (default: `True`)
`square_enable_booking`	No	Enable booking capability (default: `True`)
`square_enable_cancellation`	No	Enable cancellation capability (default: `True`)

Click Save + Publish All.

🗒️ NOTE

After publishing, the platform automatically exchanges your OAuth code for access and refresh tokens, retrieves your Square merchant locations, and populates the square_locations dropdown. Select your desired location if it has not been pre-selected.

On the first conversation after setup, the service catalog is automatically synced from Square.

How it works

Service catalog sync

At the start of every new conversation (session_started), the integration checks whether the service catalog cache is current. If not, it fetches all active items from your Square Catalog with the product type APPOINTMENTS_SERVICE that are available at the selected location, and stores them as square_catalog. This catalog drives AI-powered service matching throughout the conversation.

AI service matching

When a customer requests a service (for example, "I'd like a manicure"), the integration uses an AI model to match the natural language request against the synced square_catalog and identify the correct service variation. This matched variation is then used to search for available slots and complete the booking.

Team member assignment

During an availability search, Square returns which team members are available for each slot. The integration stores this mapping per slot. When booking, the correct team member is automatically selected for the time the customer chose — no manual selection is required.

Idempotency

All write operations — customer creation, booking, and cancellation — use unique idempotency keys to prevent duplicate records if a request is retried. This follows Square API best practices.

Automatic token refresh

If the Square access token expires, the integration detects the HTTP 401 response and automatically refreshes the token. Failed requests are retried up to 3 times.

What information is needed for booking

When a customer books an appointment, the AI Employee collects the following:

Phone number (required) — used to look up or create the customer record in Square
Name (first and last) — used when creating a new customer; the integration automatically splits a full name into first and last names

Location selection

During setup, available locations are fetched from Square and presented as a dropdown (square_locations) in the format "id | name | timezone". Select the desired location after completing the initial authorization. The integration supports one location per instance.

🗒️ NOTE

If you need to serve multiple Square locations, set up a separate Newo.ai integration instance for each location.

Testing

Test the integration through the Newo.ai conversation interface (chat or voice).

Setup: Publish the project and verify that the OAuth token exchange completed and that square_locations is populated.
Catalog: Start a new conversation and verify that square_catalog is populated with service variations from Square.
Availability: Ask "Any openings for [service] tomorrow?" and verify that time slots are returned, each with an assigned team member.
Booking: Complete a booking and verify that the appointment appears in your Square Bookings dashboard with the correct service and team member.
Cancellation: Cancel a booking and verify the appointment is removed from Square.

⚠️ CAUTION

This integration creates and cancels real appointments in your live Square account. Use a test Square account or a non-production location when verifying the setup for the first time.

Troubleshooting

If no action occurs during a conversation, check the following:

OAuth credentials — Confirm square_client_id and square_secret_id are set correctly.
Access token — Verify that square_access_token was populated after publishing. If it is empty, repeat the authorization flow.
Location selection — Confirm square_locations has a value selected. It should be auto-populated after authorization.
Service catalog — Confirm square_catalog is not empty. Services must be defined in Square Catalog with the product type APPOINTMENTS_SERVICE.
Feature flags — Verify that square_enable_slot_check, square_enable_booking, and square_enable_cancellation are set to True as needed.
Re-publish — If any credentials were changed after the initial setup, click Save + Publish All again to apply the changes.

Limitations

Limitation	Details
Rescheduling	Not supported. Use cancel + rebook as a workaround.
Payment processing	Not implemented.
Multiple locations	One location per integration instance.

FAQ

How does the AI Employee match services from natural language?

The integration uses an AI model to match the customer's service request (for example, "manicure") against the synced square_catalog of service variations. It returns the matching service_variation_id, which is used for the availability search and booking.

How are team members assigned to appointments?

During the availability search, Square returns which team members are available for each slot. The integration stores this mapping and automatically looks up the correct team member when the customer selects a time.

When is the service catalog synced?

The catalog syncs automatically at the start of every new conversation. It filters for Square Catalog items with the product type APPOINTMENTS_SERVICE that are available at the selected location.

Can I connect multiple Square locations?

Each integration instance supports one location. To serve multiple locations, set up a separate integration instance for each.

What happens if the OAuth token expires?

The integration detects HTTP 401 responses and automatically refreshes the access token. Failed requests are retried up to 3 times.

Why are idempotency keys used?

All write operations use unique idempotency keys to prevent duplicate bookings, customers, or cancellations if a request is retried — a Square API best practice.

GoHighLevel integration