Voice agent settings reference

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.

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.

For routing rules, cold transfers, and screened warm transfers, see Transfer calls.

Model tier#

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 2¢/min. 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 3¢/min.

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.

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 3¢/min; see the generated 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:

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 or in your configuration webhook's response.

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 4¢/min 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 or 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.

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 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 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 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:

Voicemail messages can contain up to 2,000 characters and support {agent_name} and {org_name}. See Pricing 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 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.

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#

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#