Authorize your Square account so the agent can list services and staff, check availability, and book appointments
Authorizing Square creates an agent that lists your bookable services and staff, checks availability, and creates bookings in Square Appointments, on the web widget and every other channel. Square is connected in the browser, not with lua integrations, and the same authorization also enables the shopping tools.Verified against lua-cli 3.33.0.Before you begin
A Square account with Square Appointments enabled: services with a duration and price, and team members with booking profiles and working hours.
An email Lua can link your admin account to: the merchant owner’s email, else the main location’s business email, else the first team member marked as owner.
1
Browser: authorize Square
Open https://auth.heylua.ai/square/auth, sign in to Square, pick the business if asked, review the permissions, and select Allow. Lua requests appointments and appointment settings (read and write), team members (read), customers (read and write), the merchant profile (read), and the items, orders, and payments grants used by the shopping tools.
Square's permission screen for Lua.
2
Admin dashboard: finish setup
Square redirects to the admin dashboard, where the agent exists already and a persona is being drafted from your business details. Tell the persona which services to offer and how to confirm a booking.
The admin dashboard after a successful Square authorization.
3
Try it
On the web widget or a connected channel, ask “Can I get a haircut with Sarah on Thursday afternoon?”. The agent reads the booking profile, finds the service and team member, searches availability, and creates the booking once the end user confirms a slot.
Read the business booking profile: booking policy, lead times, cancellation and rescheduling rules, and daily limits.
List location booking profiles and team member booking profiles, and retrieve one team member’s profile.
Search availability for one or more service segments, optionally per team member and location, in a window of at least 24 hours and at most 32 days; search availability for rescheduling an existing booking.
Create a booking for a location, start time, service variation, and team member, with an optional customer note.
List a customer’s bookings and retrieve one by ID; create or read the end user’s Square customer record.
The agent can’t cancel a booking or finalize a reschedule: it shows alternative slots, and the end user changes the booking in Square or with you.
Square isn’t a Unified.to integration type, so there is no Integrations.passthrough('square', …). For cancellations or other endpoints the tools don’t cover, write a tool that calls Square’s API with your own access token from env() (see Call your API). To add your own tools to this agent, run lua init --agent-id <id> in a new folder (find the ID with lua agents --json --ci), then follow Add a tool.
One Square account per agent; all its locations are reachable.
Availability searches cover 24 hours to 32 days per query.
Confirmations and reminders come from Square’s own notification settings, not from the agent; for reminders the agent sends itself, see Send proactive messages.
The business wasn’t selected, a permission was declined, or Square couldn’t provide an email to link (owner, main location, or an owner team member). Fix the account in Square and start again at auth.heylua.ai/square/auth.
No availability is found
The service needs a duration and a price, at least one team member assigned to it, and working hours at the location. Configure them in Square Appointments and ask again.
No staff members are offered
Team members need a booking profile and must be enabled at the location the agent searched. Create the profiles in Square and, when the persona names a location, make sure staff are assigned there.
