functions
An array of JSON objects to define functions that can be executed during the interaction with the Amazon Bedrock agent.
Properties
SWAIG.functions
An array of JSON objects that accept the following properties.
functions[].description
A description of the context and purpose of the function, to explain to the agent when to use it.
functions[].function
A unique name for the function. This can be any user-defined string or can reference a reserved function. Reserved functoins are SignalWire functions that will be executed at certain points in the conversation. To learn more about reserved functions, see Reserved Functions.
functions[].active
Whether the function is active.
functions[].data_map
An object containing properties to process or validate the input, perform actions based on the input, or connect to external APIs or services in a serverless fashion.
See data_map for additional details.
functions[].parameters
A JSON object that defines the expected user input parameters and their validation rules for the function.
See parameters for additional details.
functions[].meta_data
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.
functions[].meta_data_token
Scoping token for meta_data. If not supplied, metadata will be scoped to function’s web_hook_url.
functions[].web_hook_url
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.
Tool webhook
When the agent calls one of your SWAIG functions, the platform sends an HTTP POST to that function’s
web_hook_url (or the SWAIG defaults.web_hook_url). Your endpoint runs the function and returns a JSON
object with a response string (the result the agent reads next) and, optionally, an action — a single
object or an array — telling the agent what to do.
Request
The ID of the AI session on the call. Matches call_id for Bedrock agents.
The name of your Bedrock application. Defaults to bedrock.
The agent's current global_data. Alongside anything you seeded, the session adds
caller_id_name and caller_id_number when the call carries them.
The content type of the request body. Always text/json.
How the body is delivered. Always agent.function for a function call.
The kind of conversation the agent is running. Always voice.
What the request is asking of you. Always fetch_conversation for a function call; the
end-of-call conversation report sends post_conversation instead.
The token that scopes meta_data. This is the meta_data_token you set on the function, or an
MD5 of the function's name when you did not set one.
Metadata scoped to meta_data_token. An empty object when the function has none yet.
When the call was answered, as a Unix timestamp in microseconds. 0 when it never was.
When the call ended, as a Unix timestamp in microseconds. 0 while the call is still up.
Per-response performance metrics for the session so far. Included once the agent has any.
This payload differs from the one an ai agent sends. content_type
is text/json rather than text/swaig, argument carries no substituted value, and there is no
version, description, or argument_desc. The caller’s number arrives as caller_id (and as
caller_id_number when the call has a caller profile) rather than caller_id_num.
Write your handler against this list, not the ai one.
See the Amazon Bedrock SWAIG tool webhook webhook page for the full field reference.
Reply
Return a JSON object with a response key and an optional action key. The response is the text
the agent reads next, and action carries SWML-compatible objects that change what the call does next.
response
Static text that will be added to the AI agent’s context.
action
A list of SWML-compatible objects that are executed upon the execution of a SWAIG function.
action[].SWML
A SWML object to be executed. By default it runs inline and the agent resumes the conversation
afterward. Pair it with a sibling action[].transfer set to true to hand the call off to that
SWML instead and end the agent.
action[].transfer
Use alongside a sibling action[].SWML payload in the same action object. When true, ends the
agent and hard-transfers the call to that SWML. When omitted or false, the SWML executes inline
and the agent continues afterward.
Bedrock agents accept only this boolean form. The object form that transfers to a named destination
is specific to ai agents.
action[].set_global_data
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.
action[].set_meta_data
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.
action[].unset_global_data
The key of the global data to unset from the global_data, or an array of keys to
unset several at once.
action[].unset_meta_data
The key of the metadata to unset from the meta_data, or an array of keys to unset
several at once.
Bedrock agents accept a smaller set of actions than ai agents.
The six above are the whole list: there is no say, stop, hangup, hold, toggle_functions,
context_switch, change_context, change_step, user_input, playback_bg, or stop_playback_bg.
An unrecognized key in action is ignored rather than reported as an error, so a payload written for
an ai agent fails quietly here.
Reserved Functions
Reserved functions are special SignalWire functions that are automatically triggered at specific points during a conversation. You define them just like any other SWAIG function, but their names correspond to built-in logic on the SignalWire platform, allowing them to perform specific actions at the appropriate time.
Function name conflicts
Do not use reserved function names for your own SWAIG functions unless you want to use the reserved function’s built-in behavior. Otherwise, your function may not work as expected.
List of Reserved Functions
start_hook
Triggered when the call is answered. Sends the set properties of the function to the defined web_hook_url.
stop_hook
Triggered when the call is ended. Sends the set properties of the function to the defined web_hook_url.
summarize_conversation
Triggered when the call is ended. The post_prompt must be defined for this function to be triggered. Provides a summary of the conversation and any set properties to the defined web_hook_url.
Where are my function properties?
If the AI is not returning the properties you set in your SWAIG function, it may be because a reserved function was triggered before those properties were available. To ensure your function receives all necessary information, make sure the AI has access to the required property values before the reserved function is called. Any property missing at the time the reserved function runs will not be included in the data sent back.