Skip to main content

Locations

A location represents a single CRM tenant — typically one business account. The locationId is the routing key that ties together:

  • A connected Mac (one per location at a time).
  • Outbound HTTP traffic from the CRM (POST /crm/webhook) routed to that Mac.
  • Inbound HTTP delivery from BlueSender to the CRM (POST /conversations/messages/inbound) and per-message status updates (PUT /conversations/messages/{messageId}/status).

What locationId is​

locationId is an opaque string supplied by the CRM. The format is CRM-specific (often a short alphanumeric id like abc123XYZ); the operator decides the format and BlueSender treats the value as opaque.

How locationId is assigned​

Two paths:

CRM provisioning​

Most integrations provision the locationId at the CRM side. The operator configures the BlueSender Mac app with a fixed locationId that the Mac uses for the lifetime of the install. From the CRM's perspective, the locationId it includes on POST /crm/webhook is the same one the Mac is bound to.

OAuth flow (CRM marketplace integrations)​

For installations driven by a CRM marketplace OAuth flow, the token exchange returns a locationId along with the access token. The backend stores the encrypted tokens keyed by locationId. Once exchanged, the integration is bound to that location for as long as the OAuth grant is valid.

One client per location​

BlueSender enforces a single connected client per locationId. If a second client registers the same locationId, the existing client is displaced.

This is independent of licensing: a license controls how many Macs can run BlueSender; locationId controls which CRM tenant each connected Mac serves. A 3-seat license can run 3 Macs in parallel — each on a different locationId — but you cannot have 2 Macs both on the same locationId.

Routing failure​

If no Mac is currently bound to the locationId carried on a POST /crm/webhook request, the request fails immediately with HTTP 404 ({ "error": "Location not connected", ... }). There is no fallback routing or backend queue — see No backend queue for the rationale.