Skip to main content
Get startedGuidesTechnical Reference

defaults.web_hook_url

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

defaults.web_hook_url
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.

Webhook response​

When a SWAIG function is executed, the function 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.

response
stringrequired

Static text that will be added to the AI agent's context.

action
object[]

A list of SWML-compatible objects that are executed upon the execution of a SWAIG function.

See list of valid actions for additional details.

List of valid actions​

action[].SWML
object

A SWML object to be executed.

action[].say
string

A message to be spoken by the AI agent.

action[].stop
boolean

Whether to stop the conversation.

action[].toggle_functions
object[]

Whether to toggle the functions on or off.

See toggle_functions for additional details.

toggle_functions[].active
boolean
Default: true

Whether to activate or deactivate the functions.

toggle_functions[].function
object[]

A list of functions to toggle.

action[].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.

action[].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.

See set_meta_data for additional details.

action[].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.

action[].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.

action[].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
Default: false

Whether to wait for the audio file to finish playing before continuing.

action[].stop_playback_bg
boolean

Whether to stop the background audio file.

action[].user_input
string

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

action[].context_switch
object

A JSON object containing the context to switch to.

See context_switch for additional details.

context_switch.system_prompt
string

The instructions to send to the agent.

context_switch.consolidate
boolean
Default: 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"
              }
            }
          ]
        }
      }
    }
  ]
}

Callback Request for web_hook_url​

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

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"
}

Variables​

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