Skip to main content

GoHighLevel (GHL)

GoHighLevel is a CRM, calendar, SMS pipe, pipeline manager, and marketing automation hub rolled into one — and a huge slice of agencies that resell AI to local businesses already live inside it. This integration plugs your Insighto assistant straight into a single GHL sub-account (Location): upsert contacts by email or phone, find calendar slots, book appointments, hand off to a human agent mid-conversation, and sync the full Insighto transcript back into GHL's Conversations view so it sits next to every other interaction with that contact.

What you can do with this tool​

  • Upsert contacts by email or phone so the same person never becomes two records.
  • Look up contacts and pull their phone number, custom-field values, and tags.
  • Find calendar slots and book appointments on a configured GHL calendar.
  • Trigger a live-agent handoff by tagging the contact (so a GHL automation routes them).
  • Sync the conversation transcript into the GHL contact's message history.

Business use cases​

Agency selling AI receptionists to local businesses​

The classic GHL agency play. Each client business — dental practice, HVAC company, med spa — has its own GHL sub-account. The agency connects GHL once per client, names each connection after the business ("GHL - Smith Plumbing"), and attaches each one to its own Insighto assistant. When Smith Plumbing's voice agent answers a call, the lead lands in Smith Plumbing's GHL with their existing pipelines, tags, and automations. The agency manages everything from one Insighto dashboard.

Appointment booking inside an existing GHL calendar​

A med spa already uses GHL calendars for every staff member's bookings. They don't want to migrate to Google Calendar — their automations, reminders, and SMS confirmations are all built around GHL. The Insighto voice agent has the GHL tool attached and configured to one stylist's calendar. Callers ask for a Tuesday slot, the agent calls find_available_slots against the GHL calendar, reads three options, and books with book_appointment. The booking lands in GHL with the contact already linked.

Mid-call handoff to a human​

A roofer's voice agent handles intake but escalates anything pricing-related. Mid-call the caller asks "how much for a full re-shingle?" The assistant says "Let me pull in one of our estimators." It calls transfer_live_agent, which tags the contact ai off in GHL. The agency's GHL automation picks up the tag and routes the conversation to the on-call estimator's phone or chat.

Transcript sync for follow-up campaigns​

A real-estate brokerage uses GHL email and SMS sequences for nurture. After every Insighto call, push_conversation syncs the full transcript into the contact's Conversations view in GHL — alongside their emails, texts, and form submissions. The next time an agent opens the contact, they see exactly what was said on the call, in context.

Connecting GoHighLevel​

Step-by-step​

  1. Go to Tools & Integrations → GoHighLevel → Connect.
  2. You'll land on the GHL Marketplace's "choose location" screen. Pick the sub-account you want this connection to act on.
  3. Approve the scopes below.
  4. Back in Insighto, pick which calendar within the connected Location this instance should book against (Insighto fetches your calendars automatically for the dropdown).
  5. Save.

Scopes requested​

Paste these into your GHL Marketplace app config if your IT team asks what Insighto is requesting:

contacts.readonly
contacts.write
conversations.readonly
conversations.write
conversations/message.readonly
conversations/message.write
calendars.readonly
calendars.write
calendars/events.readonly
calendars/events.write
locations.readonly
locations/customFields.readonly
oauth.readonly
oauth.write

Prerequisites​

  • A GoHighLevel (or LeadConnector) account.
  • At least one configured calendar inside the sub-account you want to book against.
  • A custom-field configuration if you want the assistant to read or write custom fields on contacts.

Functions the assistant can call​

create_contact​

Upserts a contact. Matches existing records by email or phone; creates a new record if no match. Source is automatically set to Insighto.

  • Arguments

    • email (string, optional)
    • phone (string, optional)
    • firstname (string, optional)
    • lastname (string, optional)

    One of email or phone is required for matching.

  • Returns — "Contact added successfully." on success.

get_contact​

Fetches a contact by GHL contact ID.

  • Arguments
    • contactId (string, required)
  • Returns — the GHL contact JSON, or false if not found.

get_contact_number​

Convenience function — returns just the phone number of a contact by ID.

  • Arguments
    • contactId (string, required)
  • Returns — phone string, or false.

search_contact​

Searches GHL contacts by email or phone, with optional fall-through to create.

  • Arguments
    • email (string, optional)
    • phone (string, optional)
    • to_create (boolean, optional) — if true and no match found, creates the contact.
  • Returns — the matched contact record with custom fields resolved to their human-readable names.

update_contact​

Updates contact fields. Custom-field values are mapped automatically by their configured IDs. Phone numbers are normalized to E.164 using the Location's country setting. Fields the model "hallucinates" (i.e. fields not on the GHL contact schema) are filtered out.

  • Arguments
    • tool_contact (object, required) — the contact record from a previous lookup.
    • mapping (object, required) — fields to patch, including custom-field names.
  • Returns — "Contact updated successfully." on success.

find_available_slots​

Lists available slots on the configured GHL calendar across a date range.

  • Arguments
    • appointment_start_date (string, required) — YYYY-MM-DD.
    • appointment_end_date (string, required) — YYYY-MM-DD.
  • Returns — slot strings in the calendar's timezone.

get_earliest_appointments​

Five-day window starting from today (or from a given date).

  • Arguments
    • appointment_date (string, optional) — YYYY-MM-DD.
  • Returns — the next several open slot strings.

book_appointment​

Books a confirmed appointment on the configured calendar. Looks up the contact by email or phone first (creating if needed), then writes the appointment.

  • Arguments
    • appointment_date (string, required) — YYYY-MM-DD.
    • appointment_time (string, required) — HH:MM.
    • email (string, optional)
    • phone (string, optional)
  • Returns — { "response": "Appointment booked successfully." } on success.

transfer_live_agent​

Tags the contact with ai off. Your GHL workflow should be set up to detect that tag and route the conversation to a human (your estimator, your sales rep, etc.).

  • Arguments
    • email (string, optional) or phone (string, optional) — to find the contact.
  • Returns — confirmation string on success.

push_conversation​

Pushes Insighto's full conversation transcript into the GHL contact's Conversations view, message by message. This is typically called automatically by Insighto's conversation-sync flow rather than by the LLM mid-call.

Example invocation​

The assistant books an appointment mid-call:

{
  "function": "book_appointment",
  "arguments": {
    "appointment_date": "2026-05-20",
    "appointment_time": "14:00",
    "email": "alice@example.com",
    "phone": "+15551234567"
  }
}

Result returned to the assistant:

{ "response": "Appointment booked successfully." }

The assistant then confirms with the caller: "You're booked for Tuesday May 20 at 2pm. You'll get a confirmation text shortly."

System prompt guidance​

Spell out the path:

When a caller asks to book, call find_available_slots for the requested window. Offer at most three options. When they pick one, collect their name, email, and phone, then call book_appointment. After hanging up, the call transcript is synced into their GHL Conversations view automatically.

If the caller asks for a human, say "Let me get one of our team to call you" and call transfer_live_agent. Don't try to handle pricing questions yourself.

Multiple sub-accounts​

Agencies typically connect GHL many times — one connection per client sub-account. Name each connection after the business. The Location ID is captured at connect time from the GHL OAuth response, so each connection is locked to its specific sub-account. The model treats each connection's functions as distinct, so the right Location is always written to.

Custom fields​

If your GHL contacts have custom fields, update_contact will write to them automatically when you include them in the mapping. The field IDs are discovered from your Location during setup; you reference fields by their human-readable names in the prompt.

Calendar timezone caveat​

book_appointment doesn't take a timezone argument — it derives the calendar's timezone from a free-slots probe. If the configured calendar has no availability anywhere in the next several days, timezone resolution can fall back. Workaround: make sure the calendar has some open availability, or configure the timezone directly on the connection.

Failure modes​

  • Refresh token revoked from GHL's side — every call starts failing. Reconnect.
  • Wrong sub-account picked at connect — all writes go to the wrong Location. Disconnect, reconnect, pick the right one at the chooselocation screen.
  • Booking conflict — book_appointment returns the GHL error message directly; the model surfaces it and re-offers.
  • Transcript not showing in GHL — the conversation-sync flow must be enabled for the assistant. Check the assistant's settings.

Where to next​