Skip to main content

ai.params

Parameters for AI that can be passed in ai.params at the top level of the ai Method. These parameters control the fundamental behavior and capabilities of the AI agent, including model selection, conversation management, and advanced features like thinking and vision.

params
object

An object that accepts the params parameters.

params Parameters​

ai_model
string
Default: gpt-4o-mini

The AI model that the AI Agent will use during the conversation.

Available AI Models: gpt-4o-mini, gpt-4.1-mini, gpt-4.1-nano

conscience
string
Default: "Remember to stay in character. You must not do anything outside the scope of your provided role."

Sets the prompt which binds the agent to its purpose.

conversation_id
string

Used by check_for_input and save_conversation to identify an individual conversation.

conversation_sliding_window
integer

Sets the conversation history window size (number of turns to keep in context).

direction
string
Default: the natural direction of the call

Forces the direction of the call to the assistant. Valid values are inbound and outbound.

enable_thinking
boolean
Default: false

Enables thinking output for the AI Agent. When set to true, the AI Agent will be able to utilize thinking capabilities.
Important: This may introduce a little bit of latency as the AI will use an additional turn in the conversation to think about the query.

enable_vision
boolean
Default: false

Enables visual input processing for the AI Agent. The image that will be used for visual processing will be gathered from the users camera if video is available on the call.
When set to true, the AI Agent will be able to utilize visual processing capabilities, while leveraging the get_visual_input function.

languages_enabled
boolean
Default: false

Allows multilingualism when true.

local_tz
string
Default: GMT

The local timezone setting for the AI. Value should use IANA TZ ID

save_conversation
boolean
Default: false

Send a summary of the conversation after the call ends. This requires a post_url to be set in the ai parameters and the conversation_id defined below. This eliminates the need for a post_prompt in the ai parameters.

summary_mode
string

Summary generation mode. Valid values: "string", "original".

thinking_model
string
Default: Value of `ai_model`

The AI model that the AI Agent will use when utilizing thinking capabilities.

Available AI Models: gpt-4o-mini, gpt-4.1-mini, gpt-4.1-nano

transfer_summary
boolean
Default: false

Pass a summary of a conversation from one AI agent to another. For example, transfer a call summary between support agents in two departments.

vision_model
string
Default: Value of `ai_model`

The AI model that the AI Agent will use when utilizing vision capabilities.

Available AI Models: gpt-4o-mini, gpt-4.1-mini, gpt-4.1-nano

wait_for_user
boolean
Default: false

When false, AI agent will initialize dialogue after call is setup. When true, agent will wait for the user to speak first.

Speech Recognition​

Configure how the AI agent processes and understands spoken input, including speaker identification, voice activity detection, and transcription settings.

asr_diarize
boolean
Default: false

If true, enables speaker diarization in ASR (Automatic Speech Recognition). This will break up the transcript into chunks, with each chunk containing a unique identity (e.g speaker1, speaker2, etc.) and the text they spoke.

asr_smart_format
boolean
Default: false

Enables smart formatting for ASR output, improving the readability of transcribed text.

asr_speaker_affinity
boolean
Default: false

If true, will force the AI Agent to only respond to the speaker who responds to the AI Agent first. Any other speaker will be ignored.

end_of_speech_timeout
integer
Default: 700

Amount of silence, in ms, at the end of an utterance to detect end of speech. Allowed values from 0-10,000.

energy_level
number
Default: 52

Amount of energy necessary for bot to hear you (in dB). Allowed values from 0.0-100.0.

first_word_timeout
integer
Default: 1000

Timeout for detecting the first word of user speech. Allowed values from 0-10,000 ms.

llm_diarize_aware
boolean
Default: false

If true, the AI Agent will be involved with the diarization process. Users can state who they are at the start of the conversation and the AI Agent will be able to correctly identify them when they are speaking later in the conversation.

openai_asr_engine
string
Default: deepgram:nova-3

The ASR (Automatic Speech Recognition) engine to use. Common values include deepgram:nova-2, deepgram:nova-3, and other supported ASR engines.

Speech Synthesis​

Customize the AI agent's voice output, including volume control, voice characteristics, emotional range, and video avatars for visual interactions.

ai_volume
integer
Default: 0

Adjust the volume of the AI. Allowed values from -50-50.

eleven_labs_similarity
number

The similarity slider dictates how closely the AI should adhere to the original voice when attempting to replicate it. The higher the similarity, the closer the AI will sound to the original voice. Valid values range from 0.01 to 1.0.

Important: This will only works when elevenlabs is set in the ai.languages.voice as the engine id.

eleven_labs_stability
number

The stability slider determines how stable the voice is and the randomness between each generation. Lowering this slider introduces a broader emotional range for the voice. Valid values range from 0.01 to 1.0.

Important: This will only works when elevenlabs is set in the ai.languages.voice as the engine id.

max_emotion
integer
Default: 30

Maximum emotion intensity for text-to-speech. Allowed values from 1-30.

speech_gen_quick_stops
integer
Default: 3

Number of quick stops for speech generation. Allowed values from 0-10.

tts_number_format
string
Default: international

The format of the number the AI will reference the phone number.
Valid Values: international(e.g. +12345678901) or national(e.g. (234) 567-8901).

video_idle_file
string

URL of a video file to play when AI is idle. Only works for calls that support video.

video_listening_file
string

URL of a video file to play when AI is listening to the user speak. Only works for calls that support video.

video_talking_file
string

URL of a video file to play when AI is talking. Only works for calls that support video.

Interruption & Barge Control​

Manage how the AI agent handles interruptions when users speak over it, including when to stop speaking, acknowledge interruptions, or continue regardless.

acknowledge_interruptions
boolean | number
Default: false

Instructs the agent to acknowledge crosstalk and confirm user input when the user speaks over the agent. Can be boolean or a positive integer specifying the maximum number of interruptions to acknowledge.

barge_functions
boolean
Default: true

Allow functions to be called during barging. When false, functions are not executed if the user is speaking.

barge_match_string
string

Takes a string, including a regular expression, defining barge behavior. For example, this param can direct the AI to stop when the word "hippopotomus" is input.

barge_min_words
integer

Defines the number of words that must be input before triggering barge behavior. Allowed values from 1-99.

enable_barge
string
Default: "complete,partial"

Controls when user can interrupt the AI. Valid values: "complete", "partial", "all", or boolean. Set to false to disable barging.

interrupt_on_noise
boolean | integer
Default: false

When enabled, barges agent upon any sound interruption longer than 1 second. Can be boolean or a positive integer specifying the threshold.

interrupt_prompt
string

Provide a prompt for the agent to handle crosstalk.

transparent_barge
boolean
Default: true

When enabled, the AI will not respond to the user's input when the user is speaking over the agent. The agent will wait for the user to finish speaking before responding. Additionally, any attempt the LLM makes to barge will be ignored and scraped from the conversation logs.

transparent_barge_max_time
integer
Default: 3000

Maximum duration for transparent barge mode. Allowed values from 0-60,000 ms.

Timeouts & Delays​

Set various timing parameters that control wait times, response delays, and session limits to optimize the conversation flow and prevent dead air.

attention_timeout
integer
Default: 5000

Amount of time, in ms, to wait before prompting the user to respond. Allowed values: 0 (to disable) or 10,000-600,000.

attention_timeout_prompt
string
Default: The user has not responded, try to get their attention. Stay in the same language.

A custom prompt that is fed into the AI when the attention_timeout is reached.

digit_timeout
integer
Default: 3000

Time, in ms, at the end of digit input to detect end of input. Allowed values from 0-30,000.

hard_stop_prompt
string
Default: "Explain to the user that the call has reached its maximum duration and you need to end the conversation."

A final prompt that is fed into the AI when the hard_stop_time is reached.

hard_stop_time
string

Specifies the maximum duration for the AI Agent to remain active before it exits the session. After the timeout, the AI will stop responding, and will proceed with the next SWML instruction.
Time Format

  • Seconds Format: 30s
  • Minutes Format: 2m
  • Hours Format: 1h
  • Combined Format: 1h45m30s

inactivity_timeout
integer
Default: 600000

Amount of time, in ms, to wait before exiting the app due to inactivity. Allowed values: 0 (to disable) or 10,000-3,600,000.

initial_sleep_ms
integer
Default: 0

Amount of time, in ms, to wait before the AI Agent starts processing. Allowed values from 0-300,000.

outbound_attention_timeout
integer
Default: 120000

Sets a time duration for the outbound call recipient to respond to the AI agent before timeout. Allowed values from 10,000-600,000 ms.

speech_event_timeout
integer
Default: 1400

Timeout for speech events processing. Allowed values from 0-10,000 ms.

speech_timeout
integer
Default: 60000

Overall speech timeout (developer mode only). Allowed values from 0-600,000 ms.

Audio & Media​

Control background audio, hold music, and greeting messages to enhance the caller experience during different phases of the conversation.

background_file
string

URL of audio file to play in the background while AI plays in foreground.

background_file_loops
integer
Default: undefined

Maximum number of times to loop playing the background file.

background_file_volume
integer
Default: 0

Defines background_file volume. Allowed values from -50 to 50.

hold_music
string

A URL for the hold music to play, accepting WAV, mp3, and FreeSWITCH tone_stream.

hold_on_process
boolean
Default: false

Enables hold music during SWAIG processing.

static_greeting
string

A static greeting to play at the start of the call.

static_greeting_no_barge
boolean
Default: false

If true, the static greeting will not be interrupted by the user if they speak over the greeting. If false, the static greeting can be interrupted by the user if they speak over the greeting.

SWAIG Functions​

Configure SignalWire AI Gateway (SWAIG) function capabilities, including permissions, execution timing, and data persistence across function calls.

function_wait_for_talking
boolean
Default: false

If true, the AI will wait for any filler to finish playing before executing a function.
If false, the AI will asynchronously execute a function while playing a filler.

functions_on_no_response
boolean
Default: false

Execute functions when the user doesn't respond (on attention timeout).

swaig_allow_settings
boolean
Default: true

Allows tweaking any of the indicated settings, such as barge_match_string, using the returned SWML from the SWAIG function.

swaig_allow_swml
boolean
Default: true

Allows your SWAIG to return SWML to be executed.

swaig_post_conversation
boolean
Default: false

Post entire conversation to any SWAIG call.

swaig_set_global_data
boolean
Default: true

Allows SWAIG functions to set global data that persists across function calls.

Input & DTMF​

Handle dual-tone multi-frequency (DTMF) input and configure input polling for integrating external data sources during conversations.

digit_terminators
string

DTMF digit, as a string, to signal the end of input (ex: "#")

input_poll_freq
integer
Default: 2000

Check for input function with check_for_input. Allowed values from 1,000-10,000 ms. Example use case: Feeding an inbound SMS to AI on a voice call, eg., for collecting an email address or other complex information.

Debug & Development​

Enable debugging tools, logging, and performance monitoring features to help developers troubleshoot and optimize their AI agent implementations.

audible_debug
boolean
Default: false

If true, the AI will announce the function that is being executed on the call.

audible_latency
boolean
Default: false

Announce latency information during the call for debugging purposes.

cache_mode
boolean
Default: false

Enable response caching to improve performance for repeated queries.

debug_webhook_level
integer
Default: 1

Enables debugging to the set URL. Allowed values from 0-2. Level 0 disables, 1 provides basic info, 2 provides verbose info.

debug_webhook_url
string

Each interaction between the AI and end user is posted in real time to the established URL. Authentication can also be set in the url in the format of username:password@url.

enable_accounting
boolean
Default: false

Enable usage accounting and tracking for billing and analytics purposes.

verbose_logs
boolean
Default: false

Enable verbose logging (developer mode only).