Connect your Square account to your AI Employee to enable real-time appointment availability checks, booking and cancellation, and automatic service catalog sync through your existing Square Bookings setup.
Requirements
Before you begin, confirm the following:
An active Square account (free or paid)
A computer with a web browser (the Square Developer Dashboard does not work on mobile)
Owner or admin access to your Square account
Set up your Square Developer application
Before connecting to Newo.ai, you need to create an application in the Square Developer Dashboard and retrieve your production credentials.
Open the Square Developer Dashboard at
https://developer.squareup.com/appsand sign in with your business account credentials (the same email and password you use for your Square Dashboard).On the Applications page, click the + New Application button.
In the application creation dialog:
Enter a name for your application (e.g., "Newo AI Assistant")
Check I agree to the Square Developer Terms of Service
Click Next
On the "What will you build first?" screen, select the following three options and click Next:
Build customer relationships
Manage a team
Manage a product catalog
On the "Find your audience" screen, select Myself and click Complete.
In the left menu of your new application, click Credentials.
Click the Production tab.
Copy the Application ID (starts with
sq0idp-) by clicking the copy icon next to it.Copy the Personal Access Token (starts with
EAAA) by clicking the copy icon next to it.
⚠️ CAUTION
Make sure you are on the Production tab, not the Sandbox tab. The Sandbox environment uses test data and will not connect to your live Square account.
🗒️ NOTE
Your Personal Access Token gives full access to your Square account via the API. Keep it secure and do not share it publicly. You can revoke it at any time from the Credentials page if needed.
Troubleshooting: Developer Dashboard
Cannot find the "+ New Application" button — Confirm the URL in your browser is
developer.squareup.com, notsquareup.com/dashboard. The Developer Dashboard is a separate site.No Production tab visible — If your Square account is brand new, the Production tab may not be available until your account is verified. Complete Square's account verification process and try again.
Concerned about sharing your token — The Personal Access Token can be revoked at any time from the Credentials page. If you ever need to disconnect the integration, simply delete or regenerate the token.
Using a phone or tablet — The Square Developer Dashboard requires a desktop browser. Complete this step from a computer.
Set up Square Appointments
The AI Employee uses Square Appointments to manage bookings. Complete the following steps in the Square Dashboard to enable appointment scheduling before connecting to Newo.ai.
Enable the Appointments feature
In your Square Dashboard, click ... Add more at the bottom of the left sidebar.
Select the Bookings tab and click Add next to Appointments.
You will see the confirmation: "Scheduling features were successfully added." Click Start setup.
Verify that Appointments now appears in the left sidebar.
🗒️ NOTE
If Appointments already appears in your left sidebar, skip this step — the feature is already enabled.
Configure your business location
The AI Employee needs your location, timezone, and business hours to present accurate appointment slots.
Go to Settings → Account & Settings → My business → Locations.
If you do not have a location yet, click Create Location. If you already have one, click on it to edit.
In the Location details form, set:
Time Zone — select the timezone where your business operates
Regular hours — set open and close times for each day your business is open
Click Save.
⚠️ CAUTION
The timezone must match the physical location where your business operates. A mismatched timezone will cause appointment slots to appear at incorrect times for both the AI Employee and your clients.
Add team members
Team members are the people who perform services (e.g., stylists, therapists, doctors). Each appointment is assigned to a team member.
Go to Staff → Team → Team members.
Click Add team member.
Fill in the team member's profile:
Preferred name and Last name
Phone number or Email (used to send them an invitation)
Click Next.
Set their Primary job title and pay details.
Click Next → Done.
Repeat for each team member who should accept bookings through the AI Employee.
Create services
Services define what your clients can book (e.g., "Haircut", "Massage", "Consultation").
Go to Items & services → Items → Service library.
Click Create service.
Fill in the service details:
Name — what clients will see (e.g., "Lip Filler")
Description — describe the service in detail
Locations — select your business location
Scroll down and set:
Price type — Fixed or Variable
Price — e.g., $100.00
Duration — how long the service takes (e.g., 30 minutes)
Scroll down to the Online booking section and verify:
Bookable by customers online — must be ON
Assigned team members — by default set to "All team members"; click Select if you need to restrict which staff can perform this service
Click Save.
Repeat for each service you offer.
⚠️ CAUTION
If Bookable by customers online is OFF, the service will not appear in availability search results and the AI Employee will not be able to book it.
🗒️ NOTE
Write detailed service descriptions. The AI Employee matches what clients say (e.g., "I want fuller lips") to your services by reading these descriptions. A more specific description leads to more accurate matching.
Set team member availability
This is the most critical step. Without availability configured, the AI Employee will not find any open appointment slots.
Go to Staff → Scheduling → Availability.
Click on a day cell where you want to assign availability to a team member.
Set:
Start Time — e.g., 9:00 AM
End Time — e.g., 5:00 PM
Use Repeat on to apply the same hours to multiple days (e.g., Monday through Friday).
Click Save.
After saving, the calendar shows green blocks for the configured hours.
Repeat for each team member.
⚠️ CAUTION
If a team member has no green blocks on the Availability calendar, they will never appear in available appointment slots. The API reads directly from this schedule. Simply adding a team member to the team is not enough — they must also have availability configured here.
Pre-launch checklist
Before proceeding to connect Newo.ai, verify the following are complete in your Square account:
[ ] Appointments feature is active (visible in the left sidebar)
[ ] Your location has a correct timezone and business hours set
[ ] At least one team member has been added
[ ] At least one service has been created with a name, description, duration, and price
[ ] Each service has Bookable by customers online turned ON
[ ] Team member availability shows green blocks on the scheduling calendar for expected working days
Troubleshooting: Square Appointments setup
"Appointments" does not appear in the sidebar — Go to ... Add more → Bookings and click Add.
AI Employee says there are no available slots — Open Staff → Scheduling → Availability and confirm that team members have green availability blocks for the expected days and times. No green blocks means no slots.
Services do not appear in the integration — Services must be created in Items & services → Items → Service library, not as regular catalog items. They must also be set to available at your selected location.
Team member added but does not appear in booking slots — The team member needs working hours configured in the Availability table. Go to Staff → Scheduling → Availability and add time blocks for that team member.
Authorize in Square
Once your Square Developer application and Square Appointments are configured, connect your Square account to Newo.ai using OAuth 2.0. 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_idandsquare_secret_idusing the Application ID and Personal Access Token from your Square Developer application.Click Save on both attributes.
In the
square_oauth_codeattribute 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_codeattribute 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.
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 attributes listed in the table below, clicking Save after each.
Click Save + Publish All.
Attribute | Required | Description |
| Yes | Application ID from your Square Developer application |
| Yes | Personal Access Token from your Square Developer application |
| Yes | One-time OAuth authorization code from the Authorize step |
| Yes | The Square location to use (auto-populated as a dropdown after authorization) |
| No | API base URL (default: |
| No | Login URL (default: |
| No | Enable availability checking (default: |
| No | Enable booking capability (default: |
| No | Enable cancellation capability (default: |
🗒️ 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_locationsis populated.Catalog: Start a new conversation and verify that
square_catalogis 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_idandsquare_secret_idare set correctly.Access token — Verify that
square_access_tokenwas populated after publishing. If it is empty, repeat the authorization flow.Location selection — Confirm
square_locationshas a value selected. It should be auto-populated after authorization.Service catalog — Confirm
square_catalogis not empty. Services must be defined in Square Catalog with the product typeAPPOINTMENTS_SERVICE.Feature flags — Verify that
square_enable_slot_check,square_enable_booking, andsquare_enable_cancellationare set toTrueas 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.