@xapp/stentor-service-gohighlevel
v1.1.2
Published
GoHighLevel (HighLevel / LeadConnector) CRM client: upserts leads as contacts with tags and notes, books appointments and reads calendar availability
Readme
@xapp/stentor-service-gohighlevel
Client for GoHighLevel (HighLevel, also white-labelled as LeadConnector), API v2. It pushes each captured lead into one sub-account (a "location") as a contact, adds tags and a note with the conversation, and books a requested time on a calendar. It also reads calendar availability and lists calendars so Studio can offer them as a dropdown. Implements stentor-models' CrmService.
Usage
import { GoHighLevelService } from "@xapp/stentor-service-gohighlevel";
const ghl = new GoHighLevelService({
authenticate: () => Promise.resolve("<Private Integration Token or OAuth location token>"),
locationId: "<sub-account id>",
calendarId: "<optional calendar id>",
timezone: "America/Chicago",
tags: ["xapp ai lead"] // the default; [] adds none
});
await ghl.testConnection(); // throws GoHighLevelError kind "auth" on a bad token
const calendars = await ghl.listCalendars();
const result = await ghl.sendLead(externalLead);
// { contactId, created, noteId?, appointmentId?, partial?, errors? }Auth is a callback, so the same service works with a Private Integration Token (Settings → Private Integrations in the sub-account) or an OAuth location access token from a Marketplace app. Required scopes: contacts.write, locations.readonly, plus calendars.readonly and calendars/events.write to read availability and book appointments.
Behaviour worth knowing
- Dedupe is HighLevel's.
POST /contacts/upsertmatches an existing contact by the sub-account's Allow Duplicate Contact setting (email and/or phone, in its configured priority). - Tags are added, never set. Upsert replaces every tag on a matched contact, which would wipe the tags the business's own workflows run on. So the upsert never carries tags; they go through
POST /contacts/{id}/tags, which adds. Businesses typically start their follow-up from a Contact Tag workflow trigger on these tags. - Booking. When the lead has a
DATETIME, acalendarIdis configured and the lead is complete, an appointment is created.DATETIMEis the business's local wall clock (a trailingZis ignored) and is sent with the business's UTC offset. HighLevel takes the end time from the calendar's slot length. - Incomplete leads follow the partial/abandoned lead standard in
packages/services/README.md: skipped without a name plus an email or phone, labelled[Partial …]in the note, and never booked. - No retries. Notes and appointments have no idempotency key. If the contact lands but a later step fails,
sendLeadreturns what it created withpartial: true, andsendstill reportsSuccess. - Availability comes from
GET /calendars/{id}/free-slots, in 30-day requests (HighLevel caps a request at 31 days). A date with no free slot is reported unavailable. With no calendar, or on any error, it fails open (full availability). - Errors are
GoHighLevelErrorwithkinddecided by HTTP status alone:auth(401/403),rate_limit(429),http,network, orconfig(a tenant-supplied id failed validation and no request was made). The token never appears in a message. - Versions. HighLevel requires a
Versionheader per API family:2021-07-28for contacts and locations,2021-04-15for calendars, as pinned by the published OpenAPI specs.
Functional Test
yarn test:f runs against a live sub-account and is skipped unless GHL_TOKEN and GHL_LOCATION_ID are set (GHL_CALENDAR_ID is optional). It only reads; it never creates a contact, because that would fire the sub-account's own workflows.
