Skip to content

API Field conversion in SWML AI section #587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 13 commits into
base: main
Choose a base branch
from
Open

API Field conversion in SWML AI section #587

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
8c9d817
Updated Parameters for SWML AI section to utilize API Fields instead …
Manny-r31 Oct 21, 2025
8833e70
Merge branch 'main' into Manny/SWML-AI-API-Fields
Manny-r31 Oct 27, 2025
3829d5e
Merge branch 'main' into Manny/SWML-AI-API-Fields
Manny-r31 Oct 27, 2025
0eb7bc8
Table conversion to API fields for all remaining params
Manny-r31 Oct 27, 2025
7823495
fixed links
Manny-r31 Oct 27, 2025
7610a6e
Merge branch 'main' into Manny/SWML-AI-API-Fields
Manny-r31 Oct 28, 2025
64544a2
Merge branch 'main' into Manny/SWML-AI-API-Fields
Devon-White Oct 30, 2025
24684f2
API Field formatting fixes
Manny-r31 Oct 31, 2025
389e05f
Merge branch 'Manny/SWML-AI-API-Fields' of https://github.com/signalw…
Manny-r31 Oct 31, 2025
b68ac85
Merge branch 'main' into Manny/SWML-AI-API-Fields
Manny-r31 Oct 31, 2025
b13db17
Conversions for rest of SWML params
Manny-r31 Oct 31, 2025
f866323
Merge branch 'main' into Manny/SWML-AI-API-Fields
Manny-r31 Nov 6, 2025
a5ab8bc
Merge branch 'main' into Manny/SWML-AI-API-Fields
Manny-r31 Nov 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 151 additions & 26 deletions website/docs/main/swml/methods/_sharedtables/actions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import APIField from "@site/src/components/APIField";

[toggle_functions]: /swml/guides/ai/toggle_functions
[set_meta_data]: /swml/guides/ai/set_meta_data
[context_switch]: /swml/guides/ai/context_switch
Expand All @@ -8,36 +10,159 @@ When a SWAIG function is executed, the functions expects the user to respond wit
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`<span className="required-arg">Required</span> | `string` | - | Static text that will be added to the AI agent's context. |
| [`action`][actions]<span className="optional-arg">Optional</span> | `object[]` | - | A list of SWML-compatible objects that are executed upon the execution of a SWAIG function. |
<APIField
name="response"
type="string"
required={true}
>
Static text that will be added to the AI agent's context.
</APIField>

<APIField
name="action"
type="[object](#actions)[]"
>
A list of SWML-compatible objects that are executed upon the execution of a SWAIG function.
</APIField>

---

## List of valid actions {#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`][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`][parameters] to be globally referenced. |
| [`set_meta_data`][set_meta_data] | `object` | - | A JSON object containing any metadata, as a key-value map. This action sets the data in the [`meta_data`][parameters] to be referenced locally in the function. |
| `unset_global_data` | `string` \| `object` | - | The key of the global data to unset from the [`global_data`][parameters]. 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`][parameters]. 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`][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. |
<APIField
name="SWML"
type="object"
>
A SWML object to be executed.
</APIField>

<APIField
name="say"
type="string"
>
A message to be spoken by the AI agent.
</APIField>

<APIField
name="stop"
type="boolean"
>
Whether to stop the conversation.
</APIField>

<APIField
name="toggle_functions"
type="[object](/swml/guides/ai/toggle_functions)[]"
>
Whether to toggle the functions on or off.
</APIField>

<APIField
name="toggle_functions.active"
type="boolean"
default="true"
>
Whether to activate or deactivate the functions.
</APIField>

<APIField
name="toggle_functions.function"
type="object[]"
>
A list of functions to toggle.
</APIField>

<APIField
name="set_global_data"
type="object"
>
A JSON object containing any global data, as a key-value map. This action sets the data in the [`global_data`][parameters] to be globally referenced.
</APIField>

<APIField
name="set_meta_data"
type="[object](/swml/guides/ai/set_meta_data)"
>
A JSON object containing any metadata, as a key-value map. This action sets the data in the [`meta_data`][parameters] to be referenced locally in the function.
</APIField>

<APIField
name="unset_global_data"
type="string | object"
>
The key of the global data to unset from the [`global_data`][parameters]. You can also reset the `global_data` by passing in a new object.
</APIField>

<APIField
name="unset_meta_data"
type="string | object"
>
The key of the metadata to unset from the [`meta_data`][parameters]. You can also reset the `meta_data` by passing in a new object.
</APIField>

<APIField
name="playback_bg"
type="object"
>
A JSON object containing the audio file to play.
</APIField>

<APIField
name="playback_bg.file"
type="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`.
</APIField>

<APIField
name="playback_bg.wait"
type="boolean"
default="false"
>
Whether to wait for the audio file to finish playing before continuing.
</APIField>

<APIField
name="stop_playback_bg"
type="boolean"
>
Whether to stop the background audio file.
</APIField>

<APIField
name="user_input"
type="string"
>
Used to inject text into the users queue as if they input the data themselves.
</APIField>

<APIField
name="context_switch"
type="[object](/swml/guides/ai/context_switch)"
>
A JSON object containing the context to switch to.
</APIField>

<APIField
name="context_switch.system_prompt"
type="string"
>
The instructions to send to the agent.
</APIField>

<APIField
name="context_switch.consolidate"
type="boolean"
default="false"
>
Whether to consolidate the context.
</APIField>

<APIField
name="context_switch.user_prompt"
type="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.
</APIField>

{/*

Expand Down
103 changes: 88 additions & 15 deletions website/docs/main/swml/methods/_sharedtables/web_hook_url_.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,97 @@
import Actions from './actions.mdx';
import APIField from "@site/src/components/APIField";

[SWML Function parameters]: /swml/methods/ai/swaig/functions#parameters

## 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. |
<APIField
name="content_type"
type="string"
>
Type of content. The value will be `text/swaig`.
</APIField>

<APIField
name="app_name"
type="string"
>
Name of the application that originated the request.
</APIField>

<APIField
name="function"
type="string"
>
Name of the function that was invoked.
</APIField>

<APIField
name="meta_data"
type="object"
>
A JSON object containing any user metadata, as a key-value map.
</APIField>

<APIField
name="SWMLVars"
type="object"
>
A collection of variables related to SWML.
</APIField>

<APIField
name="purpose"
type="string"
>
The purpose of the function being invoked. The value will be the `functions.purpose` value you provided in the [SWML Function parameters].
</APIField>

<APIField
name="argument_desc"
type="string | object"
>
The description of the argument being passed. This value comes from the argument you provided in the [SWML Function parameters].
</APIField>

<APIField
name="argument"
type="object"
>
The argument the AI agent is providing to the function. The object contains the three following fields.
</APIField>

<APIField
name="argument.parsed"
type="object"
>
If a JSON object is detected within the argument, it is parsed and provided here.
</APIField>

<APIField
name="argument.raw"
type="string"
>
The raw argument provided by the AI agent.
</APIField>

<APIField
name="argument.substituted"
type="string"
>
The argument provided by the AI agent, excluding any JSON.
</APIField>

<APIField
name="version"
type="string"
>
Version number.
</APIField>

<br></br >
#### Webhook request example

Below is a json example of the callback request that is sent to the `web_hook_url`:
Expand Down Expand Up @@ -80,7 +151,9 @@ Below is a json example of the callback request that is sent to the `web_hook_ur

<Actions />

##### Webhook response example
<br></br >

#### Webhook response example

```json
{
Expand Down
Loading