Testing with the emulator

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

The phone emulator lets you talk to a draft agent end-to-end from inside the browser, without dialing a real phone number. Use it to validate prompt changes, tool wiring, and voice/STT settings before publishing.

Open the emulator

  1. Open the agent.
  2. Pick the version you want to test (draft or published).
  3. Click Preview in the editor header, or open the Preview panel on the right using its vertical handle.
  4. Use the full-screen icon in the Preview header when you want the emulator to replace the canvas and inspector.

Viewer access supports Preview for Voice and Chat agents while the canvas, prompts and settings stay read only. The Preview header identifies the selected Draft or published version. Template variable values entered here are for this preview only and do not change the saved agent. Use Test to open the testing workspace directly, with Overview, Tests, and Results.

Preview uses one slim header and keeps Assistant in the separate chat button at the lower right, leaving more vertical room for the complete phone frame.

The emulator opens a real WebRTC call against the orchestrator using the version you selected — this is the same code path a production phone call takes.

If the agent cannot start, Preview now shows an error panel above the disabled controls with the exact configuration or runtime-readiness issue. Fix that issue and Preview checks the agent again automatically; you do not need to close and reopen the panel.

Present in Demo Mode

In maximized phone Preview, click Demo Mode (the presentation icon beside the minimize button). The view fills the browser workspace with just the phone and AI Activity, hiding the header, setup widgets and other controls. AI Activity appears automatically; on narrow screens it sits below the phone.

Set up your call, Telephony destination, Mock Caller or recording first. You can enter Demo Mode before or during a call and keep using the phone's call controls. Click Exit demo at the top right or press Escape to restore the setup view. Your call continues, entered values remain, and the previous Show AI Activity setting is restored. Demo Mode does not save changes to the agent.

Share a configured Preview

In maximized Preview, choose your settings, then click Copy preview link (the link icon beside Demo Mode). The recipient opens the same agent version directly in Demo Mode. For chat and compact layouts, the link opens maximized Preview. The copy button is also available beside Exit demo.

The link includes:

These settings take precedence over the recipient's saved browser preferences. They still need access to the agent and the selected integrations. Opening the link waits for them to start the call; it does not request their microphone, start a recording, or resume your conversation.

The browser address also updates as you change settings in maximized Preview. Copying that address preserves the current full-screen or Demo view. Minimizing Preview removes the settings from the address.

The encoded part after #preview= contains the supplied values, so use demo data appropriate to share with the recipient. It excludes integration credentials, agent configuration, live call state and the shared Debug setting. Copilot/translation test-agent selections and in-call tools stay local. Long prompts or variables may exceed the link limit; shorten them if copying reports an error. Sign-in preserves the setup.

Supply template variables

Before starting a test call, enter context values in Template Variables. In full-screen Preview, this widget sits in the left column beside the phone, below any Mock Caller, Telephony or Recording controls. Fields use one or two columns based on the widget width. Long lists scroll inside the widget with its title remaining visible, keeping the controls within the bottom of the phone. On narrow screens, the controls stack above the phone in a bounded scrolling area. In compact Preview, variables remain below the phone. Variables referenced only in a sub-agent's prompt appear here too, including in-conversation specialists. For example, adding {{spec_context}} to the Specialist Agent prompt adds a Spec Context field in Preview without needing to reference it in Main. The field appears while you edit the prompt and is also available when you reopen the saved draft.

Direct-WebRTC Preview accepts up to 256 KiB across all template variables, including their JSON encoding. Larger inputs produce an error before the call starts; reduce the context and retry. Your selected model's context window can be smaller than this transport limit, so a very large document may still exceed what the model accepts.

Talk to the agent

The preview opens on the iPhone Home screen with the agent's name in the call banner at the top. Click the green phone icon—or anywhere on the Home screen—to start the test call. Your microphone is requested; allow it. The shared iPhone preview then shows:

During a call, tap More for the additional test tools:

For copilot or agent-assist pipelines, the Copilot Suggestions panel is the test surface. Choose the voice AI agent from the panel header, then click Start Call in the center of the suggestions panel. If that target voice AI agent is still draft-only, Preview tests it as a draft so the assist pipeline can run before either agent is published.

Test multimodal (visual) agents

The phone's Safari view has a frosted address pill and a floating bottom toolbar. Use the bottom Back arrow to return to Messages or Home, or tap the green call timer in the top island to return to the call. The share-shaped Open in browser control opens the link in your browser. Dimmed browser controls are decorative; live cards update automatically. Cards scroll between the bars so their buttons remain reachable.

Check the cards during an actual Preview call as well as in the catalog's component preview. Open the visual link in the phone's simulated message, then verify that card spacing, colors, and action buttons are styled correctly. Use the catalog's component preview as the reference: compare the same component, data, width, and light/dark appearance. Cards in the phone use the catalog preview's default appearance and the browser's color scheme; the phone controls keep their own appearance. A custom appearance saved separately in Surface App is not synchronized to the phone. If a styling problem appears identically in both previews, report it as a catalog issue rather than an agent-preview mismatch.

Preview rehearses the real caller experience: the agent asks permission before it sends anything, and the message arrives in the test phone's Messages app. Each test call starts with a clean tray — messages from earlier test runs don't pile up, and a banner you've already seen won't slide in again later. Only the carrier is simulated — the question, the share link, and the visual session behind it are all real. Tap the message to open the surface, then keep talking; the call stays active in the Dynamic Island the whole time, and More → Multimodal View reopens the surface after you navigate back to the call screen.

If your deployment enables real-SMS testing, full-screen Preview also shows SMS beside Recording. Enter the real handset number in Template Variables → ANI, then turn on SMS before starting the call. Preview keeps the call audio in the browser phone but sends every capability message—including multimodal links and Customer Authentication codes or links—through the configured carrier SMS integration to that ANI. A blank ANI disables the start action; the demo fallback number is never used for real delivery. Turn the mode off to return all messages to the simulated Messages app. This option can incur carrier charges and is hidden unless a platform administrator enables it.

Verifying the caller and showing them a card are two different sessions, so each has its own link. A card requested after verification therefore sends a second, different message — the agent explains that rather than asking permission again, because a completed code or passkey already counts as agreement to be messaged.

When a conversation moves between purpose-built components from different selected catalogs—for example, from an appointment summary to a photo-capture widget—the current visual view switches to the new component automatically. Each component keeps its own catalog behind the scenes; you do not need to reopen the message, return to the call, or speak again to make the next screen appear. If the voice model announces the next screen without sending it—or only disables the old Done button—the runtime keeps the transition pending and retries the visual action once automatically.

Customer Authentication passkey links use a different final step. The secure message still arrives in the emulator's Messages app, but tapping it opens the Surface App verification page in a real browser tab so the browser can use your actual fingerprint, face, PIN, or security key. The simulated call remains connected. If your browser blocks the new tab, tap Open verification on the emulator's Safari screen. On the first test for a caller identity, no passkey exists yet: the page opens code entry, the agent sends a one-time code to Messages, and after you enter it the page offers Save a passkey. Accept the real browser's device prompt to register it; a later test with the same customer identity can authenticate with that passkey. An authentication request sends one secure verification link; it does not also send a multimodal connection link or require an A2UI authentication card. After verification succeeds, the live agent is notified automatically and continues the call; you should not have to tell it that verification finished. Idle prompts are paused while the secure step is pending. Customer Authentication passkey links use a different final step. The secure message still arrives in the emulator's Messages app, but its direct browser link opens the Surface App verification page in a real browser tab so the browser can use your actual fingerprint, face, PIN, or security key. The simulated call remains connected. If browser policy still prevents the tab, tap Open verification on the emulator's Safari screen. On the first test for a caller identity, no passkey exists yet: the page opens Create your passkey directly. Select Save a passkey, accept the real browser's device prompt, then select Verify with your new passkey. A passkey-only test sends no one-time code; a later test with the same customer identity can authenticate with the saved passkey. An authentication request sends one secure verification link; it does not also send a multimodal connection link or require an A2UI authentication card. After verification succeeds, the live agent is notified automatically and continues the call; you should not have to tell it that verification finished. Idle prompts are paused while the secure step is pending.

Payments can be tested on linear speech-to-speech drafts. When keypad capture begins, the live model is muted and receives silence; scripted text-to-speech gives the instructions, and the original speech-to-speech session resumes with the masked result. Parallel/swimlane payment agents are not supported yet.

To enter the digits, open the Keypad control and press them there — the emulator sends each press straight to the secure collector, so typing on your computer keyboard does nothing. Press hash (#) to end each step. If the agent has Read the last four digits back on, it then reads them back and waits for 1 to authorise the charge; pressing hash again does not confirm, and the capture eventually times out and announces itself cancelled. The full key list is in Payments.

Test a CCaaS route from the standalone emulator

Open /emulator when you want the phone frame to place a test call through a configured CCaaS integration instead of directly testing the draft agent. Pick the tenant and platform at the top of the phone.

For Amazon Connect, choose the flow you want to start, fill in the participant details the flow expects, then click the green call button. The emulator starts a Connect web contact and joins the returned browser audio session. The contact appears to Amazon Connect as an inbound web contact, so contact flows should treat the entered attributes as test input rather than verified caller identity.

Recent calls remember the transport, selected flow, participant display name, caller ID fields, and custom attributes so you can replay the same test quickly.

Set up a demo run

Demo Settings on the standalone emulator preconfigures a run so nothing has to be picked on camera. With Enable demo mode on, the tenant, platform, and extension selectors are hidden, the dialer is prefilled with the number you entered, and the contact photo you gave replaces the caller avatar on the call screen.

Turn on Start on the lock screen when you are recording. The phone then opens on the iPhone lock screen with the live date and time; tap it to reveal the Home screen, place or answer the call as usual, and the lock screen slides back down over the Home screen when the call ends. Leave it off while you are actually testing an agent — the Preview panel and the embedded phone always start on the Home screen, and matching that keeps a test one click shorter.

Inspect what's happening

The phone's More → Transcript view is the quickest way to follow the caller and agent turns. For frame-level diagnosis, turn on Debug and open the live debugger, where you can inspect:

This is the fastest way to figure out why an agent said something unexpected.

Live frame debugging

Use Debug in the Preview panel when you need to inspect Pipecat/Whisker frames while a test call is running. Debug is a team-wide agent setting: turning it on for an agent means future emulator test calls for that agent publish live frame sessions until someone turns it off.

  1. Turn Debug On in Preview.
  2. Click Launch Debugger. The debugger opens with the current agent selected.
  3. Start a test call. The active session appears under the agent name in the debugger sidebar.
  4. Select the session to connect to its live frame stream, then inspect processors, frame counts, and frame details.

Use frame search when a session has too much traffic to scan by hand. The Signals filter narrows the frame list to tool calls, end_session, EndFrame, cancel, and disconnect markers. The frame window can jump between oldest frames, newest frames, or the selected frame, and Export downloads the captured frame history for offline review.

The debugger page lists every debug-enabled agent you can view in the current tenant, so teammates can work on overlapping test calls without sharing one fixed debug port. When a test call ends, the session changes to closed but stays available on the debugger page while the captured frames remain in the browser tab for review.

Multiple test sessions

Each click of the call button starts a new conversation. Hang up before starting a fresh test or you'll have two sessions running and traces will interleave.

Record a demo

Open Preview full-screen, turn on Recording, then select Test & Record in the Recording widget to the left of the phone. Its status, Record, Stop, and download buttons stay in that widget while the Preview header remains the same. Your browser asks which tab to capture; choose the current TrueServe tab. The test call starts only after capture is allowed, and the recorder cancels if the browser returns a window or screen capture instead of a browser-tab capture. Collapsing Preview stops recording and clears all mode switches.

Recording uses the same iPhone frame and screens as the normal Preview and fits the full phone frame within the canvas, so the recording includes the complete frame even when the editor itself would otherwise scroll. Multimodal and Customer Authentication messages use the same delivery mode as the normal Preview: the simulated Messages app by default, or the explicit ANI while SMS is on. Authentication ceremonies still hand off to the outer browser.

When the call ends, or when you click Stop, the Recording widget offers an MP4 download that combines the phone frame, screen activity, and call audio. The selected download button shows a spinner until the file is ready.

Limits

When the emulator is silent

See Why is the emulator silent. Almost always it's a microphone permission or a draft pipeline with a validation error.

See also

When Customer Authentication and Multimodality are both enabled, keep the customer page open: verification appears there and disappears when complete. An auth-first page becomes the multimodal landing page, including in opted-in Preview simulation, so later components need no second SMS. Real passkey verification still uses the real browser; a verification requested from native emulator Safari offers Continue verification for the same page. See Customer Authentication.