> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GoHighLevel agent functions
> GoHighLevel tools for Retell AI agents: look up and update contacts, add tags, work opportunities and tasks, and book the sub-account's calendars.
A [connected GoHighLevel sub-account](/integrations/gohighlevel) 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](/integrations/overview#run-tools-before-or-after-the-call-or-chat), and no [contact sync](/integrations/gohighlevel-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](/integrations/overview#use-integration-tools-in-an-agent) for how to add and configure them.
| Tool | What it does |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Search Contact** | Find a contact by phone number — typically the caller's number, to identify who's calling |
| **Get Contact** / **Update Contact** | Fetch a contact by ID, or update fields the caller confirms or corrects |
| **Create Contact** | Create a contact for a caller who isn't in the CRM yet |
| **Add Contact Tags** | Tag the contact so your workflows fire on the outcome |
| **List Contact Opportunities** | List the opportunities associated with a contact (up to 50) |
| **Get Opportunity** | Fetch an opportunity by ID |
| **Create Opportunity** / **Update Opportunity** | Create an opportunity in a pipeline you pick, or move one between stages and mark it won or lost |
| **List Contact Tasks** / **Create Task** | List a contact's follow-ups (up to 50), or create one when a follow-up is agreed |
| **Create Note** | Record a summary of the conversation in the contact's Notes panel |
| **List Contact Appointments** | List a contact's appointments (up to 50) when the caller asks about their bookings |
| **Check Availability** | List free slots on a configured calendar for a time window |
| **Book Appointment** | Book a configured calendar for a contact after the caller confirms a time |
| **Get Appointment** | Fetch one appointment by its ID |
| **Reschedule Appointment** | Move an existing appointment to a new start and end time |
| **Cancel Appointment** | Cancel an existing appointment |
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](/build/dynamic-variables) 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](/integrations/cal-com-functions) or [Calendly](/integrations/calendly-functions) 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](/build/dynamic-variables) 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](/integrations/gohighlevel#step-1-create-a-private-integration-token); scope changes take effect without regenerating the token:
| Scope | Used for |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `contacts.readonly` | Search Contact, Get Contact, List Contact Tasks, List Contact Appointments |
| `contacts.write` | Create Contact, Update Contact, Add Contact Tags, Create Task, Create Note |
| `opportunities.readonly` | List Contact Opportunities, Get Opportunity, and reading pipelines when you configure the opportunity tools |
| `opportunities.write` | Create Opportunity, Update Opportunity |
| `locations/customFields.readonly` | Reading custom field definitions when you configure the tools |
| `calendars.readonly` | Check Availability, and reading the calendar list when you configure the booking tools |
| `calendars/events.readonly` | Get Appointment |
| `calendars/events.write` | Book Appointment, Reschedule Appointment, Cancel Appointment |
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
Add GoHighLevel tools to a single- or multi-prompt agent and test them with live requests.
Call GoHighLevel tools from a function node and branch on the result.
Import the sub-account's contacts, write analysis results back, and log conversations as notes.
Map tool responses to variables your agent can use later in the conversation.