# 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
- Normalize the email address inside the Beam workspace.- Match the workspace's existing CRM contact id when present.- Otherwise search the connected location by normalized email.- Create an email-only contact only when no unambiguous match exists.- Preserve the RFC email thread separately even when SMS and email belong to the same unified contact timeline.

## Recommended workflow
- Connect the client location from Beam Settings.- Verify the returned location matches the intended sub-account.- Enable email activity sync for only that test workspace.- Send one CRM-originated email through Beam with a stable request key.- Reply to it and confirm Beam and HighLevel each show one event on the same contact.- Test a duplicate webhook and a human takeover before enabling the next client.
CRM is the synced record, not the transportAll sends still pass through Beam's tenant-owned domain authorization, entitlement cap, suppression checks, outbox, and provider event ledger.