Architecture overview

A one-page mental model of how DialStack fits together. Read this once and the rest of the docs will make more sense.

Tenancy model

DialStack is multi-tenant from the ground up. Every resource lives inside this hierarchy:

• Platform — your SaaS product.
• Account — one of your customers (a clinic, a dealership, a contractor).
• User — a person at that customer with phone service.
• Softphone / physical device — what rings. A user can have any number of softphone sessions (browser + mobile) plus at most one physical device (a desk phone or a DECT handset). All of them ring in parallel; the first to answer takes the call.

Your API key is scoped to your Platform. Requests that act on one customer name it in a DialStack-Account header, or carry the account in a session or user token; see Authentication at a glance below.

The account resource graph

Inside an account, resources form a small, opinionated graph. Inbound calls arrive on a phone number or an extension, both of which route to routing targets (e.g., a user, a ring group, a dial plan, or a voice app).

• Phone numbers are the PSTN entry point. Each has a routing_target — the ID of the user, ring group, dial plan, or voice app that inbound calls to that number hit.
• Extensions are short internal dial codes (e.g., dial 200 to reach reception). They route to the same routing targets as phone numbers; they're a parallel surface, not a hop on the way.
• Dial plans are the branching logic — e.g., schedule-based routing, ring-all, external transfer, dial, or voice-app handoff.
• Ring groups parallel-dial users.
• Voice apps are programmable call handlers (REST webhook + optional audio WebSocket); AI Agents are a DialStack-managed Voice App with a pre-built receptionist persona.
• Users can register any number of softphones (browser, mobile) plus at most one physical device (desk phone or DECT handset). All of them ring in parallel.

Call flow

You interact with DialStack through four surfaces: the REST API, Webhooks, SSE (Server-Sent Events), and WebSockets. Everything else is managed for you.

Key properties:

• Webhooks are fire-and-forget. Respond with an HTTP 200 OK quickly (before executing long-running logic); you cannot return data to influence the call. React in your own systems.
• SSE (Server-Sent Events) is account-scoped and safe to consume in browsers with a session token — ideal for Screen Pop.
• Media is relayed by DialStack. Your app never touches audio unless you explicitly attach a WebSocket (e.g., for BYO VoiceAI or Listeners).

The four surfaces

Surface	Direction	Use for
REST API	You → DialStack	Provisioning, config, triggering calls, reading history. Auth: Bearer token.
Webhooks	DialStack → your backend	Durable event delivery with retries and signed payloads. Platform-scoped.
SSE (/v1/events)	DialStack → your frontend	Real-time browser notifications. Account-scoped via session token.
WebSockets	Bidirectional	attach for bidirectional audio (Voice App Control mode); Listeners API for one-way audio.

Full docs: REST, Webhooks, SSE, WebSocket API.

Authentication at a glance

Your backend authenticates with your secret API key, which covers your whole platform; account-scoped operations also take a DialStack-Account header, while platform-wide ones don't (Making requests has the rule). Embedded components in the browser use short-lived session tokens, and softphones use user tokens, both minted by your backend. Authentication covers each credential, how long it lasts, and how to replace or revoke it.

What DialStack hosts vs. what you host

What DialStack hosts and manages

• PSTN / SIP edges, carrier interconnects
• Call routing engine, dial plan execution
• WebRTC media relay, TURN
• Voicemail, recording, transcription
• AI Agents (native receptionist)
• White Label admin portal
• Regulatory and tax/fee compliance

What you build and host

• Your signup flow, account sync, user lifecycle
• Webhook handler for activity logging / Screen Pop
• Your frontend (embedded components) or nothing (white-label portal)
• (BYO VoiceAI only) an audio-bridge WebSocket server
• (AI Scheduling) availability + booking HTTP endpoints

Nothing about calls, carrier relationships, or media transport is your responsibility. You own the business logic and the data you care about.

Identifiers

IDs are opaque; see Making requests. Webhook events can be delivered more than once, so dedupe by event.id before writing.

What's next

• Quickstart — provision your first account, user, and phone number.
• Webhook events — the firehose of everything that happens on a call.
• Dial plans — route calls where you want them.
• Choosing an integration — pick between the white-label portal, embedded SDK components, and the direct API.