Skip to main content

​
Messaging data residency

“Where does my message data live?” is a question you can answer programmatically. Orbit exposes a messaging-layer residency read alongside the org-level residency pin, so a regulated buyer integrating the messaging product reads residency where it integrates — next to sender pools and messaging services — instead of digging through a generic settings page. This page explains what the read reports, how it differs from tenant-schema isolation, and how it composes with the voice residency controls.

​
Section 1 — What the messaging residency read reports

The org-level residency pin is stored and managed in the compliance surface: one singleton configuration per organization, written through the compliance endpoints and read everywhere else. The messaging read projects that pin onto the messaging data plane and answers the question a messaging team actually has: where are message bodies, metadata, and logs stored and processed today? Read your messaging residency posture:
The response carries four parts. Field values are literal examples from an org that has enforced an EU pin; every other value the surface can return is named below.
  • The org’s residency pin — pinnedRegion is the enforced region, or null when nothing is enforced; enforced separates a recorded advisory pin from an enforced one. supportedRegions lists the closed catalog (region code, label, jurisdictions, regulatory frameworks, per-region availability) so the messaging surface shows the choices without a second call to the compliance endpoint.
  • The messaging-plane status — plane is the messaging entry of the org-wide data-plane matrix, same class and fields the compliance matrix reports. Message bodies and metadata live in the primary_database storage class, and both axes are reported: at-rest storage (residencyScoped, residentRegion) and processing (processingScoped, processingRegion), each with a plain-language note written for quoting into a register.
  • The composed verdict — storedAndProcessedInRegion is true only when the pin is enforced and targets the region where the message bytes genuinely rest and are processed today. The platform stores and processes message data in one region (the EU; see the per-plane matrix in Data residency overview), so this flag is true for an enforced eu pin and false for every other configured pin — it reports the cross-region gap rather than implying a guarantee.
  • The API-layer residency signal — api_region is a separate object from the storage story above: it compares the compute region this API pod is actually processing in (apiRegion) against the region your enforced pin targets for REST API traffic (targetApiRegion), reports whether the two coincide (inRegion), and gives the region-pinned ingress endpoint (targetApiEndpoint, e.g. https://api.eu.orbit.devotel.io/api/v1) with targetApiEndpointLive stating whether that ingress is serving today. All of its fields beyond apiRegion are null when nothing is enforced — there is no target to compare against.
The pin is single-region and org-wide: one region applies to every messaging data plane at once. There is no per-channel or per-sender residency knob to set, and the read is exactly that — a read. Because it projects the shared org config rather than keeping its own copy, it answers with the same pin the compliance surface manages: Owner or admin permission is required for writes; every change lands in your audit log.

​
Section 2 — Messaging residency vs. tenant-schema isolation

Do not confuse the residency pin with tenant isolation. They answer different questions:
  • Tenant isolation is the hard boundary. Every tenant’s working data lives in its own PostgreSQL schema, resolved server-side from your API key on every request. That boundary keeps one tenant’s data unreachable from another tenant; it applies to all tenants always, pin or no pin.
  • The residency pin is a within-my-tenant choice: of the geographic regions the platform offers, which one should my data be pinned to? It is a tenant-owned control — you set it, you lock it, you document it. It is not a platform hard gate, and it defaults open until you enforce it.
Tenant isolation is a security invariant; residency is a placement preference you opt into. Isolation is the precondition on which a residency pin can even be meaningful — a pin only has content because your schema is already isolated.

​
Section 3 — How it composes with voice data residency

Messaging data and voice data have separate residency controls, and a coherent posture sets both deliberately rather than assuming one covers the other:
  • Voice data (call recordings, voicemail, live media) follows the workspace voice-region pin documented in Voice data residency. It covers exactly those three voice data classes and nothing else.
  • Messaging data (SMS, MMS, chat bodies and metadata) follows the org residency pin described above.
When you answer an audit question or a buyer questionnaire, check the messaging read for messaging data and the voice-region page for voice data. Pointers that conflate the two answer the question with the wrong control. The data residency overview maps which surface answers which channel’s residency question.

​
Section 4 — Common setups

Enforce the EU pin, then lock it. The region catalog reports each boundary as available or preview, and enforcement is only accepted for an available region. The EU is the one region live today — the same region the primary database and all platform compute already run in — so an enforced EU pin also flips storedAndProcessedInRegion on the messaging read to true. For a regulated EU posture:
A locked pin is refused (409 RESIDENCY_LOCKED) on any further region change until you deliberately unlock it — the guard that keeps data already written under the pin from being silently re-homed. Advisory pin while a region is in preview. Every other catalogued region (UK, US, CA, AU, BR, IN) is preview until its region-scoped storage and provisioning go live. Enforcement of a preview region is refused (409 RESIDENCY_REGION_UNAVAILABLE) because the platform will not claim an at-rest guarantee it cannot keep — but an advisory pin (enforced: false) to a preview region is allowed: you register where your data needs to land, so the intent is recorded before the region graduates. One org, one pin. Residency is set per organization, and a pin covers every messaging data plane at once — there is no per-channel pin to keep in sync. A multi-brand operator sets each organization’s pin independently on its own compliance surface; the messaging read then reports that organization’s answer, and the audit log records who set it.

​
Section 5 — Read your posture before you certify it

Residency is one of the tenant-owned controls in your compliance posture: Orbit provides the surface, you own the decision and its documentation. Before you certify a workspace’s residency posture in a register or answer a questionnaire, read the messaging surface and record what it returns:
  1. Read the messaging endpoint and check pinnedRegion, enforced, and storedAndProcessedInRegion. A false storedAndProcessedInRegion means either the pin is advisory-only or it targets a region where message data does not rest and get processed today — resolve which before you certify.
  2. Check the api_region block if you care about where API calls are processed, not only where data rests. inRegion: false or targetApiEndpointLive: false tells you the request path is still cross-region even when the at-rest story is settled.
  3. Check the lock state if you rely on the pin as a frozen answer. An unlocked enforced pin can still be moved by an owner or admin; lock it if the register entry must not drift.
  4. Record the plain-language notes the endpoint returns per plane — they are written for exactly this register entry, so quote them rather than paraphrasing.
The residency surfaces are storage-placement policy. They perform no outbound traffic of their own and gate no sending — configure them deliberately and document the reading you settle on.

​
Cross-references