Guides

Simulated calls

Run a few phone calls against your agent with a synthetic caller, then play and download the recordings, read the transcripts and see pass or fail.

When an agent is built, you can hear it work before anyone dials it. A simulated call is a real call through the agent's own voice pipeline, with real speech recognition, model and voice, but the caller is the platform: it says lines you choose, waits for the agent between them, and hangs up at the end. No phone rings and no telephony is charged.

In the dashboard: Voice agents, the agent, Simulate calls in the bottom bar; or Simulate calls in the graph builder's toolbar. The panel uses the agent as it was last saved.

What a run is

A run is one to five calls, played one after another. Each call is one of:

a caller script you type: one line per sentence, in order;
a suggestion: for a graph agent, one call per path from the start node to a closing step, with the expected outcome; for any other agent, a few plain starters in the language you pick;
a workflow test of a graph agent (see Graph agents): its lines, starting variables and expectations. Lines that inject an event cannot be spoken and are skipped.

Before you start, the panel shows an estimate: minutes on the line, how long until the results are ready, and the cost.

What you get per call


Recording	Both sides in one WAV file: play it in the panel or download it
Transcript	What the agent heard and said, turn by turn
Pass or fail	The checks below, each with the reason when it fails
Latency	Per line, the time from the caller stopping to the agent's first audio; the time to the welcome; the median
Call record	A link to the call in the call log, with its logs, path and cost

Download all saves one ZIP of the run: per call the recording (.wav), the transcript with the checks and latencies (.txt) and the full result (.json), plus run.json.

How a call passes

The call ended cleanly: its record is completed, with no error.
The agent spoke, and answered every line.
For a graph agent with expectations: the call ended on the expected step, went through (or avoided) the steps named, and extracted the expected values. These are the same rules as workflow tests.

The caller's voice

The caller speaks with the text-to-speech server's default voice. A cloned voice is never used for the caller. The lines are said as written, so write them in the language the agent should hear.

Which voice pipelines can be simulated

Pipeline	Simulated calls
Sonic voice engine (`own`)	Yes: real audio, the stream the agent's phone provider would send
An external pipeline	Yes, if it takes Exotel or Twilio media streams and is enabled. It receives `pipeline_id` and `signature` as on any call. If it makes no recording, the panel keeps the simulated line's own recording of both sides
Simulation (`mock`)	A scripted simulation: the lines go in as text, there is no audio or latency, and the recording is tones
Open-source engine (`oss`)	No. The panel says so; switch the agent to the Sonic voice engine to simulate calls

See Voice pipelines.

Where simulated calls show up

In the call log, with a Simulated badge.
Not in Insights unless you tick Include simulated calls, and not in report exports unless the request sets include_simulated: true.
Never sent to your webhooks.
In the wallet: priced like a browser test call, with no telephony charge. The platform fee and the agent's models are priced as usual; the platform's own models cost nothing.

Limits

5 calls per run, 8 lines per call, 300 characters per line.
3 runs per hour per account, one run at a time.
One simulated call at a time on the whole platform, so a run may wait for another to finish. Its progress says so.
Cancel hangs up the call on the line and starts no further call. Finished calls are kept.

API

bash

curl -X POST https://api.kshyamai.space/simulations \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "3c90c3cc-0d44-4b50-8822-8dd25736052a",
       "language": "en",
       "calls": [{"name": "Bill question", "lines": ["Hello, I have a question about my bill.", "Thank you, bye."]}]}'

The answer is 202 with the run. Poll GET /simulations/{run_id} until status is done; each finished call is in results with its execution_id, recording_url, transcript, latency, checks and passed. GET /simulations/{run_id}/download returns the ZIP. Also: GET /simulations/agents/{agent_id}/setup (can this agent be simulated, its workflow tests, the limits), POST /simulations/agents/{agent_id}/suggest, POST /simulations/estimate, GET /simulations and POST /simulations/{run_id}/cancel. Reading needs the viewer role; starting and cancelling, member.