functions

A description of the context and purpose of the function, to explain to the agent when to use it. A function with neither description nor the deprecated purpose isn’t added to the agent.

A unique name for the function. This can be any user-defined string or can reference a reserved function. Reserved functions are SignalWire functions that will be executed at certain points in the conversation. To learn more about reserved functions, see Reserved Functions.

Whether the function is active.

An object that processes function inputs and executes operations through expressions, webhooks, or direct output. Properties are evaluated in strict priority order: (1) expressions, (2) webhooks, (3) output. Evaluation stops at the first property that returns a valid output result, similar to a return statement in a function.

See data_map for additional details.

A JSON object that defines the expected user input parameters and their validation rules for the function.

See parameters for additional details.

An object containing language-specific arrays of filler phrases that are played when calling a SWAIG function. These fillers help break silence between responses and are played asynchronously during the function call. Each key is a language code and each value is an array of filler phrases selected from randomly.

Skips the top-level fillers specified in ai.languages (which includes speech_fillers and function_fillers). When set to true, only function-specific fillers defined directly on SWAIG.functions.fillers will play.

A powerful and flexible environmental variable which can accept arbitrary data that is set initially in the SWML script or from the SWML set_meta_data action. This data can be referenced locally to the function. All contained information can be accessed and expanded within the prompt - for example, by using a template string.

Scoping token for meta_data. If not supplied, metadata will be scoped to function’s web_hook_url.

A file to play while the function is running. wait_file_loops can specify the amount of times that files should continously play.

The amount of times that wait_file should continuously play/loop.

Whether to wait for fillers to finish playing before continuing with the function.

Function-specific URL to send status callbacks and reports to. Takes precedence over a default setting. Authentication can also be set in the url in the format of username:password@url. Credentials embedded in the URL take precedence over web_hook_auth_user and web_hook_auth_password.

Username for basic auth on this function’s webhook. Falls back to defaults.web_hook_auth_user.

Password for basic auth on this function’s webhook. Falls back to defaults.web_hook_auth_password.

Semantic gates: 1 to 8 yes/no questions about the call that must all pass before the function runs. When any gate fails, the function doesn’t run, and the AI gets the first failing gate’s on_fail response instead. A gated function needs a description and a web_hook_url (its own or from SWAIG.defaults) or a data_map. If any gate is invalid, the function isn’t added to the agent at all.

See gates for additional details.

What the agent says while the function’s gates are checked, shaped like fillers. Ignored on a function without gates.

For a gated function without gate_fillers, whether its fillers play as soon as the AI calls it, during the gate check (true), or only after the gates pass (false). Set it to false when the function’s fillers announce the action (“OK, cancelling your account now”), so the caller doesn’t hear them before a gate blocks it. When unset, the function inherits SWAIG.defaults.fillers_at_gates, which is true unless you change it.

How many of the caller’s newest video frames your web_hook_url receives with the function call, as visual_input in the request body: true is 1, a whole number from 0 to 5, and false or 0 is none. On a gated function, the frames are taken when its gates are checked, never later, and a blocked call sends none. Ignored on a data_map function.

Deprecated. Use description instead. When a function sets both, purpose is used.

Deprecated. Use parameters instead.

Password for basic auth on this function’s webhook. Deprecated — use web_hook_auth_password instead. The alias is used only when web_hook_auth_password is not set.

A SWML object to be executed.

A message to be spoken by the AI agent.

Whether to stop the conversation.

Whether to hang up the call. When set to true, the call will be terminated after the AI agent finishes speaking.

Places the caller on hold while playing hold music (configured via the params.hold_music parameter). During hold, speech detection is paused and the AI agent will not respond to the caller.

The value specifies the hold timeout in seconds. Can be:

• An integer (e.g., 120 for 120 seconds)
• An object with timeout, and optionally step and timeout_step

Default timeout is 300 seconds (5 minutes). Maximum timeout is 900 seconds (15 minutes).

The name of the context to switch to. The context must be defined in the AI’s prompt.contexts configuration. This action triggers an immediate context switch during the execution of a SWAIG function.

Visit the contexts documentation for details on defining contexts.

The name of the step to switch to. The step must be defined in prompt.contexts.{context_name}.steps for the current context. This action triggers an immediate step transition during the execution of a SWAIG function.

Visit the steps documentation for details on defining steps.

An array of objects to toggle SWAIG functions on or off during the conversation. Each object identifies a function by name and sets its active state. A function can only toggle functions that have the same meta_data_token as itself.

See toggle_functions for additional details.

A JSON object containing any global data, as a key-value map. This action sets the data in the global_data to be globally referenced.

A JSON object containing any metadata, as a key-value map. This action sets the data in the meta_data to be referenced locally in the function.

See set_meta_data for additional details.

The key to remove from global_data, or an array of keys to remove.

The key to remove from the function’s meta_data, or an array of keys to remove.

A JSON object containing the audio file to play.

Stops the background audio file. The action runs whenever the key is present, whatever its value, so false also stops playback. Leave the key out to keep playing.

Used to inject text into the users queue as if they input the data themselves.

Replaces the agent’s instructions mid-conversation. You can use variables in system_prompt, user_prompt, system_pom, and user_pom. In a data_map function they’re expanded along with the rest of the output; in a reply from your web_hook_url, they’re expanded when the action runs. Either way they’re expanded only once, so a value that itself contains ${...} is left as it is.

See context_switch for additional details.

Changes the AI model’s settings for the rest of the conversation, as a key-value map. Only settings the selected model supports are applied. Requires params.swaig_allow_settings, which is on by default. The new map replaces the current settings: any setting you leave out, including one set on prompt, returns to the model’s default.

Sends a custom event to the client connected to the call, with this object as its payload, like the user_event method.

Transfer the call to a new destination. Accepts two forms depending on whether it accompanies a sibling action[].SWML payload:

• Boolean — use alongside a sibling action[].SWML payload in the same action object. When true, ends the AI session and hard-transfers the call to that SWML. When omitted or false, the SWML executes inline and the AI session continues afterward.
• Object or string — use on its own, without SWML, to end the AI session and transfer the call to the destination configured with the fields below. A string is shorthand for transfer.dest.