SWAIG.functions

An array of JSON objects to define functions that can be executed during the interaction with the AI.

Name	Type	Default	Description
`functions`Optional	`object[]`	-	An array of JSON objects that accept the `functions Parameters`.

functions Parameters

Parameter	Type	Default	Description
`description` Required	`string`	-	A description of the context and purpose of the function, to explain to the agent when to use it.
`function` Required	`string`	-	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.
`active` Optional	`boolean`	`true`	Whether the function is active.
`data_map`Optional	`object`	-	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.
`parameters` Optional	`object`	-	A JSON object that defines the expected user input parameters and their validation rules for the function.
`fillers` Optional	`object`	-	A JSON object defining the fillers that should be played when calling a `swaig function`. This helps the AI break silence between responses. The filler is played asynchronously during the function call.
`meta_data` Optional	`object`	-	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.
`meta_data_token` Optional	`string`	Set by SignalWire	Scoping token for `meta_data`. If not supplied, metadata will be scoped to function's `web_hook_url`.
`wait_file` Optional	`string`	-	A file to play while the function is running. `wait_file_loops` can specify the amount of times that files should continously play.
`wait_file_loops` Optional	`string` \| `integer`	-	The amount of times that `wait_file` should continuously play/loop.
`wait_for_fillers` Optional	`boolean`	`false`	Whether to wait for fillers to finish playing before continuing with the function.
`web_hook_url` Optional	`string`	-	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`. See Callback Parameters for details on the request body.
`purpose`	`string`	-	Deprecated. Use `description` instead.
`argument`	`object`	-	Deprecated. Use `parameters` instead.

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

Function Name	Purpose
`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.

Diagram examples

SWML Examples

Using SWAIG Functions

YAML
JSON

version: 1.0.0
sections:
  main:
    - ai:
        post_prompt_url: "https://example.com/my-api"
        prompt:
          text: |
            You are a helpful assistant that can provide information to users about a destination.
            At the start of the conversation, always ask the user for their name.
            You can use the appropriate function to get the phone number, address,
            or weather information.
        post_prompt:
          text: "Summarize the conversation."
        SWAIG:
          includes:
            - functions:
                - get_phone_number
                - get_address
              url: https://example.com/functions
              user: me
              pass: secret
          defaults:
            web_hook_url: https://example.com/my-webhook
            web_hook_auth_user: me
            web_hook_auth_pass: secret
          functions:
            - function: get_weather
              description: To determine what the current weather is in a provided location.
              parameters:
                properties:
                  location:
                    type: string
                    description: The name of the city to find the weather from.
                type: object
            - function: summarize_conversation
              description: Summarize the conversation.
              parameters:
                properties:
                  name:
                    type: string
                    description: The name of the user.

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "ai": {
          "post_prompt_url": "https://example.com/my-api",
          "prompt": {
            "text": "You are a helpful assistant that can provide information to users about a destination.\nAt the start of the conversation, always ask the user for their name.\nYou can use the appropriate function to get the phone number, address,\nor weather information.\n"
          },
          "post_prompt": {
            "text": "Summarize the conversation."
          },
          "SWAIG": {
            "includes": [
              {
                "functions": [
                  "get_phone_number",
                  "get_address"
                ],
                "url": "https://example.com/functions",
                "user": "me",
                "pass": "secret"
              }
            ],
            "defaults": {
              "web_hook_url": "https://example.com/my-webhook",
              "web_hook_auth_user": "me",
              "web_hook_auth_pass": "secret"
            },
            "functions": [
              {
                "function": "get_weather",
                "description": "To determine what the current weather is in a provided location.",
                "parameters": {
                  "properties": {
                    "location": {
                      "type": "string",
                      "description": "The name of the city to find the weather from."
                    }
                  },
                  "type": "object"
                }
              },
              {
                "function": "summarize_conversation",
                "description": "Summarize the conversation.",
                "parameters": {
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "The name of the user."
                    }
                  }
                }
              }
            ]
          }
        }
      }
    ]
  }
}

functions Parameters​

Reserved Functions​

List of Reserved Functions​

Diagram examples​

SWML Examples​

Using SWAIG Functions​