HighLevel and CRM integration

Map each Beam workspace to one HighLevel sub-account without reusing the SMS provider identity.

Account boundary

One Beam client workspace maps to one verified HighLevel location. Agency authorization may select client locations, but Beam exchanges and stores a location-scoped installation for each workspace. A token for one location cannot read, write, or sync another client.

Separate email provider

Email uses its own conversation-provider identity and dedupe keys. It never reuses the existing SMS/blue provider id or guesses a provider from the contact. The email adapter remains behind the platform feature flag until a controlled sub-account proves both directions exactly once.

Implementation references: HighLevel conversation providers, signed provider outbound events, and location-scoped OAuth.

Contact and thread matching

1. Normalize the email address inside the Beam workspace.
2. Match the workspace's existing CRM contact id when present.
3. Otherwise search the connected location by normalized email.
4. Create an email-only contact only when no unambiguous match exists.
5. Preserve the RFC email thread separately even when SMS and email belong to the same unified contact timeline.

Recommended workflow

1. Connect the client location from Beam Settings.
2. Verify the returned location matches the intended sub-account.
3. Enable email activity sync for only that test workspace.
4. Send one CRM-originated email through Beam with a stable request key.
5. Reply to it and confirm Beam and HighLevel each show one event on the same contact.
6. Test a duplicate webhook and a human takeover before enabling the next client.