Your phone carrier goes down. Customers are calling and getting dead air. For a bank, a hospital, or any business where the phone is the product, that's not an inconvenience — it's the worst kind of outage.
Most companies handle this with a pager and a runbook. A human gets paged, logs into a dashboard, reroutes traffic, and hopes nobody called during the gap. Fifteen to forty-five minutes of lost calls, every time.
This is the problem behind the Auto-Failover Voice Routing example:
https://github.com/team-telnyx/telnyx-code-examples/tree/main/auto-failover-voice-routing
The example is an Edge function that wires two independent Telnyx connections behind a circuit breaker. When the primary carrier fails, calls automatically switch to the backup connection in seconds. No human in the loop.
What Is a Telecom Circuit Breaker?
The circuit breaker pattern is standard in distributed systems. If a service starts failing, you stop routing traffic to it and fall back to a healthy replica. After a cooldown, you probe the failed service and restore traffic if it's healthy again.
A telecom circuit breaker does the same thing for voice calls. The primary connection carries all traffic. If calls start failing — busy, no-answer, timeout — the breaker counts the failures and trips at a threshold. Every new call routes through the backup connection instead. After a cooldown, the breaker goes half-open: the next call is a live probe of the primary. If the probe succeeds, traffic flows back automatically.
The difference from the software version is the signal source. In a microservices setup, you detect failures through HTTP status codes or health checks. In telecom, the carrier tells you. Every call outcome — connected, failed, busy, no-answer — arrives as a signed webhook. Those webhooks are the failure detection layer. No polling, no health checks, no guesswork.
The Demo: A Fraud Alert Line That Never Goes Down
The sample uses a fraud alert line for a fictional bank to show the pattern end-to-end. The system calls the customer, speaks a fraud alert using Telnyx Ultra text-to-speech, and collects a confirmation keypress. Press 1 to confirm the transaction. Press 2 to block the card and freeze the account. Either way, the customer gets an SMS receipt with a case reference number.
The point of this scenario is not the fraud alert itself. It's that the customer experience has to keep working no matter what happens to the infrastructure. A fraud alert that doesn't fire because the carrier went down is worse than no fraud alert at all — it tells the customer the bank isn't watching.
The Architecture
The example composes four Telnyx primitives:
- Call Control — two independent Call Control applications, one for the primary connection and one for backup. The router dials through whichever connection the breaker selects.
- Webhooks — Telnyx sends signed webhooks for every call outcome. The handler verifies each one against the Ed25519 public key before processing. Failure causes (busy, no-answer, timeout) increment the failure counter. Answered calls never count.
- KV — the circuit breaker state lives in KV: failure count, last failure timestamp, tripped flag. All mutations go through a single durable actor, which prevents race conditions when webhooks arrive out of order.
- SMS — two flows. When the breaker trips, the on-call engineer gets paged with the failure count and which backup connection took over. The customer gets a receipt after every keypress interaction.
The architecture runs on Telnyx Edge Compute using the Agent SDK. A single FailoverAgent extends the Agent base class and owns all mutable state: the breaker counters, the call routing maps, and the per-call conversation stages.
The Customer Experience Survives the Outage
The interesting part of this demo is not the failover itself — that's a well-understood pattern. The interesting part is that the customer experience is identical on both connections.
During normal operation, the primary carries all traffic. The customer answers the fraud alert, hears a professional announcement in Telnyx Ultra's voice, presses a key, gets a confirmation. During an outage, the backup carries the traffic. The customer hears the same alert, with one additional sentence: "Heads up: we're running on our backup systems right now after a brief technical issue." Then the exact same flow — same voice, same keypress, same SMS receipt.
That one sentence is the only difference the customer notices. That's the goal. The outage happened, the infrastructure failed, and the customer's experience was a single sentence instead of dead air.
The Recovery
Failover isn't the end of the story. After the cooldown period, the breaker goes half-open. The next call routes through the primary as a probe. If the probe succeeds — the call connects without a failure code — the breaker closes and traffic returns to normal. If the probe fails, the cooldown timer resets and backup continues handling traffic.
This means the system recovers without human intervention. No one has to remember to switch back. No one has to monitor the primary and decide when it's safe. The breaker does it.
Getting Started
The sample is in the Telnyx code examples repo. Clone it, create two Call Control applications, set your phone numbers in the config, and deploy to Edge.
The README includes the full setup guide, the API reference, and the deployment instructions. The smoke test runs twenty-five assertions that cover the entire flow — breaker trip, failover, webhook idempotency, the call flow, and the event feed.
Why This Pattern Matters
Voice infrastructure is different from web infrastructure. When your API goes down, requests fail and clients retry. When your phone line goes down, callers get dead air and hang up. There's no retry. There's no queue. The call is gone.
That's why the circuit breaker matters more for voice than for HTTP. The cost of not having it is not a failed request — it's a customer who called your support line, heard nothing, and called your competitor.
The sample is open source. The circuit breaker pattern is not specific to fraud alerts — it works for any voice application where availability matters. Support lines, emergency notifications, appointment reminders, order status updates. If the phone call matters, the failover matters.