---
title: "Voice agent settings reference"
description: "Every ThunderPhone voice agent setting explained: tiers, voices, languages, acknowledgements, tools, speak order, voicemail, consent announcements, silence handling, testing, and deployment."
---
Open **Voice Agents**, select an agent, and use its **Config** tab to control
how it sounds, reasons, starts calls, uses tools, handles silence and voicemail,
and reaches callers. Changes autosave to a draft; production traffic does not
change until you select **Deploy**.
This page is the complete dashboard reference. For field names and request
examples, use the [Agents API reference](/api-reference/agents).
## Prompt and identity
The agent name identifies it throughout the dashboard, reports, call history,
and client portals. The prompt is the agent's operating script: persona,
business facts, required questions, escalation policy, and call actions.
The prompt editor reports estimated tokens and flags common problems such as an
empty prompt, unresolved template placeholders, a missing escalation path, or
a very long prompt. The first **5,000 estimated tokens** are included; longer
prompts use [block-based surcharge pricing](/guides/pricing#prompt-size).
Transfers, keypad presses, hold behavior, and hang-up decisions can be written
directly into the prompt. Attach API, app, MCP, or knowledge tools when the
agent needs external data or actions.
For routing rules, cold transfers, and screened warm transfers, see
[Transfer calls](/guides/call-transfers).
## Model tier
{/* rate:tier-table */}
| Tier | Base price | Best fit |
| --- | ---: | --- |
| **Spark** | 2¢/min | Cost-sensitive, straightforward calls. |
| **Bolt** | 5¢/min | Fast responses and balanced everyday workflows. |
| **Storm** | 9¢/min | Complex instructions, audio understanding, and reasoning. |
{/* /rate */}
Storm exposes two optional controls:
- **Acknowledgement** — **None** stays silent while preparing the full reply;
**Tick** plays a soft waiting sound; **Verbal** speaks a brief acknowledgement
and adds **{/* rate:ack */}2¢/min{/* /rate */}**. Verbal text can be generated from the main prompt or
supplied manually. **Custom acknowledgement prompt** appears only when the
selected Storm mode supports verbal acknowledgements; otherwise that field is
unavailable.
- **Extra intelligence** — adds deeper reasoning for complex calls and
**{/* rate:extra */}3¢/min{/* /rate */}**.
The builder continuously shows the agent's **all-in cost per minute**, including
the tier, voice/language path, prompt length, verbal acknowledgement, extra
intelligence, and supervision.
## Voice, background, and languages
Select a voice and play its sample before deploying. The picker only requires
your chosen voice to support the **primary language**. If you turn on **Switch to native voices**,
additional languages can be covered by same-gender native catalog voices instead.
Premium combinations are marked with their surcharge. Your custom voices appear in
the same picker once ready. See [Voice library and custom voices](/guides/voice-library).
**Background track** can be:
- **None** — no ambient audio.
- **Call center** — a call-center ambience, with an in-dashboard preview.
Set one **primary language**, then any number of **additional languages**. The
agent automatically detects when a caller switches to a selected language and
responds in it. Some voice/language combinations add **{/* rate:language */}3¢/min{/* /rate */}**; see the
generated [Supported languages](/guides/supported-languages) catalog.
When an agent has **Additional languages**, enable **Switch to native voices**
to use a catalog voice native to the detected language, matched by gender. It
switches back to the configured voice for the primary language. If no matching
native voice is available, the current voice stays in use. Custom voices do not
switch. Test each language with **Talk**, then select **Deploy**.
Native switching has no separate surcharge. The selected language and voice
combination still determines whether the premium-language rate applies.
## Connected capabilities
The Config tab has four independently attachable capability sections:
| Section | Use it for |
| --- | --- |
| **Connected apps** | Approved operations in Google Calendar, Google Sheets, Slack, HubSpot, Salesforce, or Cal.com. |
| **API connections** | Your own HTTP endpoints, described as callable functions. |
| **Knowledge** | Files or web content the agent can search during a call. |
| **MCP servers** | Cached tools discovered from remote Model Context Protocol servers. |
An attachment is part of the draft and becomes available to production calls
after deployment. Configure the resources first under **Connections** or
**Knowledge**, then attach them to the agent.
## Phone and web endpoints
Under **Phone numbers**, attach an existing number, get a ThunderPhone number, or
import a number through a VoIP connection. A number can use different agents
for inbound and outbound directions.
Under **Web widgets**, attach a widget so visitors can speak to the agent from a
site. Widget availability can also be enabled or disabled as part of agent
configuration.
## Time zone
**Time zone**, under the phone numbers, is what the agent treats as "now": it
states the date and time, offers appointment times and works out "today" and
"tomorrow" in this zone. This agent's business hours in reports use it too.
A new agent starts with your organization's time zone, or your computer's if
the organization has none. Change it if your callers are somewhere else. When
the agent's phone number is in a different zone from the one you picked, the
builder says so and offers to switch.
An agent without a time zone (an older one, or one created through the API
without `timezone`) uses the zone of the number the call is on, then the zone
of the agent's numbers, then the organization's, then US Pacific. The builder shows which zone that is
and asks you to confirm it, or to pick one when the numbers don't settle it
(a toll-free number, or numbers in different zones).
When one agent serves contacts in several time zones, pass the zone with each
call instead: `timezone` on [`POST /v1/call`](/api-reference/outbound-calls) or
in your [configuration webhook's response](/guides/dynamic-call-config#set-the-time-zone-per-call).
### If your agent has no time zone yet
New agents require a time zone. Older agents can still have none.
If an older agent has no time zone, ThunderPhone first uses the agent's own
setting if there is one, then your organization's, then the time zone inferred
from the agent's phone numbers. If that still does not settle it, it falls
back to Los Angeles. The builder shows the resolved zone and asks you to
confirm it, or to pick one when the numbers do not settle it.
## Advanced call behavior
Expand **Advanced** at the bottom of Config for the following controls.
### Supervision
When enabled, a second AI monitor checks each agent turn against the
instructions and can intervene silently. Supervision adds **{/* rate:supervision */}4¢/min{/* /rate */}** and is not
available on Bolt.
### Connection tone
Play a short tone immediately after the call connects and before either party
speaks.
### Intro clip
Play a prerecorded clip at the start of inbound calls, followed by ringing,
so the line sounds like a company phone line before the agent answers. It plays
on inbound phone calls and on **Talk** (browser) test calls in the builder. It
does not play on outbound calls, AI test calls, web widget calls, or Realtime
API calls.
- **Off** (default) — the agent answers right away.
- **Recording notice** — a recorded voice says "This call may be monitored or
recorded, for quality assurance purposes." Preview it in the builder.
- **Your own recording** — upload an audio file (MP3, WAV, M4A, and other
formats your browser can play) or record one in the browser. Clips can be
0.5 to 15 seconds long. The builder converts the clip before uploading it,
and you can play it back or remove it.
**Ring after intro** sets how many US rings play after the clip: **Off**,
**1 ring** (default), or **2 rings**.
The order at the start of a call is: connection tone (if on), intro clip,
rings, then the [consent announcement](#consent-announcement) or
[AI-processing disclosure](#ai-processing-disclosure) if they apply, then the
greeting. The intro clip never replaces the consent announcement or the
AI-processing disclosure, even when your clip says the call is recorded.
Caller audio is not processed while the clip and rings play. A custom clip is
fetched when the call starts; if it cannot be loaded within a few seconds, the
call goes ahead without it, so a failed load can delay the greeting by up to
about 3 seconds.
The intro clip is a draft setting like the others: it reaches live calls when
you deploy.
Stock recording notice voice: Allison Smith,
[CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/), adapted
(trimmed, joined, resampled) by ThunderPhone.
### Tool sound
Choose the sound made by the prompt-callable sound tool:
- **None** — the tool is not offered.
- **Chime**, **Ding**, or **Beep** — each can be previewed in the builder.
### Typing sounds
Enable **Typing sounds** to play a soft keyboard sound while the agent runs a
custom tool. Platform-managed tools do not trigger it.
Once it is on, pick the sound. Each one can be previewed in the builder:
- **Keyboard and mouse** (default): typing with mouse clicks, like someone looking it up.
- **Mechanical keyboard**: bright, clicky mechanical keys.
- **Desktop keyboard**: steady typing on a standard keyboard.
- **Laptop**: soft, flat laptop keys.
- **Office keyboard**: quiet, muted office keyboard.
- **Quiet room**: soft room tone with one person typing.
### Tool-start line
Choose whether something is said when the agent calls a tool:
- **Always** (default for new agents): something is said at every tool call,
however fast the tool returns. If the agent spoke with the call, its own words
are that line. Otherwise a short line written for the call plays as soon as
it is ready, or a standard one such as "One moment, please" if it takes more
than about a second. Tools that play their own audio or act on the call
itself (keypad input, sounds, hold, transfers, ending the call, step
handoffs) still get a line only if they are slow, and so does any tool
while the agent is in a phone menu or talking to voicemail.
- **Only if the tool is slow**: a short line plays only if the tool is still
running about 3 seconds after the agent last spoke. Agents created before
this setting existed keep this choice.
- **Never**: ThunderPhone says nothing when a tool starts, and the agent is
told not to speak when it calls a tool. Anything the agent still says with
the call plays.
The agent's own words always play, whichever option you pick. The caller hears
at most one tool-start line per turn: a line already spoken in that turn, such
as the agent's words or a filler on a slow reply, counts as it.
### Long-wait updates
On by default. When a tool is still running after about 12 seconds of
silence, the agent says it is still working on it, then adds a short patience
line about every 15 seconds until the result arrives. These lines are worded
for the call: they follow the agent's prompt and persona, the conversation so
far and the call language, so they do not repeat one fixed sentence. If a line
cannot be written in time, the agent uses a standard one such as "Sorry, this
is taking a little longer than expected". Slow replies without a tool get
short standard lines such as "Just a sec".
Turn **Long-wait updates** off to stay quiet after the tool-start line until
the result arrives. Slow replies without a tool then get no filler either.
Typing sounds still play if they are on. Storm's acknowledgement setting is
separate and is not affected.
### Settings win over the prompt
Tool-start line and Long-wait updates decide what ThunderPhone says while a
tool runs. Prompt text cannot stop or add these lines. For an agent that stays
silent while tools run, set **Tool-start line** to **Never** and turn
**Long-wait updates** off rather than asking for silence in the prompt. The
builder's prompt check warns when the prompt asks for silence, or for a line
at every tool call, and these settings say otherwise.
### Send email
Enable **Send email** and enter one recipient address to give the agent the
`send_email` tool. The address is fixed in the agent settings. The model writes
the subject and plain-text body, but it cannot choose or change the recipient.
Prompt the agent with the exact situations that should produce an email, such
as sending a caller's message after collecting their name and callback number.
See [Built-in tools](/guides/built-in-tools) for the full tool behavior.
### Calculator
Enable **Calculator** to give the agent the `calculate` tool. The agent uses it
to add up order totals, fees and change exactly instead of doing the math
itself. It is off by default; turn it on for agents that quote prices. No
prompt change is needed.
See [Built-in tools](/guides/built-in-tools) for the full tool behavior.
### Send SMS
Enable **Send SMS** to give the agent a `send_sms` tool.
Choose which connected VoIP number (Twilio or Telnyx, SMS-capable and verified) to
send from; ThunderPhone-provisioned numbers cannot send SMS. You can limit
sending to the caller only, or allow other recipients and keep an allowlist of
approved numbers. You can also enable an SMS follow-up template for messages
sent after the call.
See [Built-in tools](/guides/built-in-tools) for the full tool behavior.
### Extra audio context
**Extra audio context** controls how much recent caller audio is carried
between turns:
- **Automatic (recommended)** uses more recent audio for inbound, browser, and
WebSocket calls, and only the latest turn for outbound phone calls.
- **On** includes the last few caller turns to help with corrections, spelling,
and number-heavy data collection.
- **Off** includes only the latest caller turn for lower latency.
The Agents API also exposes the Storm-only `audio_context_mode` compatibility
field: `full` or `reduced`. It is separate from the dashboard's
`additional_audio_context` tri-state above.
### Who speaks first
Configure inbound and outbound calls separately:
- **Inbound:** agent speaks first, or caller speaks first.
- **Outbound:** agent speaks first, or callee speaks first.
To remove the agent's initial greeting, choose **Caller speaks first** for
inbound calls or **Callee speaks first** for outbound calls.
This setting is useful for outbound dialers that must wait for a person or
phone menu before beginning the script.
### Voicemail handling
Choose what happens when an outbound call reaches voicemail:
| Option | Behavior |
| --- | --- |
| **Let the agent decide** | The prompt and conversation context determine whether to speak or hang up. |
| **Hang up silently** | End without leaving a message. |
| **Leave a message, then hang up** | Speak the configured message and end the call. |
Voicemail messages can contain up to **2,000 characters** and support
`{agent_name}` and `{org_name}`. See
[Pricing](/guides/pricing#hold-time-and-phone-menus) for how call time is
metered.
### Consent announcement
By default, a short announcement at the start of every call tells the caller
that they are speaking with an AI assistant and that the call is recorded. You
can edit the announcement text, up to **2,000 characters**; it plays verbatim
in the agent's language.
Disabling the announcement on an eligible agent requires an organization admin
to affirm that the organization will provide any legally required notice and
obtain any legally required consent. Re-enabling and later disabling it
requires a new affirmation. Review the
[recording consent laws guide](/guides/recording-consent-laws) before changing
this setting.
### Record calls
**Record calls** controls whether this agent stores call audio, transcripts,
and other call content. The organization-wide recording setting must also be
enabled for recording to occur. When recording is off, those artifacts are not
stored. A recording covers at most the first 3 hours of a call; a longer call
continues, but the audio after 3 hours is not recorded. See [Call recording consent laws](/guides/recording-consent-laws#turning-recording-off-and-the-ai-processing-disclosure).
### AI-processing disclosure
When recording is off, **AI-processing disclosure** controls the shorter notice
that audio is processed live but not recorded. Choose **Use organization
setting**, **Always play**, or **Don't play**. Disabling the disclosure requires
an organization-admin attestation.
### Uninterruptible disclosures
**Uninterruptible disclosures** remains visible for compatibility, but enabling
it has no effect. Leave it off. For required opening language, use **Consent
announcement**, which plays before conversation and cannot be interrupted.
### Silence check-ins
When enabled, the agent checks whether the caller is still present after a
period of silence, repeats up to your limit, then hangs up:
- **Seconds before check-in:** 10–120 seconds.
- **Maximum check-ins:** 1–10.
The defaults are 15 seconds and 3 check-ins.
### Call length and timeouts
Use these controls to keep stalled or unusually long calls from accumulating
call time and telephony charges:
- **Minutes of silence before hanging up:** 1–60 minutes. The default is 10
minutes and applies when silence check-ins are disabled.
- **Max call duration:** 1–360 minutes. New agents start at 60 minutes,
except agents made from the Interpreter template, which start with no
agent-level cap; raise it, lower it, or switch it off for no agent-level
cap. Agents created before this default keep their existing setting. 45 seconds before the
limit (a quarter of the limit when it is under 3 minutes) the agent is told
to wrap up and say goodbye.
- **Platform limit:** every call ends after 6 hours, whatever the agent's
setting. The agent gets the same wrap-up warning first.
- **Ring duration:** let outbound and transferred calls ring for 5–120 seconds.
Leave it unset for platform defaults: 60 seconds for outbound calls, 45
seconds for warm transfers, and the carrier default for cold transfers.
This setting does not affect inbound ringing.
## Builder tabs and lifecycle
| Tab or action | Purpose |
| --- | --- |
| **Live / Talk** | Speak with the current draft in your browser and inspect transcript and tool activity. |
| **Calls** | Review calls handled by this agent. |
| **A/B** | Create prompt or configuration variants and compare live outcomes. |
| **Simulate** | Run saved or ad-hoc AI-caller scenarios against the draft. |
| **Validation** | Replay frozen real-call turns against the draft before deployment. |
| **History** | Compare deployed revisions and restore one into the draft. |
| **Discard** | Revert every pending draft setting to the deployed version. |
| **Deploy** | Atomically promote the complete draft and create a revision. |
If another editor saves the same agent after you loaded it, ThunderPhone stops
the conflicting save or deploy and asks you to refresh rather than overwriting
their changes.
## Manage agents from the list
The **Voice Agents** page also supports organization-level lifecycle actions:
- **Duplicate** an agent as a new starting point in the same organization.
- **Transfer** an agent to another organization you belong to. **Copy** keeps
the source; **Move** removes it from the current organization and requires
administrator access.
- Delete one agent, or bulk-delete selected agents, after confirmation.
### Export the agent list
Select one or more agents and export their summary fields as **CSV** or
**JSON**. The export does not include full prompts and is not a configuration
backup.
Copying or moving an agent across organizations does not silently grant the
destination organization access to source-only connections. Review the copied
agent's app, API, knowledge, MCP, phone-number, and widget attachments before
deploying it there.
## Related pages
A concise end-to-end builder walkthrough.
Base tiers, add-ons, call metering, numbers, and one-time charges.
Freeze real-call turns and replay them before deploying.
Request fields, drafts, deploys, versions, and examples.