Connection settings & stage mapping

Every connection has its own settings, on the Settings tab of the connection. They decide who the imported leads belong to, what happens when a lead already exists, and which Booked55 pipeline stage each GoHighLevel stage lands on.

Settings reference

When a contact already exists

Before it creates anything, Booked55 looks for a matching contact in your workspace, in this order:

1. The GoHighLevel contact id, which Booked55 remembers on the contact after the first import.
2. The email address, compared lower-cased.
3. The phone number, compared by digits in a few common formats.

The phone rule cuts both ways: two GoHighLevel contacts that share a number, such as an office line, are one contact to Booked55. Give them different numbers in GoHighLevel, or set the connection to Always create, if they must stay separate.

What happens next depends on the setting:

• Update and append (default) — Fills in fields that are empty, adds new tags and phone numbers, appends notes, and moves the pipeline stage if a mapping applies. It never overwrites a field that already has a value, and never changes the contact's email or assignee.
• Skip — Records the event and changes nothing. The event is marked skipped with the reason duplicate_contact.
• Always create — Creates a new contact every time, even when one matches. Use it only if every GoHighLevel opportunity should be its own Booked55 contact.

Stage mapping

GoHighLevel tells Booked55 which pipeline and stage the opportunity is in. Stage mapping translates that into a Booked55 pipeline and stage. Each row has four fields:

Names are matched case-insensitively after trimming whitespace, so “Appointment Booked” and “appointment booked” are the same stage. Beyond that, the names must match what GoHighLevel sends exactly.

How a stage is resolved

1. If a mapping row matches the incoming pipeline and stage, the contact goes to that row's Booked55 pipeline and stage.
2. Otherwise, if a default pipeline and stage is set, the contact goes there.
3. Otherwise the contact is imported with no pipeline item. It exists in Contacts but is not on any pipeline.

Contact already on a pipeline

A contact can be on only one pipeline at a time in Booked55. When a matched contact already has a pipeline item, this setting decides what the incoming event does with it:

• Move to the mapped stage (default) — The contact is moved to the stage the mapping resolved to.
• Leave where it is — The contact keeps its current pipeline and stage. The rest of the update still applies.

This only comes into play under Update and append. Skip never touches an existing contact, and Always create makes a new one.

Suggested names

Once the connection has received real events, the mapping editor suggests the GoHighLevel pipeline and stage names it has seen in them, so you can pick a name instead of typing it. The suggestions only reflect what has actually arrived: send a lead through the workflow first, then map it. Test events are not used for suggestions.

Worked example

Your GoHighLevel pipeline is called Sales and the stage that should hand a lead to sales is Appointment Booked. In Booked55 those leads belong on the Sales Process pipeline at the Appointment Set stage. The mapping row is:

When an opportunity in the Sales pipeline reaches Appointment Booked, the workflow fires and the contact appears on Sales Process at Appointment Set, assigned to the connection's assignee. If you later add a second GoHighLevel pipeline with its own Appointment Booked stage, either add a row for it or blank the pipeline name on this row so it matches both.

Private Integration Token

The webhook carries at most one note. If you want a lead's full note history from GoHighLevel to come across too, give the connection a Private Integration Token. With it, Booked55 pulls every note on the contact from GoHighLevel and adds each one as a completed note task. Without it, only the note carried in the webhook itself is imported, and often there is none.

1. 1

   Open Private Integrations in GoHighLevel

   In the GoHighLevel sub-account (location) the workflow belongs to, go to Settings → Private Integrations and click New.

2. 2

   Name it and pick the scope

   Give the integration a name such as "Booked55". Under scopes, select View Contacts (contacts.readonly). Nothing else is needed: Booked55 only reads contacts and their notes.

3. 3

   Copy the token

   GoHighLevel shows the token when the integration is created. Copy it.

4. 4

   Paste it into the connection

   In Booked55, open the connection, go to the Settings tab, and paste the token under Credentials → Private Integration Token. Save.

The token is stored encrypted and is never shown again once saved. Booked55 uses it for one thing only: reading contacts and their notes. To change it, replace it with a new one.

For what happens to each event after these settings are applied, see Event log & troubleshooting.