Customer Authentication¶

Status: Current | Last reviewed: 2026-10-16

The caller must agree to receiving the verification message. Saying “yes” to their name or confirming that their phone receives texts is not permission to send one. The agent can proceed after a reply to its permission question or a direct request such as “please send the verification link by text.”

Customer Authentication lets an agent confirm who a caller is before it discusses anything sensitive. You enable it per agent, choose which verification methods to offer, and decide in the prompt which requests need verification and which don't. The agent can reuse the conversation's completed verification without sending another verification message.

When procedure correction is enabled, a completed verification also gives the agent guidance for the next unfinished step, such as asking for missing account details. That step still needs its own answers and completion checks.

Turn it on¶

Two switches, both required:

1. Tenant — Settings → Tenant Settings → Customer Authentication → Allow agents to verify callers. This page also sets the tenant-wide defaults agents resolve against: the identity source (TrueServe built-in, or your own identity provider) and the SMS integration used to send codes and links.
2. Agent — in the pipeline editor, open the conversational stage's inspector and flip the Customer Authentication switch in the Capabilities section. The configuration form appears under it.

For methods that send a text, the agent form has an SMS integration picker inside both One-time code and Passkey. It lists active integrations in the current tenant that provide SMS, including AWS messaging profiles. Choose a profile to override this agent, or leave it at None to inherit Settings → Customer Authentication. Create or repair the underlying profile under Settings → Integrations; selecting a different tenant changes the profiles available in these pickers.

Choose the methods¶

Required assurance decides how much proof the agent demands:

• Single factor (AAL1) — one check is enough.
• Two factors (AAL2) — recommended for money or health data. A passkey satisfies it alone; a one-time code needs a passing knowledge check alongside it (turn on Counts toward assurance in the knowledge-check settings). Publishing blocks a two-factor requirement the selected methods can never satisfy, and warns when a text-message code is the only route (phone numbers can be hijacked).

For knowledge checks, pick the Tools that confirm the answer from the stage's tools. A qualifying tool signals a pass by including "kba_verified": true in its JSON result (optionally with a "customer_ref" identifying the matched customer). Only a genuine true counts — the platform reads the result itself, so the model cannot decide the caller passed.

Decide when to verify¶

When to verify offers two timings:

• When the prompt asks for it — you write the rules. The agent's tools appear in the prompt editor's autocomplete, so you can reference them the way you reference any tool:

text Before discussing balances, transfers, or personal details, the caller must be verified. Check {{TOOL:get_customer_auth_status}} — if {{customer_auth_status}} is not "verified", run {{TOOL:authenticate_customer}} first. General questions about branch hours or products need no verification.

• Right after the greeting — the agent verifies everyone up front before handling any request.

The {{customer_auth_status}} variable (unauthenticated, pending, verified, locked) is available in the Variables section of the autocomplete for prompt branching. Extra instructions appends your own guidance to the built-in verification instructions.

Ask permission to send is the one line the caller hears before anything is sent. Leave it blank and the agent matches the selected method: it asks about a secure link for passkey, a texted code for SMS, or an emailed code for email. You can also word it yourself. It is asked once per call, and agreeing covers everything else the agent sends afterwards. The send is blocked until the caller's latest words actually grant permission; the agent cannot bypass this by merely claiming consent in its tool call.

What the caller experiences¶

• Permission to message them, asked once: the agent first resolves the highest-priority method you enabled and asks the matching question in that same turn. It waits for the caller's answer, then sends only after they agree; it does not announce a send and pause first. A direct reply that expects the message—“did you send it?”, “where is the link?”, or “go ahead”—counts as agreement when it follows that question, so the agent sends instead of asking again. If they decline, the agent says it can only help with things that don't need verification and carries on. Once they've agreed, or once they've completed a code or passkey the agent sent them, anything else the agent needs to send on that call — including a visual card later in the conversation — goes out without another permission question. On a chat conversation the question is skipped entirely: the chat window is the surface, so there is nothing extra to send. In Preview the caller is asked, exactly as on a real call. The message lands in the test phone's Messages app by default, or on the real ANI when the deployment exposes SMS and the tester enables it.
• One-time code: "I've sent a code to the phone ending 4567 — read it back when you have it." The number defaults to the caller's own line on an inbound call; the agent can also send to the email or phone on file.
• Passkey: "I've texted you a secure link." For two-factor assurance, the agent starts with this link so a returning caller can use their existing passkey without an unnecessary code. They tap it, their phone prompts for Face ID / fingerprint, and the agent confirms out loud the moment it completes — they never leave the call. A first-time caller sees Create your passkey, selects Save a passkey, and completes the device prompt; the page then asks them to verify once with the new passkey. The link itself authorizes that first setup, so a passkey-only agent sends no separate code. Creating the passkey alone never marks the caller verified. With real verification, an emulator test opens the Surface App in a new browser tab so the device can provide biometrics; the test call stays connected. The optional Preview simulation runs entirely inside the test phone.
• Knowledge check: the agent asks the questions your prompt tells it to and your tools do the checking.

Wrong guesses are limited per code, and repeated failures lock the caller's number or email out for a while across calls — the agent tells them how long to wait. Codes expire after the Valid for window (capped at 10 minutes).

When Let first-time callers set up a passkey is on, a caller with no passkey can create one directly from the secure link. A caller who independently chose an allowed one-time-code route can still be offered enrollment after that code is accepted. In either case, the passkey is registered to the customer identity and this website when the caller accepts the browser's fingerprint, face, security-key, or device-PIN prompt, and creating it alone never marks the caller verified.

Use one page for verification and visual content¶

Enable Customer Authentication and Multimodality on the agent to share the customer page automatically:

• If the customer already has the multimodal page open, verification appears there. Once they finish, it disappears and their existing content remains.
• If verification comes first, its page automatically becomes the multimodal landing page after verification. Leave it open; the agent's components appear there when needed.

No second connection SMS is needed. This works with a real handset and with Preview's simulated messages and authentication. If the customer closed the page, the link expired, or verification targets a different phone number, the agent can send a replacement link. One-time verification codes still arrive as their own messages.

Simulate authentication for Preview and recordings¶

To rehearse verification without setting up a passkey:

1. Open the agent's Customer Authentication capability and select Passkey.
2. In its Passkey settings, turn on Simulate authentication in Preview.
3. Start a new Preview call with simulated SMS delivery (leave SMS off).
4. Open the verification message in the test phone and tap its link.

This also works in Amazon Connect Telephony Preview when the contact flow reaches TrueServe through its configured Voice Connector. Keep SMS off and use a new call after changing the simulation setting.

The test phone opens its own Safari screen, shows a simulated Face ID prompt, confirms verification, and shows the multimodal landing page when that capability is enabled. With authentication alone, it returns to the connected call automatically. The agent continues as authenticated for that test. The whole screen stays inside the phone recording; no real biometrics, passkey setup, mobile device, or new browser tab is needed. The screen is labelled Preview simulation.

During the scan, Cancel returns to the call without submitting verification. Once confirmation is submitted, wait for its result. If verification fails, Try again retries while the link and test call are still valid. An expired link needs a new verification message.

This option is off by default and applies only to test calls using simulated messages. Live calls and tests using real SMS retain real passkey verification. The transcript records Identity verification simulated. Simulation creates no passkey and provides no real identity assurance.

Reviewing verifications¶

Every step — code sent, verified, failed attempt, lockout — is recorded in an audit trail with time, method, and result (never the code itself or the caller's answers). The conversation's transcript view shows the final verification status.

Troubleshooting¶

• "This agent is not configured to verify callers…" — the capability is off on the stage, or the running service has stale configuration. Current builds expose only ticked methods to the model and confine an unexpected method request to the configured default.
• "Customer Authentication is not enabled for this tenant" — flip the tenant switch in Settings → Tenant Settings → Customer Authentication.
• Codes don't arrive — check the Send codes and links by integration on the tenant page; the form also flags it inline ("No SMS integration is configured, so codes cannot be texted"). In Preview, codes and links appear in the test phone's Messages app by default. If your deployment exposes SMS, they instead go to the explicit Preview ANI while that mode is on. Unless Simulate authentication in Preview is on with simulated SMS delivery, a passkey message uses a direct browser link so the verification page opens in a real tab; if browser policy still prevents that tab, use Open verification on the emulator's Safari screen.
• The browser says “You don't have any passkeys saved” — cancel that dialog. It is an authentication prompt and cannot create the first passkey. On a current build, a caller with no registered credential sees Create your passkey instead and does not need a code when the agent is passkey-only.
• “We couldn't save a passkey” — select Try saving again. The page requests a fresh enrollment challenge and opens the device passkey prompt again; you do not need another one-time code while the verification link is still valid.
• More than one link arrives — an open customer page is reused when both capabilities are enabled. A closed or expired page, a changed recipient, or a change between simulated and real SMS can require another link. The agent should never create an “Authentication Required” visual card.
• It texted me the verification link without asking — on a current build the agent always asks first, including in the emulator (earlier builds skipped the question there because the visual renderer was pre-attached). If it still sends without asking, check that Ask permission to send and the stage prompt aren't instructing it to verify silently.
• No second link arrived for a card after I verified — this is expected when Multimodality is enabled. Keep the verification page open; it becomes the visual session automatically. If no component appears, confirm the agent rendered one in More → Multimodal View.
• The agent asks permission to message me twice — it shouldn't on a current build: the built-in instructions make the tool choose the enabled method and return the one question to ask, and consent is remembered for the whole call. If it happens, check Extra instructions, the greeting instruction, and the stage prompt for wording that independently tells the agent to ask before it calls the authentication tool.
• The agent keeps talking for a while after I verify — fixed on 12 August 2026. A completed verification now interrupts whatever the agent is saying, so it acknowledges you straight away instead of finishing an answer to the question you have just resolved.
• It mentioned a technical issue, went quiet, then started again — also fixed on 12 August 2026, on speech-to-speech agents. Telling the live voice model about a completed verification used a channel it accepts only once per call, which restarted the voice session: the apology and the pause were that restart, and the verification was never mentioned. If you still hear it, report the agent id and roughly when in the call it happened.
• Publish is blocked with an assurance error — your Required assurance is two factors but the ticked methods can't reach it. Add passkey, or add a knowledge check with Counts toward assurance on.

The simulated verification screen in Preview and Scene agents is headed Identity Verification. This customer-facing label does not change its simulated behavior.