GoHighLevel in Agent Builder

The GoHighLevel step lets an agent work in one sub-account: contacts, opportunities, calendars, conversations and invoices. A step on the agent's path does one action. The same step, attached to an Intelligence step, can offer several, and the AI decides which to call. There are 55 actions. GoHighLevel has no trigger of its own, so the agent starts from a schedule, from an email, or from another system's alert.

app.centrus.ai/app/agents/workflow-builder

Agents

Build modular AI workflows with reusable nodes

Quote requests

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

Quote request

Outlook · Inbox/Quotes

Add them to the pipeline

GPT-5.6 Terra

Contacts and opportunities

Upsert contact

2

AI builderMap

1. 1GoHighLevel in the Integration group of the Nodes panel. It is the last step in that group.
2. 2The step used as a tool. Its summary names only the first action, Upsert contact, even though two are ticked.
3. 3Connection: this agent's sub-account, shown by the location name.
4. 4Actions: what the AI may call. Here, add a contact and open an opportunity.
5. 5Require approval is off. Turn on Pause for approval if someone should agree before each call.

Centrus works alongside GoHighLevel. Contacts, pipelines and calendars stay there. A typical agent adds a contact and an opportunity when a quote request arrives, emails a weekly pipeline summary, or sends one follow-up to each quiet conversation. Chat uses a separate connection: connecting this step does not connect chat, and connecting chat does not connect the step. For asking questions in chat, see GoHighLevel in chat. For how every integration is connected, see Integrations overview.

Open the agent and find GoHighLevel in the Integration group of the Nodes panel. It sits at the bottom of that group, under Cin7 Core. Its line reads: Looks up and updates GoHighLevel contacts, opportunities, calendars, conversations, and invoices, using the Private Integration Token and location you connect. Drag it onto the canvas and connect the step before it to its left-hand side. A new step is already set to Search contacts, so that is the summary you see until you choose a different action. Its name on the canvas starts as GoHighLevel.

Quote request

Outlook · Inbox/Quotes

GoHighLevel

Search contacts

2

1. 1GoHighLevel in the Integration group. Drag it onto the canvas.
2. 2The new step. It starts on Search contacts until you choose another action in Endpoint.

On a phone, Agent Builder shows the canvas only. The Nodes panel is hidden on screens narrower than 768 pixels and the Details panel on screens narrower than 1,024 pixels, so you can follow an agent's steps on a phone but need a tablet or computer to add a GoHighLevel step or change its settings.

09:41

Centrus

Agents

Build modular AI workflows with reusable nodes

Chase overdue invoices

Save and Publish

Quote request

Outlook · Inbox/Quotes

Add them to the pipeline

GPT-5.6 Terra

Contacts and opportunities

Upsert contact

The connection belongs to this agent alone. It is one sub-account, not the agency view, and it is separate from the organisation's GoHighLevel connection in chat. One connection covers every GoHighLevel step in the agent, so you only connect once per agent. It is not shared with Outlook, BigChange or any other step.

You need three values from inside the sub-account. The connect window says to open Settings, then Private Integrations, and to copy a token that starts with pit-. The Location ID is on Business Profile, or the id after /location/ in the address bar. Timezone is the sub-account's zone, written like Europe/London. The window also lists the scopes to tick: contacts, opportunities, calendars, calendar events, conversations and locations, including the write scopes. Connecting only proves that locations can be read. A missing scope fails later, when the step calls that part of GoHighLevel. A white-label sub-account uses the same token and the same host. If you do not have these values, ask the person who administers the sub-account.

1. 1Save the agent with Save draft. Until it has been saved once, the Connection section reads Save this workflow as a draft first, then connect the account. and Connect is greyed out.
2. 2Select the GoHighLevel step. In the Details panel, open Connection and click Connect.
3. 3In the Connect GoHighLevel window, enter Private Integration Token, Location ID and Timezone, then click Connect.
4. 4Centrus reads that location with the token. If GoHighLevel accepts it, Connection reads Connected, followed by the location's name. Meridian FM's sub-account shows as Meridian FM.

Centrus checks the three values when you click Connect. An empty location id, a token that does not start with pit-, or a timezone that is not a zone name such as Europe/London is refused, and nothing is saved. If GoHighLevel rejects the token, the window stays open with that message. A successful connect returns Successfully connected to GoHighLevel. Try a dry run afterwards, as described under Test before it goes live.

Reusing a connection. If you have already connected GoHighLevel on another agent you created, choose that agent under Copy from existing agent. Centrus fills in the three fields from it, and you click Connect to save them on this agent. The list only shows agents you created that are not archived and have a GoHighLevel connection, so an agent someone else shared with you never appears. The names in the list do not include the location, so two agents on different sub-accounts look the same until you open one. When there are none, the box reads No other agents with this connection.

Sharing and copying the agent. When you share an agent, its GoHighLevel connection stays on the agent. People you share it with cannot see or copy the token. Runs use that connection, because GoHighLevel has no per-person sign-in on the step. When you duplicate an agent, the steps are copied but the connection is not, so connect GoHighLevel again on the copy. Copy from existing agent makes that quick. For the details, see Share an agent.

Disconnecting. Disconnect removes the credentials from this agent only. Its GoHighLevel steps stop working until someone connects it again. Other agents keep their own connections, and the chat connection is left as it is.

Select the step and open Endpoint in the Details panel. The section's own line reads Choose the GoHighLevel action this step should run. Endpoint tool type holds all 55 actions in one list that starts with Search contacts. The list has no search box and no headings, so the tables at the end of this guide are the quickest way to find the exact name you need.

Keep Set endpoint fields here when the step sits in the agent's path. Let AI populate endpoint fields hides the fields so that an AI can fill them, but on a step in the main flow nothing fills them in when the step runs. To have an AI choose the values, attach the step to an Intelligence step as a tool, as described below.

Each action then shows its own fields in a box titled with the action's name. The label is the first sentence of the field's description, or the field name with spaces if it has none, and a required field has an asterisk. Search opportunities has Q, Pipeline Id and Status. Q is the search text. Status is typed as open, won, lost or abandoned. Search contacts labels its search box Name, email, or phone.

On the main path, only seven actions use what you type: Search contacts, Search opportunities, Search conversations, List appointments, List invoices, List form submissions and List transactions. A handful of lookups that need no input also run, including List pipelines, List calendars, List calendar groups, List location tags and Search businesses. Every other action, including Upsert contact, Create opportunity, Send message and Get contact, ignores the boxes and calls GoHighLevel with nothing in them. The step then fails its own checks, for example email or phone is required, even though Email is filled in. Put those actions on an Intelligence step, where the AI's values are sent.

To use a value from an earlier step on one of the seven lists, open Step data references at the top of the Details panel and click a field to copy its reference, then paste it into a text field. An email trigger's details are not listed there. Type them, for example {{ trigger.json.fromAddress }} or {{ trigger.json.subject }}. Inside a Loop, the current item is {{ item.json }} followed by the field name you saw on a test run. Monetary Value on Create opportunity is a number field, so a reference pasted into it is turned into a number and lost. That only matters once the action is running as a tool, because on the main path the box is not sent at all.

What a list passes on. Search contacts, Search opportunities, Search conversations, List invoices, List form submissions and List transactions each pass on one item per row, up to five pages of 20, so 100 rows. List appointments is one response, at most 100 events, and it needs a calendar id. Later steps reach those items through Step data references, and an Intelligence step can read them together. To do something once per row, put the next step inside a Loop, described in Conditions, loops and approvals.

As a tool for an AI step. Connect a GoHighLevel step to the Tools side of an Intelligence step and its Details panel changes. Instead of one endpoint, Actions lets you choose several, with a search box, and the AI decides when to call each one and fills in the fields itself. The canvas summary still shows only the first action's name. Upsert contact needs an email or a phone, and a first name or a name. Create opportunity needs a pipeline id, a contact id and a name, and leaves the status as open if you do not set one.

Quote request

Outlook · Inbox/Quotes

Add them to the pipeline

GPT-5.6 Terra

Contacts and opportunities

Upsert contact

1

1. 1The GoHighLevel step attached to the Intelligence step as a tool.
2. 2Actions: the actions the AI may call. These values are sent.
3. 3Pause for approval: each call the AI makes waits for someone to approve it in the Runs panel.

Pause for approval appears on every GoHighLevel step but only applies to calls an AI makes, so it has no effect on a step in the main flow. To ask someone before a main-flow step changes GoHighLevel, put an Approval step in front of it. Do not give an Intelligence step the long lists (Search contacts, Search opportunities, Search conversations, List appointments, List invoices, List form submissions or List transactions). Centrus warns you, because the whole list would be loaded into the AI. Use the Ingest step for those, as described under Limits and good to know.

GoHighLevel has no trigger of its own. Nothing in the sub-account starts a run by itself. Put another trigger at the start of the agent, then the GoHighLevel step. Three patterns cover the usual work.

An email. Email received starts a run for each new message in one Outlook folder or one Gmail label. Point it at Inbox/Quotes, set From contains to @northgatehousing.co.uk and Subject contains to quote, and the next step can add the sender as a contact. The trigger hands on fromAddress, fromName and subject. Setting up the mailbox, the filters and what each run receives is covered in Start an agent when an email arrives.

A schedule. A Schedule Trigger starts the agent on a clock, with no alert from GoHighLevel. Monday at 08:00 suits a pipeline summary. Weekdays at 09:00 suits a follow-up pass. The trigger itself is free. The run still costs 1 credit, like any other run. For the trigger choices, see Choose how an agent starts.

Another system's alert. A BigChange, Simpro, Joblogic, Fixflo, Freshdesk or Ostara webhook can start the agent, and a GoHighLevel step later in the path can add a contact or an opportunity from that alert. The webhook uses that other system's connection, not the GoHighLevel one, so the agent needs both. The general picture is in Start an agent from a system alert. Alerts and schedules only start runs once the agent is published. Run now works on drafts.

Quote request

Outlook · Inbox/Quotes

Add them to the pipeline

GPT-5.6 Terra

Contacts and opportunities

Upsert contact

Quote requests adds a contact and an opportunity when Northgate Housing emails about a quote. Quote request watches Outlook, Inbox/Quotes, with From contains set to @northgatehousing.co.uk and Subject contains set to quote. Add them to the pipeline reads the sender and the subject, for example Sarah Price at sarah.price@northgatehousing.co.uk with the subject Quote for the boiler at Riverside House. Contacts and opportunities gives it Upsert contact and Create opportunity. Upsert matches on the email address and uses the sender's name. Create opportunity uses a pipeline id you already know from List pipelines, names the opportunity from the subject, and leaves the status open. The two writes run as tools, because those actions do not receive boxes filled in on the main path. Each matching email costs 1 credit for the run, at least 2 for the Intelligence step, and 1 for each GoHighLevel call it makes.

Monday at 08:00

Weekly at 08:00 · Mon

Open opportunities

Search opportunities

Write the summary

GPT-5.6 Terra

Email John

1 action enabled

Weekly pipeline summary emails John Martin the open opportunities every Monday at 08:00. Open opportunities uses Search opportunities with Status set to open. That list does use its boxes, and it passes on one item per opportunity, up to 100. Write the summary reads those items together and drafts a short note: how many are open, and which sites they name, such as Riverside House and 12 High Street. Email John sends it from the agent's Outlook connection to john.martin@meridianfm.co.uk. The list is one GoHighLevel call however many rows come back.

Weekdays at 09:00

Daily at 09:00 · Mon, Tue, Wed, Thu, Fri

Inbox threads

Search conversations

Each thread

For each of incoming items

Write the follow-up

GPT-5.6 Terra

Send the follow-up

Send message

Follow up after 7 days sends one SMS to each contact whose conversation has gone quiet. Inbox threads uses Search conversations, which returns one item per thread and does not itself know how old the last reply is. Each thread is a Loop set to each incoming item, so the body runs once per thread. Write the follow-up reads that thread with Get messages (20 messages at most) and calls Send message only when the last reply is older than 7 days. Send message is a tool on that Intelligence step, with type SMS. On the main path the message box would not be sent. The Loop's summary reads For each of incoming items. Connect the Intelligence step back into the Loop so it can move on. See Conditions, loops and approvals.

A dry run is the safe way to try a GoHighLevel step. Open Runs in the toolbar, click Run now and choose Dry run (no actions performed). Read actions such as Search opportunities, List pipelines and Get contact call GoHighLevel for real, so you see real rows. Write actions, such as Upsert contact, Create opportunity and Send message, are skipped, so nothing in the sub-account changes. Run for real performs every action, including the writes.

{
  "handles": { "main": 12 },
  "items": {
    "main": [
      {
        "name": "Riverside House boiler",
        "status": "open",
        "monetaryValue": 4800
      }
    ]
  }
}

Open a step in the run to see its output. A list's summary is Found, then the count, then GoHighLevel row or rows. The panel shows the first 50 items, and later steps still receive all of them. A write that actually ran summarises with an internal action name rather than Upsert contact. A dry run of a write does the same, and says it was not performed. Read the output, not that line, to see what was sent. A dry run costs 1 credit for the run. The steps themselves are not charged. A real email or a real Monday schedule is not a dry run, so test writes with Run now first. For Run now, dry runs and the Runs panel in full, see Test an agent before it goes live.

A GoHighLevel step costs 1 automation credit each time it runs successfully, whatever the action and however many rows come back. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. GoHighLevel has no trigger. A run started by a schedule, an email or another system's alert still costs 1 credit for the run, and that trigger itself is free.

Inside a Loop, the GoHighLevel step is charged on every pass that succeeds, so a Loop that sends 40 messages costs 40 credits for that step. The Loop itself is free. A single list is one credit, which is cheaper than fetching the same records one at a time. An Intelligence step costs at least 2 credits, and more as the text it reads gets longer. For allowances, limits and how to see what each run cost, see Automation credits and usage limits.

• Dates are year first. Get free slots needs a start and an end, written as 2026-10-09, in the connection timezone. The range cannot be longer than 31 days. List appointments uses the same shape. If you leave its dates empty, the window is today through the next 7 days, and the response holds at most 100 events.
• 100 rows on a list, 500 through Ingest. Search contacts, Search opportunities, Search conversations, List invoices, List form submissions and List transactions fetch up to five pages of 20 on the step. Ingest can ask for up to 25 pages, which is 500 rows. List appointments does not page: one response, 100 events, and it needs a calendar id. Search businesses returns at most 20 businesses and has no further page.
• Wide lists use Ingest. Do not attach those seven lists to an Intelligence step. Ingest offers them under GoHighLevel. See Large lists.
• Messages. Get messages returns at most 20. Send message accepts SMS or Email only. An email needs a subject and a body. WhatsApp and other social channels are refused. The message is a real send.
• Tags. Add contact tags adds the tags you name. Upsert contact and Update contact replace the contact's tags with the ones you send, so a short list removes the rest. Tags and Followers are plain text boxes, and the action only accepts a list, so a line you type in the box is not sent. Use the step as a tool if the AI can pass a real list, and check a dry run before you rely on it.
• What you cannot do. There is no action to create an invoice. Record invoice payment records a payment already taken and does not charge a card. There is no delete for an appointment: Update appointment can set Appointment Status to cancel it, and one occurrence of a recurring appointment uses a special event id. There is no list of workflows, so Add contact to workflow needs the id from GoHighLevel.
• 30 seconds. A call is given 30 seconds. After that the step fails. If GoHighLevel is busy, the message is GoHighLevel is busy. Try again in a moment. and the run can retry.
• Per-user integration mode. GoHighLevel only works with the agent's own connection. In per-user mode the Connection section says the step still uses that connection. Keep agents that use it on the agent's own connection. A scheduled run has nobody to borrow an account from anyway.
• The location is fixed. Actions do not ask for a location id. Every call uses the sub-account you connected. To work in a second sub-account, use a second agent.
• Writes are claimed once. Before a write, the run records that this step is about to change GoHighLevel. A repeat of the same write in the same run is skipped. A dry run does not record that claim and does not call GoHighLevel for the write.

• GoHighLevel is not connected on this automation. Open the step's Connection section and click Connect. If you have duplicated the agent, the copy needs its own connection. A chat connection does not count.
• Private Integration Token must start with pit-. Create the token under Settings, Private Integrations, inside the sub-account, not the agency view. Nothing is saved until the token is accepted.
• Location ID is required. Copy it from Business Profile. The field was empty. You can also copy the id after /location/ in the address bar.
• Timezone is required or Timezone must be an IANA zone, for example Europe/London. London on its own is refused. Use Europe/London.
• GoHighLevel refused the token. The token was rejected, or a scope is missing. Connecting only checks that locations can be read, so a later action can fail this way even after a successful connect. Edit the Private Integration, tick the missing scope, then disconnect and connect again.
• Stored GoHighLevel credentials are incomplete. The saved connection is missing the token or the location id. Disconnect and connect again with all three values.
• Could not verify GoHighLevel credentials. GoHighLevel did not accept the three values. Check the token, the location id and that you are in the sub-account.
• email or phone is required, firstName or name is required, or pipelineId, contactId, and name are required, even though the boxes are filled in. On the main path those actions do not receive the boxes. Attach the step to an Intelligence step, or use one of the seven lists, which do receive them. See Choose an action.
• tags is required. Add contact tags and Remove contact tags only accept a list, and the box is plain text, so a line you type does not count. The same applies to Followers.
• Free slots cover at most 31 days. Narrow startDate and endDate. endDate must be on or after startDate means the two dates are the wrong way round. Both boxes are labelled YYYY-MM-DD.
• calendarId is required. List appointments and Get free slots need a calendar id from List calendars.
• type must be SMS or Email. Send message refuses WhatsApp and other channels. SMS needs message. Email needs subject and html or message.
• Connect a timezone on this GoHighLevel account before using a date or a time without an offset. The connection has no timezone, so a time such as 2026-10-09T09:00 cannot be placed. Reconnect and set Timezone.
• GoHighLevel is busy. Try again in a moment. Wait and run it again. A long list can also hit this if you page through Ingest.
• No action selected. Rare, because a new step starts on Search contacts. Choose one under Endpoint tool type if the summary reads No endpoint selected.
• An alert never starts the agent. GoHighLevel does not listen for alerts. Check the Email received trigger or the Schedule Trigger, and publish the agent. See Start an agent when an email arrives.
• No other agents with this connection. None of the agents you created has a GoHighLevel connection. Enter the three values by hand.
• You can only copy credentials from agents you have created. The agent you picked was shared with you, or it is archived. Connect by typing the three values.

The GoHighLevel step offers 55 actions: 24 read from the sub-account and 31 change it. Every call goes to https://services.leadconnectorhq.com. The location is taken from the connection, not from a field on the action. On the main path, only the seven lists named under Choose an action use the values you type. The other actions receive those values when an Intelligence step calls them as tools.