defaults.web_hook_url

The function specific URL that the user defines to which to send status callbacks and reports.

Name	Type	Default	Description
`web_hook_url`Optional	`string`	-	The URL to send status callbacks and reports to. Authentication can also be set in the url in the format of `username:password@url`. See Callback Parameters for details on the request body.

Callback Request for web_hook_url

SignalWire will make a request to the web_hook_url of a SWAIG function with the following parameters:

Name	Type	Description
`content_type`	`string`	Type of content. The value will be `text/swaig`.
`app_name`	`string`	Name of the application that originated the request.
`function`	`string`	Name of the function that was invoked.
`meta_data`	`object`	A JSON object containing any user metadata, as a key-value map.
`SWMLVars`	`object`	A collection of variables related to SWML.
`purpose`	`string`	The purpose of the function being invoked. The value will be the `functions.purpose` value you provided in the SWML Function parameters.
`argument_desc`	`string` \| `object`	The description of the argument being passed. This value comes from the argument you provided in the SWML Function parameters.
`argument`	`object`	The argument the AI agent is providing to the function. The object contains the three following fields.
`argument.parsed`	`object`	If a JSON object is detected within the argument, it is parsed and provided here.
`argument.raw`	`string`	The raw argument provided by the AI agent.
`argument.substituted`	`string`	The argument provided by the AI agent, excluding any JSON.
`version`	`string`	Version number.

Webhook request example

Below is a json example of the callback request that is sent to the web_hook_url:

{
  "app_name": "swml app",
  "global_data": {
    "caller_id_name": "",
    "caller_id_number": "sip:guest-246dd851-ba60-4762-b0c8-edfe22bc5344@46e10b6d-e5d6-421f-b6b3-e2e22b8934ed.call.signalwire.com;context=guest"
  },
  "project_id": "46e10b6d-e5d6-421f-b6b3-e2e22b8934ed",
  "space_id": "5bb2200d-3662-4f4d-8a8b-d7806946711c",
  "caller_id_name": "",
  "caller_id_num": "sip:guest-246dd851-ba60-4762-b0c8-edfe22bc5344@46e10b6d-e5d6-421f-b6b3-e2e22b8934ed.call.signalwire.com;context=guest",
  "channel_active": true,
  "channel_offhook": true,
  "channel_ready": true,
  "content_type": "text/swaig",
  "version": "2.0",
  "content_disposition": "SWAIG Function",
  "function": "get_weather",
  "argument": {
    "parsed": [
      {
        "city": "Tulsa",
        "state": "Oklahoma"
      }
    ],
    "raw": "{\"city\":\"Tulsa\",\"state\":\"Oklahoma\"}"
  },
  "call_id": "6e0f2f68-f600-4228-ab27-3dfba2b75da7",
  "ai_session_id": "9af20f15-7051-4496-a48a-6e712f22daa5",
  "argument_desc": {
    "properties": {
      "city": {
        "description": "Name of the city",
        "type": "string"
      },
      "country": {
        "description": "Name of the country",
        "type": "string"
      },
      "state": {
        "description": "Name of the state",
        "type": "string"
      }
    },
    "required": [],
    "type": "object"
  },
  "purpose": "Get weather with sarcasm"
}

Webhook response

When a SWAIG function is executed, the functions expects the user to respond with a JSON object that contains a response key and an optional action key. This request response is used to provide the LLM with a new prompt response via the response key and to execute SWML-compatible objects that will perform new dialplan actions via the action key.

Name	Type	Default	Description
`response`Required	`string`	-	Static text that will be added to the AI agent's context.
`action`Optional	`object[]`	-	A list of SWML-compatible objects that are executed upon the execution of a SWAIG function.

List of valid actions

Name	Type	Default	Description
`SWML`	`object`	-	A SWML object to be executed.
`say`	`string`	-	A message to be spoken by the AI agent.
`stop`	`boolean`	-	Whether to stop the conversation.
`toggle_functions`	`object[]`	-	Whether to toggle the functions on or off.
`toggle_functions.active`	`boolean`	`true`	Whether to activate or deactivate the functions.
`toggle_functions.function`	`object[]`	-	A list of functions to toggle.
`set_global_data`	`object`	-	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.
`set_meta_data`	`object`	-	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.
`unset_global_data`	`string` \| `object`	-	The key of the global data to unset from the `global_data`. You can also reset the `global_data` by passing in a new object.
`unset_meta_data`	`string` \| `object`	-	The key of the metadata to unset from the `meta_data`. You can also reset the `meta_data` by passing in a new object.
`playback_bg`	`object`	-	A JSON object containing the audio file to play.
`playback_bg.file`	`string`	-	URL or filepath of the audio file to play. Authentication can also be set in the url in the format of `username:password@url`.
`playback_bg.wait`	`boolean`	`false`	Whether to wait for the audio file to finish playing before continuing.
`stop_playback_bg`	`boolean`	-	Whether to stop the background audio file.
`user_input`	`string`	-	Used to inject text into the users queue as if they input the data themselves.
`context_switch`	`object`	-	A JSON object containing the context to switch to.
`context_switch.system_prompt`	`string`	-	The instructions to send to the agent.
`context_switch.consolidate`	`boolean`	`false`	Whether to consolidate the context.
`context_switch.user_prompt`	`string`	-	A string serving as simulated user input for the AI Agent. During a `context_switch` in the AI's prompt, the `user_prompt` offers the AI pre-established context or guidance.

Webhook response example

{
  "response": "Oh wow, it's 82.0°F in Tulsa. Bet you didn't see that coming! Humidity at 38%. Your hair is going to love this! Wind speed is 2.2 mph. Hold onto your hats, or don't, I'm not your mother! Looks like Sunny. Guess you'll survive another day.",
  "action": [
    {
      "set_meta_data": {
        "temperature": 82.0,
        "humidity": 38,
        "wind_speed": 2.2,
        "weather": "Sunny"
      }
    },
    {
      "SWML": {
        "version": "1.0.0",
        "sections": {
          "main": [
            {
              "play": {
                "url": "https://example.com/twister.mp3"
              }
            }
          ]
        }
      }
    }
  ]
}

Variables

ai_result: (out) success | failed
return_value: (out) success | failed

Callback Request for web_hook_url​

Webhook request example​

Webhook response​

List of valid actions​

Webhook response example​

Variables​