A human-sounding voice is not the same thing as an authenticated caller.
That distinction matters when a support request can move money, reset a password, change an address, or enroll a new device. A voice interface can make those workflows convenient, but it should not be the only control deciding whether a sensitive action completes.
This example shows how to build a voice fraud step-up workflow with Telnyx. It uses Call Control to place a call, Deepfake Detection to evaluate the remote-party audio, webhooks to return the detection result, Telnyx Edge Compute to hold per-account state, and optional Telnyx Verify flashcall for a risky result.
The canonical code example is:
https://github.com/team-telnyx/telnyx-code-examples/tree/main/voice-fraud-step-up-agent
The live walkthrough is:
https://youtu.be/DQ3RLClemqM
What This Voice Fraud Example Builds
The example models a support request for a high-risk action such as a $2,500 wire transfer.
A request opens a per-account fraud gate. The gate begins in a blocked-pending state. The application places an outbound Call Control call with Deepfake Detection enabled. The caller hears a short verification prompt while the detection service evaluates the remote-party audio.
When the result arrives, the Edge actor combines it with recent account history:
- A clean real result returns proceed
- A fake result triggers Verify flashcall step-up when configured
- A recent risky ledger event can also force step-up
- A timeout or provider error routes to manual review
The final call message is delivered with deterministic Call Control speech. The live path does not start an autonomous assistant after detection, so the spoken verdict is selected directly from the stored policy outcome.
Why Voice Authenticity Is Not Identity
Deepfake Detection answers a narrow question: does the call audio appear human or synthetic?
It does not answer:
- Does this person own the account?
- Is this person authorized to send the transfer?
- Has the account passed the company’s identity policy?
- Should the business complete the transaction?
Those questions require independent controls.
The right production sequence is closer to:
~~~ voice authenticity signal -> account and transaction risk policy -> independent identity factor -> sensitive action ~~~
The voice result can improve the risk decision without being mistaken for proof of account ownership.
This separation is useful for both security and operations. Security teams can inspect the exact signal that caused a step-up, while support teams can continue using a normal phone interaction. The caller does not need to understand the model or the ledger. They only hear the next required step. The application, meanwhile, retains enough context to explain why the request proceeded, why it required a challenge, or why a specialist needs to review it.
How The Call Starts
The actor receives a sensitive action and records it in its state. The initial ledger row is:
~~~ blocked_pending — request opened ~~~
That state is intentional. The request does not begin in an approved state while the phone call is still waiting for a result.
The outbound Call Control request includes Deepfake Detection:
~~~ts const payload = { connection_id: env.OUTBOUND_CONNECTION_ID, from: env.OUTBOUND_CALLER_ID, to: action.caller, deepfake_detection: { enabled: true, timeout: 30, }, client_state: encodeClientState({ accountId: action.accountId, }), }; ~~~
client_state carries the account identifier through the call flow. When the webhook arrives, the Edge function can route the event back to the correct account actor.
Playing The Verification Prompt
When the call is answered, the webhook handler sends a Call Control speech command:
~~~ts await fetch('/calls/' + callControlId + '/actions/speak', { method: 'POST', body: JSON.stringify({ payload: VERIFICATION_PROMPT, voice: VERIFICATION_VOICE, language: 'en-US', }), }); ~~~
The prompt makes the security boundary clear:
~~~ This call includes a voice-authenticity screen, not identity verification. Please state your name and confirm whether you requested the two thousand five hundred dollar wire transfer on this account. ~~~
The call continues while Telnyx evaluates the remote-party audio. The application does not treat the caller’s spoken confirmation as proof by itself.
Handling Deepfake Detection Webhooks
The Edge webhook handler routes the event by account ID and handles three result values:
~~~ts if (eventType === 'call.deepfake_detection.result') { const result = payload.result;
if (result !== 'real' && result !== 'fake' && result !== 'silence_timeout') { return new Response('unexpected detection result', { status: 400 }); }
return actor.recordDeepfakeResult(callLegId, result, callControlId); } ~~~
The result is stored in the ledger along with the call identifier, action, timestamp, source, and policy outcome.
Provider errors follow a fail-closed path:
~~~ call.deepfake_detection.error -> manual_review -> deterministic review message ~~~
This prevents a missing detection result from being interpreted as approval.
Applying The Account Policy
The decision function evaluates the latest result and recent ledger history:
~~~ts if (result === 'real' && !hasRecentFlag) { return { outcome: 'proceed', reason: 'human-sounding voice result and clean recent ledger', }; }
if (result === 'fake' || hasRecentFlag) { return { outcome: 'step_up_flashcall', reason: 'synthetic voice detected or recent risky ledger event', }; }
return { outcome: 'manual_review', reason: 'detection returned silence_timeout', }; ~~~
The policy is intentionally conservative. A clean real result allows the workflow to continue, but it does not complete the sensitive action. The next stage must still perform independent verification.
A fake result or recent risky event creates a step-up path. When a Verify profile is configured, the sample sends a flashcall request to the caller’s number. If flashcall is unavailable or unsuitable for the production workflow, the same policy boundary can route to another factor or a human reviewer.
Why Store The Ledger In Edge State?
A voice fraud decision needs context.
If the application only examines the newest call, a later human-sounding call could erase the meaning of an earlier risky event. The actor ledger keeps the recent sequence together:
~~~ blocked_pending — request opened step_up_flashcall — recent risky ledger event found proceed — not automatically available while the recent flag is active ~~~
The actor stores this state in embedded SQL. That gives the example an auditable record of what happened and why. It also means that the policy can rehydrate the account’s recent history after a restart instead of starting from an empty in-memory array.
This is the same reason to keep the pending action, call identifier, and escalation rows with the account’s actor. The fraud gate is a stateful workflow, not just a single webhook handler.
Why Use Deterministic Call Control Speech?
An earlier version of the sample started an AI Assistant after the detection result to deliver the verdict. That introduced an unnecessary second conversational layer: the assistant could speak in a way that did not match the ledger.
The live path now uses Call Control speech for the prompt and verdict:
~~~ proceed -> the voice passed the synthetic-voice screen
step_up_flashcall -> additional verification is required
manual_review -> a specialist will review the request ~~~
The caller hears the exact message selected by the policy. The code, not the assistant, owns the security decision.
Run The Example
Clone the code example and run the local checks:
~~~bash git clone https://github.com/team-telnyx/telnyx-code-examples.git cd telnyx-code-examples/voice-fraud-step-up-agent npm install cp .env.example .env npm run typecheck npm run smoke ~~~
The smoke test does not place a call or send a verification message.
For a live call, configure the Edge secrets and use a phone number you control:
~~~bash npm run demo:live ~~~
The local monitor prints the dial payload with the target number masked. The API key remains in the deployed Edge function and is not printed by the local monitor.
Production Considerations
The sample is a focused fraud-gate pattern, not a complete identity system. A production implementation should:
- Require an independent factor before completing a sensitive action
- Add transaction amount, velocity, device, and account risk signals
- Limit repeated calls and step-up attempts
- Keep full phone numbers and credentials out of logs
- Define retention rules for detection results and audit rows
- Route inconclusive results to trained reviewers
- Add idempotency and duplicate-event handling to every external action
- Test the behavior for voicemail, silence, dropped calls, and provider errors
The most important rule is to keep voice authenticity separate from account authorization.