> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GoHighLevel

> Connect a GoHighLevel sub-account with a Private Integration Token and let an agent book into its calendars

Check availabilityBookFindRescheduleCancelList

GoHighLevel is a scheduling system *and* a CRM, and both matter here. The calendar owns its slot duration, buffers, minimum notice and open hours, so Roark maps the agent's six actions onto it. The CRM matters because **a GoHighLevel appointment belongs to a contact**: every booking writes a contact into your sub-account.

Roark uses GoHighLevel's **v2 API**, served from LeadConnector.

***

## What you need

| | |
| :- | :- |
| **Credential** | A sub-account **Private Integration Token**, beginning `pit-` |
| **Plus** | The **Location ID** of the sub-account the token was minted in |
| **Where the token comes from** | The sub-account → **Settings → Private Integrations** |
| **Where the Location ID comes from** | The same sub-account → **Settings → Business Profile** (it also appears in the app URL, after `/location/`) |

> [!WARNING]
>
> The token and the Location ID are **one credential**. A Private Integration Token does not name its own sub-account, and every calendar call needs one, so the two are stored and verified together — a token minted in a different sub-account is refused. The same applies when you rotate: send both.

> [!NOTE]
>
> It must be a **sub-account (location)** Private Integration, not an agency-level one. An agency token cannot act on a location's calendars.

### Scopes to select on the Private Integration

Tick exactly these when you create the integration. GoHighLevel's picker lists them with friendly labels; the API names are what Roark checks against.

| Scope | Why it is needed |
| :- | :- |
| `calendars.readonly` | Lists the sub-account's calendars and reads their free slots |
| `calendars/events.readonly` | Finds a caller's appointment and lists their upcoming ones |
| `calendars/events.write` | Books, moves and cancels appointments |
| `contacts.readonly` | Finds the contact a caller's appointments belong to |
| `contacts.write` | Creates or updates the contact a booking is made for — GoHighLevel requires one |
| `locations.readonly` | Confirms the token really belongs to the Location ID you gave |

A token missing any of these is refused when you connect, rather than failing later on a live call.

***

## Connect the account

**1. Create the Private Integration**

In the sub-account, open **Settings → Private Integrations**, create an integration, tick the six scopes above, and copy the token. It is shown once.

**2. Copy the Location ID**

**Settings → Business Profile** shows the sub-account's Location ID, for example `ve9EPM428h8vShlRW1KT`.

**3. Add GoHighLevel to your agent**

In Roark, open your agent built on Roark, go to the **Tools** tab, and in the **Calendars** card choose **Add GoHighLevel**. Name the account, pick the time zone the business keeps, and paste both the Location ID and the token.

![The Account step of the calendar setup dialog for GoHighLevel, with the Location ID and Private Integration Token fields](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/connect-gohighlevel.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=444d99438c4fec96352b59772493b915)

**Verify and connect** checks the pair against GoHighLevel before anything is stored.

**4. Pick the calendars the agent may book into**

Each appointment type points at one of the sub-account's calendars, with a line telling the agent when it fits. The calendar keeps its own rules — length, buffers, notice and open hours — exactly as a Cal.com event type does.

![The Appointment types step, with one bookable thing per kind of appointment and a line describing when each fits](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/appointment-types.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=87752cb767c8a7782c401472821784fd)

**5. Switch on the tools**

GoHighLevel supports all six actions, including a real reschedule.

![The Tools step with the six calendar actions and the Test bookings switch](https://mintcdn.com/roark/04duxFHL38Z0zeKF/images/calendars/tools.png?fit=max\&auto=format\&n=04duxFHL38Z0zeKF\&q=85\&s=0f1c4dfb00344f1147db614da2e84334)

Prefer the API or the CLI?

```bash CLI theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark connections calendar create \
  --provider GO_HIGH_LEVEL \
  --label "Riverside clinic" \
  --api-key pit-... \
  --go-high-level-location ve9EPM428h8vShlRW1KT \
  --timezone America/Chicago
```

```bash cURL theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -X POST https://api.roark.ai/v1/connections/calendar \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "GO_HIGH_LEVEL",
    "label": "Riverside clinic",
    "apiKey": "pit-...",
    "goHighLevelLocation": "ve9EPM428h8vShlRW1KT",
    "timezone": "America/Chicago"
  }'
```

***

## GoHighLevel specifics

> [accordion] Every booking writes a contact
>
> `contactId` is required to create an appointment and there is no inline attendee field, so each booking upserts a contact in your sub-account from what the caller gave: their name, and their email and phone number when they gave them. An existing contact is **updated**, following your sub-account's own duplicate-contact rules; a caller Roark has never seen becomes a new contact.
>
> This is a write beyond the calendar, and it is the only way to book at all — worth knowing if automations in your sub-account fire on contact creation.

> [accordion] The caller's email is optional
>
> Because the booking goes through a contact, and the contact can be matched on a phone number alone, an agent that cannot get an email spelled out over the phone can still book. Supply an email where the caller gives one: GoHighLevel's own confirmation automations need it.

> [accordion] Availability is read 31 days at a time
>
> GoHighLevel refuses a free-slots query wider than 31 days. A caller asking about a longer range is answered from several queries; you do not have to do anything.

> [accordion] Calendars that offer several lengths
>
> Where a calendar lets the booker choose a length, pin one on the appointment type (`durationMinutes`). Unlike Calendly's, this is not redundant: GoHighLevel takes the duration on the availability read, so it decides which slots are offered in the first place. Leave it off and the calendar's own slot duration applies.

> [accordion] The "Roark reference" line on appointments
>
> GoHighLevel appointments carry no metadata or custom fields, so Roark writes its booking id into the appointment's **description**, as a trailing `Roark reference:` line after whatever the caller asked to pass on. It is what lets a booking whose answer never came back be reconciled instead of duplicated. You will see it in your own GoHighLevel calendar; leave it in place.

> [accordion] Finding an appointment when the caller names no dates
>
> A lookup with no window reads from **7 days back to 90 days ahead** — back far enough to find an appointment a caller has just missed, forward far enough to cover any horizon a calendar offers.

> [accordion] Appointments awaiting confirmation
>
> An appointment GoHighLevel leaves in its `new` status is reported as not yet confirmed, and the agent tells the caller the time is *requested*. Statuses that mean cancelled are reported as cancelled.

> [accordion] No slot holds
>
> GoHighLevel cannot hold a time while the caller thinks about it — its nearest feature blocks a slot out with no expiry, which a dropped call would leave closed until somebody noticed. A slot that goes between being offered and being booked comes back as `SLOT_TAKEN`, with fresh times to offer.

***

## Rotating the token

Send the new token **and** the Location ID it belongs to. The pair is verified before it is stored, and a verified pair returns a connection in `INVALID_CREDENTIALS` to `ACTIVE`.

```bash CLI theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark connections calendar update <connection-id> \
  --api-key pit-... \
  --go-high-level-location ve9EPM428h8vShlRW1KT

roark connections calendar check <connection-id>
```

```bash cURL theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -X PATCH https://api.roark.ai/v1/connections/calendar/$CONNECTION_ID \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "pit-...", "goHighLevelLocation": "ve9EPM428h8vShlRW1KT" }'
```

***

## Troubleshooting

| What you see | What it means |
| :- | :- |
| The connection is refused when you connect | The token is missing one of the six scopes, it belongs to a different sub-account than the Location ID, or it is an agency token |
| No calendars are listed | The sub-account has no calendars, or the token lacks `calendars.readonly` |
| A booking failed but a contact was created | The contact upsert comes first. Re-booking reuses that contact rather than creating another |
| Status is `INVALID_CREDENTIALS` | The Private Integration was deleted or its scopes were changed. Create a new one and [rotate](#rotating-the-token) |
| Disconnect refused with a `409` | A calendar tool is still bound to the connection; the refusal names the tools |

***

## Next steps

> [card] [Calendars overview](https://docs.roark.ai/documentation/integrations/calendars/overview.md)
>
> The six tools, slot ids, test bookings and limits

> [card] [Tools as code](https://docs.roark.ai/documentation/config-as-code/tools.md#calendar-handler)
>
> Declare a GoHighLevel tool in your config

> [card] [Cal.com](https://docs.roark.ai/documentation/integrations/calendars/cal-com.md)
>
> Connect a Cal.com account with an API key

> [card] [Test tool calls](https://docs.roark.ai/documentation/recipes/tool-call-testing.md)
>
> Exercise booking paths in simulations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.