Skip to main content
A connected GoHighLevel sub-account gives your agents live tools for the sub-account: identify the caller, tag them to fire workflows, work opportunities, tasks, and notes, and book the sub-account’s calendars. Tools run during a conversation or before and after it, and no contact sync is required.

​
Available tools

These tools appear in your agent’s function menu once the sub-account is connected. See use integration tools in an agent for how to add and configure them.
Chain the tools to change an existing booking: List Contact Appointments returns the caller’s appointments with their IDs, then Reschedule Appointment or Cancel Appointment acts on the one the caller names. Map the ID to a dynamic variable so the second tool can use it.

​
Book the sub-account’s calendars

Appointments are created on the sub-account’s own calendar and linked to the contact, so they behave like any other GoHighLevel appointment — which makes this the natural calendar choice when your scheduling and your contacts live in the same sub-account. If your team books through Cal.com or Calendly instead, connect those. The time inputs differ by tool, and none of them need UTC conversion — the agent supplies local ISO 8601 datetimes plus the caller’s IANA timezone:
  • Check Availability and Reschedule Appointment take a start time and an end time.
  • Book Appointment takes the one time the caller agreed to, plus the contact ID (usually from an earlier Search Contact call) and an optional appointment title. It doesn’t take an end time: GoHighLevel derives the appointment’s length from the calendar’s slot duration, and rejects a slot that’s no longer free. Bookings are created with the status confirmed.

​
Pick the calendar

Check Availability and Book Appointment each work against one calendar, set by the calendar_id input when you configure the tool: it lists the sub-account’s calendars for you to pick from. Add one tool per calendar the agent should offer, or let the agent fill calendar_id from a dynamic variable to route to a calendar decided mid-conversation. If the calendar_id field asks you to type a value instead of offering a list, Retell couldn’t read the sub-account’s calendars. A missing calendars.readonly scope is the usual cause; a revoked token, the wrong Location ID, or a sub-account with no calendars produces the same result.

​
How the booking tools behave

  • Availability windows are capped at 31 days. GoHighLevel limits each availability check to 31 days (as of August 2026); if the agent asks for a longer range, Retell caps it at 31 days from the start time. For a caller asking about next month, have the agent check again with a later start date.
  • Cancelling sets the appointment’s status to cancelled rather than deleting it, so the appointment stays on the contact’s timeline and your cancellation workflows still fire.
  • Rescheduling needs both a new start and end time, and GoHighLevel validates them against the calendar’s rules, so confirm the new slot with Check Availability first.

​
Required scopes

Each tool works only if the Private Integration holds its scope, granted in Step 1 of connecting; scope changes take effect without regenerating the token: GoHighLevel’s task, note, tag, and appointment-listing endpoints all sit under the contact, so the two contact scopes cover them. The booking tools are separate and need the calendars scopes. A tool call that hits a missing scope fails with an authorization error, and because GoHighLevel returns the same error for a revoked token, the connection can end up flagged with a Connection error tag. Three scopes matter before any call is made, when Retell builds a tool’s config dialog. Without opportunities.readonly, the opportunity tools can’t offer a pipeline to pick; without calendars.readonly, the booking tools can’t offer a calendar; and without locations/customFields.readonly, the contact tools’ custom field list fails to load.

​
Troubleshooting

That’s almost always a missing scope on the Private Integration — opportunities.readonly/opportunities.write and locations/customFields.readonly are the ones most often skipped. Edit the integration in GoHighLevel and grant the scope for the capability that’s failing; scope additions apply without regenerating the token. If the failing calls also flagged the connection with a Connection error tag, open the connection’s settings and click Reconnect to re-test and clear it.
Check the calendar on the tool first: it must be the calendar that actually holds the openings. Then check that calendar’s availability in GoHighLevel for the window the agent asked about, including its working hours and any date-specific overrides.
Retell books through GoHighLevel’s own validation, so the calendar can still refuse the slot: someone else may have taken it between the two calls, or it may breach the calendar’s minimum scheduling notice or per-day appointment limit. Have the agent re-check availability and offer another time.
Retell adds exactly the tag names the tool call supplies. GoHighLevel workflows trigger on exact tag matches, so configure the tool’s tag values to match the tag your workflow watches, letter for letter.

​
FAQ

Yes. The pipeline and stage are fixed when you configure the Create Opportunity tool; the agent fills in the contact and details, not the pipeline. If you work more than one pipeline, point a separate tool at each.
Yes, two ways. Add one Book Appointment tool per calendar, each with its own fixed calendar_id, and tell the agent in the prompt which to use for which request. Or configure a single tool whose calendar_id comes from a dynamic variable, and set that variable earlier in the conversation.
Yes. Book Appointment books for a specific contact, so the appointment appears on that contact in GoHighLevel and List Contact Appointments returns it.

​
Next steps

Integration tools for prompt agents

Add GoHighLevel tools to a single- or multi-prompt agent and test them with live requests.

Integration tools in conversation flow

Call GoHighLevel tools from a function node and branch on the result.

GoHighLevel contact sync

Import the sub-account’s contacts, write analysis results back, and log conversations as notes.

Dynamic variables

Map tool responses to variables your agent can use later in the conversation.