This guide walks you through setting up the Newo.ai integration in a GoHighLevel sub-account. It covers installing the integration (from the GoHighLevel Marketplace or manually with a private integration token), authorizing the connection, and configuring AI-powered booking, CRM sync, and pipeline automation.

🗒️ NOTE

The Newo.ai app is not yet live on the GoHighLevel Marketplace. Please use "Method B: Private Integration Token" to connect a Newo agent to GoHighLevel.

Install from the GoHighLevel Marketplace (In Progress)

The fastest way to connect Newo.ai to GoHighLevel is through the GHL Marketplace. The Marketplace install automatically scans the business website and Google Maps data to create a fully trained AI Employee.

Open the GoHighLevel App Marketplace in your sub-account (located in the left sidebar).
Search for Newo.ai and select the app.
Click Install.
The Agent Creator launches automatically. It scans the business website and Google Maps data to learn business hours, services, pricing, and location.
Within moments, a fully initialized AI Employee is created and ready to handle calls.

After installation, Newo.ai adds a custom page directly to the GoHighLevel sidebar. Two new items appear in the left sidebar: Newo and Newo AI Voice Receptionist. These provide direct access to the Newo.ai integration without leaving GoHighLevel.

🗒️ NOTE

If you installed the app from the Marketplace, the OAuth authorization is typically completed automatically. You can skip the manual OAuth flow below and proceed directly to calendar configuration.

Create a new project (manual setup)

If you are not using the Marketplace install, create a new project manually in the Newo.ai Builder and add the GoHighLevel integration module with the following details:

Idn: gohighlevel
Title: gohighlevel
Module: ghl_integration

To create a new project, follow the steps in Create a new project.

Authorize GoHighLevel

Two authentication methods are available. Use the ghl_auth_type attribute in the Builder to select the method you want to use (oauth or token).

Method A: OAuth (In Progress)

Use this method if the agent was installed directly from the GoHighLevel Marketplace. Authentication is completed automatically on creation and no additional steps are required.

If re-authentication is needed, generate a new OAuth code manually:

In the Builder, navigate to Attributes > GoHighLevel Settings and set ghl_auth_type to oauth.
In the ghl_oauth_code attribute, click the authorization link. You will be redirected to the LeadConnector login page.
Log in and confirm permissions.
Select your Sub-Account.
After the redirect, copy the text from the dialog.
Paste it into the ghl_oauth_code field.
Click Save.
Click Publish All.

⚠️ CAUTION

The OAuth code is single-use. If it expires or fails, you must repeat the entire authorization flow to generate a new code.

🗒️ NOTE

OAuth only works for agents created via the GHL Marketplace. If you need to authorize an existing agent that was not created through the Marketplace, use Method B.

Method B: Private Integration Token

Use this method to connect an existing agent manually using a Private Integration Token from your GoHighLevel sub-account.

In GoHighLevel, navigate to Settings > Private Integrations.
Click Create new integration.
Enter a Name (required) and a Description (optional).
Enable all of the following scopes:
- contacts.readonly
- contacts.write
- conversations.readonly
- conversations.write
- conversations/message.readonly
- conversations/message.write
- calendars.readonly
- calendars.write
- calendars/events.write
- calendars/events.readonly
- calendars/groups.readonly
- calendars/groups.write
- calendars/resources.readonly
- calendars/resources.write
- businesses.readonly
- businesses.write
- locations.readonly
- locations/customValues.readonly
- locations/customValues.write
- locations/customFields.readonly
- locations/customFields.write
- opportunities.readonly
- opportunities.write
- users.readonly
- workflows.readonly
In the Builder, navigate to Attributes > GoHighLevel Settings and set ghl_auth_type to token.
Copy the generated token and paste it into the ghl_oauth_token attribute in the Builder and click Save.
In GoHighLevel, go to Settings > Business Profile and copy the Location ID.
In the Builder, toggle Show Hidden and paste the Location ID into the ghl_location_id attribute. Click Save, then Publish All.

Connect a calendar

Before configuring calendar selection, add a staff user and create a calendar in GoHighLevel.

Go to Settings > My Staff and click Add User if the account owner or team member is not already listed. This user will be linked to the calendar you create next.
Go to Settings > Calendars and click Create Calendar. Complete the setup and save.
In the Newo.ai Builder, click Publish All to refresh the integration data.
Confirm that your newly created calendar is selected in the ghl_calendar attribute.

🗒️ NOTE

You can create more than one calendar if you plan to use Name or Duration selection modes — each service or appointment length requires its own calendar.

Calendar selection logic

The ghl_selection_type setting defines how the AI Employee selects a calendar during a booking conversation. This is the most critical integration setting because it controls the entire downstream booking flow.

Selection modes

Mode	Attribute value	Description	Best for
Single	`Single`	The AI Employee always uses the default booking calendar set in `ghl_calendar`. No dynamic selection occurs.	Single-service businesses (e.g., a dentist with one appointment type).
Name	`Name`	The AI Employee listens for a service name during the conversation and selects the matching calendar. Requires AI selection instructions.	Multi-service businesses with distinct offerings (e.g., a salon with "Haircut" and "Color Treatment").
Duration	`Duration`	The AI Employee detects the requested meeting length and selects the matching calendar. Requires one calendar per duration and AI selection instructions.	Businesses that differentiate appointments by length (e.g., 30-minute and 60-minute sessions).

❗❗ IMPORTANT

Calendar selection modes are mutually exclusive. You cannot combine Name and Duration logic. Choose one mode that best fits the business.

🗒️ NOTE

If you recently added a calendar in GoHighLevel and do not see it in the ghl_calendar dropdown, click Publish All to refresh the calendar list.

Example — Single mode: A dental clinic offers only general checkups. Set ghl_selection_type to Single and select a calendar in ghl_calendar. Every booking goes to that one calendar.

Example — Name mode: A spa offers "Massage" and "Facial" services, each with its own calendar in GoHighLevel. Set ghl_selection_type to Name. When a caller says "I'd like to book a massage," the AI Employee matches "Massage" to the corresponding calendar.

Example — Duration mode: A law firm offers 30-minute consultations and 60-minute strategy sessions, each with a separate calendar. Set ghl_selection_type to Duration. When a caller requests "a 30-minute consultation," the AI Employee selects the 30-minute calendar.

Configure AI selection instructions

The ghl_selection_criteria setting provides the AI Employee with instructions for selecting the correct calendar when ghl_selection_type is set to Name or Duration. This field is required for dynamic selection modes and is ignored in Single mode.

❗❗ IMPORTANT

The AI Employee must return one single value in plain text based on these instructions. Do not include explanations, extra formatting, or multiple values. Extra text may break calendar selection.

Example — Name mode instructions:

Identify the service the caller is requesting.
Available calendars: Consultation, Demo, Follow-Up.
Return only the exact calendar name.

Example — Duration mode instructions:

Extract the appointment duration in minutes from the conversation.
Return only the number: 30 or 60.

🗒️ NOTE

Calendar names in your instructions must match GoHighLevel calendar names exactly. Copy names directly from GoHighLevel to avoid mismatches caused by capitalization, spacing, or punctuation differences.

Configure global settings

All GoHighLevel integration settings are located in the Builder under Attributes > GoHighLevel Settings. The following settings control the AI Employee's permissions and behavior boundaries. Configure them based on the business requirements.

Enable Booking

Set ghl_enable_booking to True to allow the AI Employee to create appointments in GoHighLevel. This grants write access to the calendar. If disabled, the AI Employee can check availability but cannot create bookings.

Enable Cancellation

Set ghl_enable_cancellation to True to allow the AI Employee to cancel existing appointments. Disable this setting to prevent accidental cancellation of important meetings.

Check Existing Client

Set ghl_check_existing_client to True to have the AI Employee look up the caller's phone number in GoHighLevel before starting the conversation. If a matching contact is found, the AI Employee pulls the contact's name and history for a personalized experience.

Save conversation history

Set ghl_enable_client_history to True to save full conversation transcripts (voice and chat) to the contact's Notes section in GoHighLevel.

This setting does not affect booking behavior or AI Employee logic. It is purely for record-keeping.

Value	Behavior
`True`	Transcripts are saved to the GoHighLevel contact record. Useful for debugging, quality review, and team visibility.
`False`	No conversation data is written to the contact record.

Where to find conversation history in GoHighLevel:

Go to the Contacts section.
Find the client and open their profile.
In the right-hand panel, select the Notes tab.
Look for an entry titled "Voice Agent Conversation Log" containing the full transcript.

Common use cases for conversation history:

Quality control: Review how well the AI Employee handled the consultation.
Context transfer: If a human manager follows up, they can read the notes to avoid asking the client to repeat what was discussed.
Dispute resolution: A text record of what was agreed upon is always available.

Detect time zone from conversation

Set ghl_use_timezone_from_conversation to control whether the AI Employee adapts availability to the caller's local time zone.

Value	Behavior	Best for
`True`	The AI Employee detects time zone cues from the conversation (e.g., "I'm calling from London") and displays available times in the caller's local time.	Virtual or remote businesses serving callers in multiple time zones.
`False`	The AI Employee strictly enforces the calendar's configured time zone for all slot times.	Local businesses with a fixed physical location (e.g., dental clinics, gyms, restaurants).

🗒️ NOTE

Enabling this setting does not change the calendar's configured time zone. It only affects how availability is presented to the caller. The AI Employee may ask for clarification if time zone cues are ambiguous.

Pre-load availability on start

Set ghl_check_availability_on_conversation_start to True to allow the AI Employee to check available time slots at the beginning of a call and proactively suggest open times.

This setting works only when ghl_selection_type is set to Single. In Single mode, the AI Employee knows which calendar to check before the conversation begins.

⚠️ CAUTION

Do not enable this setting with Name or Duration logic. The AI Employee will suggest availability from the default calendar before the correct calendar has been identified, resulting in incorrect slot suggestions.

Sync call status

Set ghl_sync_conversation to True to sync final call outcomes back to GoHighLevel after a conversation ends. This setting is optional — enable it only if you use GoHighLevel workflows triggered by call status changes.

Status	Meaning
`completed`	The conversation connected successfully.
`voicemail`	The AI Employee reached an answering machine.
`busy`	The line was busy.
`no-answer`	The phone rang but the contact did not pick up.
`failed`	A connection error occurred.
`canceled`	The call was canceled before connecting.

For details on building automations with these statuses, see GoHighLevel workflow automation.

Create a GHL pipeline

Before enabling pipeline automation, set up a pipeline in GoHighLevel:

Go to Opportunities > Pipelines tab and click Create Pipeline.
Give your pipeline a name and add stage names (for example: New Lead, Appointment Scheduled, Not Interested).
Click Create.

Configure pipeline automation

Pipeline automation allows the AI Employee to update opportunity stages in GoHighLevel after a conversation ends.

Enable pipeline updates

Set ghl_update_pipeline to True to allow the AI Employee to move opportunities through pipeline stages. When set to False, all other pipeline settings are ignored.

Define stage selection rules

The ghl_pipeline_criteria setting maps conversation outcomes to pipeline stages. Write rules that tell the AI Employee which stage to assign based on the call result. Stage names must match your GoHighLevel pipeline exactly.

Example:

  "Appointment scheduled": "If the appointment was successfully scheduled."
  "New lead": "If the caller requested a callback."
  "Not interested": "If the caller declined to book."

❗❗ IMPORTANT

Always click Publish All after modifying any integration settings. Without publishing, the AI Employee continues using the previous configuration.

Common misconfigurations

Avoid these frequent setup mistakes:

Mixing Name and Duration logic:ghl_selection_type only accepts one mode at a time. You cannot combine them.
Missing AI Selection Instructions: When using Name or Duration mode, ghl_selection_criteria is required. Without instructions, the AI Employee cannot select the correct calendar.
Non-exact calendar names: Calendar names in ghl_selection_criteria must match GoHighLevel exactly. Copy names directly from GoHighLevel.
Forgetting to Publish All: Settings changes do not take effect until you publish. Always click Publish All after making changes.
Enabling Pre-load Availability with dynamic selection:ghl_check_availability_on_conversation_start works only with Single mode. Enabling it with Name or Duration causes incorrect slot suggestions.

Testing the integration

Once you have completed the setup above, place a test call to verify that the AI Employee can access calendar availability and create bookings in GoHighLevel. Check the contact record in GoHighLevel to confirm that the appointment was created and that any conversation history is saved if enabled. The contact record might take a few moments to update in GoHighLevel after the call ends. You can check the Sessions page in the Builder to confirm that the call data was received by Newo.ai.

Example scenario: Bright Smile Dental Clinic

Bright Smile Dental Clinic is a local dental office in Austin, Texas. They offer one appointment type (general checkup) and want the AI Employee to handle booking calls.

Configuration:

Apply the following settings in the Builder under Attributes > GoHighLevel Settings:

Setting	Value	Reason
`ghl_selection_type`	`Single`	Only one appointment type.
`ghl_calendar`	General Checkup	The only calendar in the account.
`ghl_selection_criteria`	(left blank)	Not required for Single mode.
`ghl_enable_client_history`	`True`	To review call transcripts during the first month.
`ghl_use_timezone_from_conversation`	`False`	Local business; all appointments are in Central Time.
`ghl_check_availability_on_conversation_start`	`True`	The AI Employee proactively offers available slots.
`ghl_sync_conversation`	`False`	No call-status workflows configured.
`ghl_update_pipeline`	`False`	No pipeline automation needed.

In GoHighLevel, create a calendar named "General Checkup."
Complete authorization: use Method A (OAuth) if installed from the Marketplace, or Method B (Private Integration Token) for an existing agent.
Configure the settings shown in the table above.
Save all configured settings.
Click Publish All.
Place a test call. The AI Employee answers, offers available times for the General Checkup calendar, confirms a slot, and creates the booking in GoHighLevel.

Example scenario: Acme Software

Acme Software is a B2B software company that offers product demos and consultations. They want the AI Employee to book the correct meeting type based on what the caller requests.

Configuration:

Apply the following settings in the Builder under Attributes > GoHighLevel Settings:

Setting	Value	Reason
`ghl_selection_type`	`Name`	Multiple meeting types require dynamic calendar selection.
`ghl_calendar`	(ignored)	Not used in Name mode.
`ghl_selection_criteria`	Identify the meeting type the caller is requesting. Available calendars: Demo, Consultation. Return only the exact calendar name.	Instructions for calendar matching.
`ghl_enable_client_history`	`True`	To review call transcripts.
`ghl_use_timezone_from_conversation`	`True`	Serves clients in multiple time zones.
`ghl_check_availability_on_conversation_start`	`False`	Cannot pre-load until meeting type is identified.
`ghl_sync_conversation`	`False`	No call-status workflows configured.
`ghl_update_pipeline`	`False`	No pipeline automation needed.

In GoHighLevel, create separate calendars: "Demo" and "Consultation."
Complete authorization using Method A or Method B.
Configure the settings shown in the table above.
Save all configured settings.
Click Publish All.
Place a test call. When a caller says "I'd like to schedule a demo," the AI Employee identifies the meeting type, selects the "Demo" calendar, checks availability, and creates the booking.

Next steps

After completing the integration setup and placing a successful test call, continue with the following:

Build workflow automations. Use the native GoHighLevel Workflow Actions to trigger outbound calls and SMS messages automatically when leads enter your pipeline. See GoHighLevel workflow automation.
Deploy a ready-made scenario. Choose from 10 pre-built scenarios — such as speed-to-lead closer, missed-call recovery, and re-engagement campaigns — with complete settings and agent instructions you can copy directly into the Builder. See GoHighLevel use cases and scenarios.
Look up a specific setting. If you need to understand what an individual attribute controls, how it interacts with other settings, or what its default value is, consult the GoHighLevel settings reference.
Troubleshoot an issue. If bookings are not appearing, calendars are not loading, or the AI Employee is selecting the wrong time slots, check the GoHighLevel FAQ for solutions to common problems.

HubSpot integration

GoHighLevel FAQ

GoHighLevel settings reference

GoHighLevel use cases and scenarios

GoHighLevel workflow automation