Developer guide
Route customer messages to the right SaaS tenant
Keep a trusted tenant-to-line mapping, scope access to the correct workspace, and resolve inbound replies before running application logic. Confirm dedicated-line eligibility before promising a number for every customer.
Route by the receiving line, not model guesses
Store your tenant identifier, workspace identifier, line E.164 and conversation ID. Resolve data.message.line_e164 against that mapping. A missing or unknown line must not fall through to a default tenant.
The example rejects duplicate line mappings and rejects an existing conversation whose tenant or line changes. Use workspace or line-scoped keys and application authorization checks; a database tenant_id alone does not isolate provider permissions.
COMMS_TENANT_LINES={"tenant_a":"+12025550101","tenant_b":"+12025550102"}
# The receiver resolves message.line_e164 against this trusted map.Handle line provisioning as a gated operation
API line claiming requires workspace approval and available inventory. A denied claim returns line_claim_not_allowed; unavailable inventory returns no_available_line.
Use GET /lines to inspect inventory and capabilities before POST /lines/claim. A successful claim returns e164, inbound_mode and status. The agent must not promise a line until that operation succeeds.
{ "e164": "+12025550101", "inbound_mode": "api", "status": "active" }| State | Application behavior |
|---|---|
| 403 line_claim_not_allowed | Request workspace access; show the user that provisioning requires approval. |
| 409 no_available_line | Keep onboarding pending; do not invent a number or silently assign another tenant’s line. |
| Success | Persist the mapping, configure the webhook, verify inbound routing and channel capabilities. |
Define number control and offboarding
Porting requires approval and a supported number. Confirm port-in, port-out, geographic availability, fees, and timing before planning a migration. You can cancel replacement setup before submitting the transfer; a submitted transfer cannot be canceled from the setup panel.
Confirm port-in/out rights, fees, supported countries and any retention terms in the agreement. Record which tenant may send and read on each line. Revoke credentials and remove automated send access during offboarding; do not reassign a number while old tenant routing is still active.
Test two tenants and failure cases
Send signed local events for both configured lines. Replay an event, send an unknown line, and attempt to attach a conversation to another tenant. The example tests those boundaries with persistent storage. Use a shared transactional database in production when you run several receivers.
Price shared testing and dedicated production separately. Confirm throughput and supported geography for the workload rather than treating a headline message capacity as a per-tenant SLA.