Execute SWML from a function

SWAIG functions allow you to execute SWML from within itself. This allows you to create a function that can be used to execute a specific SWML block, that lives outside the AI language model. The benefit of this is you can get more granular control over the execution of what happens next after the function is triggered while also getting the additional benefits of SignalWire’s APIs.

For this example, we will create an AI and who will help assist with transferring the call. The AI will ask the user for a destination to transfer to, and then execute a function to send an SMS to notify the destination that they have a call coming in, and then transfer the call.

Enabling SWML execution

The first important step is to make sure our AI is capable of executing SWML in its functions. In the ai.params, you will need to set the parameter swaig_allow_swml to true, to allow SWML execution:

1 {
2   "params": {
3     "swaig_allow_swml": true
4   }
5 }

Data map example

In this example, we are using the data_map to execute SWML in the data_map.expressions.output.action.

Creating the Function

We will create a function that will send an SMS to the destination number, and then transfer the call to the destination number.

1 {
2   "SWAIG": {
3     "functions": [
4       {
5         "function": "transfer",
6         "description": "Get input from user and transfer to a destination department",
7         "parameters": {
8           "type": "object",
9           "properties": {
10             "destination": {
11               "type": "string",
12               "description": "The destination to transfer to"
13             }
14           }
15         },
16         "data_map": {
17           "expressions": [
18             {
19               "string": "${args.destination}",
20               "pattern": ".*",
21               "output": {
22                 "response": "Transferring call.",
23                 "action": [
24                   {
25                     "transfer": true,
26                     "SWML": {
27                       "sections": {
28                         "main": [
29                           {
30                             "send_sms": {
31                               "to_number": "+1XXXXXXXXXX",
32                               "from_number": "+1YYYYYYYYYY",
33                               "body": "Call coming from ${caller_id_num}"
34                             }
35                           },
36                           {
37                             "connect": {
38                               "to": "+1XXXXXXXXXX"
39                             }
40                           }
41                         ]
42                       }
43                     }
44                   },
45                   { "stop": true }
46                 ]
47               }
48             }
49           ]
50         }
51       }
52     ]
53   }
54 }

When passing a SWML object that includes a connect (or other method that transfers the call) in output.action[], your script must be JSON, and "transfer": true, must be included before the SWML in the same action object. Refer to the example above.

SWML Execution

We are using the SWML action to execute the SWML block that will send the SMS using the send_sms method and then connect the call to the destination number using the connect method.

1 {
2   "action": [
3     {
4       "transfer": true,
5       "SWML": {
6         "sections": {
7           "main": [
8             {
9               "send_sms": {
10                 "to_number": "+1XXXXXXXXXX",
11                 "from_number": "+1YYYYYYYYYY",
12                 "body": "Call coming from ${caller_id_num}"
13               }
14             },
15             {
16               "connect": {
17                 "to": "+1XXXXXXXXXX"
18               }
19             }
20           ]
21         }
22       }
23     }
24   ]
25 }

Full Example

1 {
2   "sections": {
3     "main": [
4       {
5         "ai": {
6           "prompt": {
7             "text": "Your name is Frank. You help the user with transferring calls.\n## Handling The User\n- You are asked to transfer a call.\n- You ask for the destination.\n- You use the 'transfer' function to transfer the call."
8           },
9           "post_prompt_url": "https://example.com/post_prompt_url",
10           "params": {
11             "swaig_allow_swml": true
12           },
13           "SWAIG": {
14             "functions": [
15               {
16                 "function": "transfer",
17                 "description": "Get input from user and transfer to a destination department",
18                 "parameters": {
19                   "type": "object",
20                   "properties": {
21                     "destination": {
22                       "type": "string",
23                       "description": "The destination to transfer to"
24                     }
25                   }
26                 },
27                 "data_map": {
28                   "expressions": [
29                     {
30                       "string": "${args.destination}",
31                       "pattern": ".*",
32                       "output": {
33                         "response": "Transferring call.",
34                         "action": [
35                           {
36                             "transfer": true,
37                             "SWML": {
38                               "sections": {
39                                 "main": [
40                                   {
41                                     "send_sms": {
42                                       "to_number": "+1XXXXXXXXXX",
43                                       "from_number": "+1YYYYYYYYYY",
44                                       "body": "Call coming from ${caller_id_num}"
45                                     }
46                                   },
47                                   {
48                                     "connect": {
49                                       "to": "+1XXXXXXXXXX"
50                                     }
51                                   }
52                                 ]
53                               }
54                             }
55                           },
56                           { "stop": true }
57                         ]
58                       }
59                     }
60                   ]
61                 }
62               }
63             ]
64           },
65           "hints": ["transfer"]
66         }
67       }
68     ]
69   }
70 }

Webhook example

In this example, we are using the function.web_hook_url to execute SWML.

Creating the Function

We will create a function that will take the input from the user as an argument (destination) and then make a request to the function.web_hook_url.

1 {
2   "SWAIG": {
3     "functions": [
4       {
5         "function": "transfer",
6         "web_hook_url": "https://example.com/transfer",
7         "description": "Get input from user and transfer to a destination department",
8         "parameters": {
9           "type": "object",
10           "properties": {
11             "destination": {
12               "type": "string",
13               "description": "The destination to transfer to"
14             }
15           }
16         }
17       }
18     ]
19   }
20 }

SWML Execution

When executing SWML while utilizing a function.web_hook_url, you will need to provide a response from the function.web_hook_url that contains the action key. In this action key you will need to provide the SWML block that you want to execute.

Format:

1 {
2   "response": "The response to the AI",
3   "action": ["The SWML block to execute"]
4 }

Webhook Response Example:

We are using the SWML action to execute the SWML block that will send the SMS using the send_sms method and then connect the call to the destination number using the connect method.

1 {
2   "response": "Transferring call.",
3   "action": [
4     {
5       "transfer": true,
6       "SWML": {
7         "sections": {
8           "main": [
9             {
10               "send_sms": {
11                 "to_number": "+1XXXXXXXXXX",
12                 "from_number": "+1YYYYYYYYYY",
13                 "body": "Call coming from ${caller_id_num}"
14               }
15             },
16             {
17               "connect": {
18                 "to": "+1XXXXXXXXXX"
19               }
20             }
21           ]
22         }
23       }
24     }
25   ]
26 }

Full Example

1 {
2   "sections": {
3     "main": [
4       {
5         "ai": {
6           "prompt": {
7             "text": "Your name is Frank. You help the user with transferring calls.\n## Handling The User\n- You are asked to transfer a call.\n- You ask for the destination.\n- You use the 'transfer' function to transfer the call."
8           },
9           "post_prompt_url": "https://example.com/post_prompt_url",
10           "params": {
11             "swaig_allow_swml": true
12           },
13           "SWAIG": {
14             "functions": [
15               {
16                 "function": "transfer",
17                 "web_hook_url": "https://example.com/transfer",
18                 "description": "Get input from user and transfer to a destination department",
19                 "parameters": {
20                   "type": "object",
21                   "properties": {
22                     "destination": {
23                       "type": "string",
24                       "description": "The destination to transfer to"
25                     }
26                   }
27                 }
28               }
29             ]
30           },
31           "hints": ["transfer"]
32         }
33       }
34     ]
35   }
36 }

Enabling SWML execution

1 {
2   "params": {
3     "swaig_allow_swml": true
4   }
5 }

Data map example

In this example, we are using the data_map to execute SWML in the data_map.expressions.output.action.

Creating the Function

We will create a function that will send an SMS to the destination number, and then transfer the call to the destination number.

1 {
2   "SWAIG": {
3     "functions": [
4       {
5         "function": "transfer",
6         "description": "Get input from user and transfer to a destination department",
7         "parameters": {
8           "type": "object",
9           "properties": {
10             "destination": {
11               "type": "string",
12               "description": "The destination to transfer to"
13             }
14           }
15         },
16         "data_map": {
17           "expressions": [
18             {
19               "string": "${args.destination}",
20               "pattern": ".*",
21               "output": {
22                 "response": "Transferring call.",
23                 "action": [
24                   {
25                     "transfer": true,
26                     "SWML": {
27                       "sections": {
28                         "main": [
29                           {
30                             "send_sms": {
31                               "to_number": "+1XXXXXXXXXX",
32                               "from_number": "+1YYYYYYYYYY",
33                               "body": "Call coming from ${caller_id_num}"
34                             }
35                           },
36                           {
37                             "connect": {
38                               "to": "+1XXXXXXXXXX"
39                             }
40                           }
41                         ]
42                       }
43                     }
44                   },
45                   { "stop": true }
46                 ]
47               }
48             }
49           ]
50         }
51       }
52     ]
53   }
54 }

SWML Execution

We are using the SWML action to execute the SWML block that will send the SMS using the send_sms method and then connect the call to the destination number using the connect method.

1 {
2   "action": [
3     {
4       "transfer": true,
5       "SWML": {
6         "sections": {
7           "main": [
8             {
9               "send_sms": {
10                 "to_number": "+1XXXXXXXXXX",
11                 "from_number": "+1YYYYYYYYYY",
12                 "body": "Call coming from ${caller_id_num}"
13               }
14             },
15             {
16               "connect": {
17                 "to": "+1XXXXXXXXXX"
18               }
19             }
20           ]
21         }
22       }
23     }
24   ]
25 }

Full Example

1 {
2   "sections": {
3     "main": [
4       {
5         "ai": {
6           "prompt": {
7             "text": "Your name is Frank. You help the user with transferring calls.\n## Handling The User\n- You are asked to transfer a call.\n- You ask for the destination.\n- You use the 'transfer' function to transfer the call."
8           },
9           "post_prompt_url": "https://example.com/post_prompt_url",
10           "params": {
11             "swaig_allow_swml": true
12           },
13           "SWAIG": {
14             "functions": [
15               {
16                 "function": "transfer",
17                 "description": "Get input from user and transfer to a destination department",
18                 "parameters": {
19                   "type": "object",
20                   "properties": {
21                     "destination": {
22                       "type": "string",
23                       "description": "The destination to transfer to"
24                     }
25                   }
26                 },
27                 "data_map": {
28                   "expressions": [
29                     {
30                       "string": "${args.destination}",
31                       "pattern": ".*",
32                       "output": {
33                         "response": "Transferring call.",
34                         "action": [
35                           {
36                             "transfer": true,
37                             "SWML": {
38                               "sections": {
39                                 "main": [
40                                   {
41                                     "send_sms": {
42                                       "to_number": "+1XXXXXXXXXX",
43                                       "from_number": "+1YYYYYYYYYY",
44                                       "body": "Call coming from ${caller_id_num}"
45                                     }
46                                   },
47                                   {
48                                     "connect": {
49                                       "to": "+1XXXXXXXXXX"
50                                     }
51                                   }
52                                 ]
53                               }
54                             }
55                           },
56                           { "stop": true }
57                         ]
58                       }
59                     }
60                   ]
61                 }
62               }
63             ]
64           },
65           "hints": ["transfer"]
66         }
67       }
68     ]
69   }
70 }

Webhook example

In this example, we are using the function.web_hook_url to execute SWML.

Creating the Function

We will create a function that will take the input from the user as an argument (destination) and then make a request to the function.web_hook_url.

1 {
2   "SWAIG": {
3     "functions": [
4       {
5         "function": "transfer",
6         "web_hook_url": "https://example.com/transfer",
7         "description": "Get input from user and transfer to a destination department",
8         "parameters": {
9           "type": "object",
10           "properties": {
11             "destination": {
12               "type": "string",
13               "description": "The destination to transfer to"
14             }
15           }
16         }
17       }
18     ]
19   }
20 }

SWML Execution

Format:

1 {
2   "response": "The response to the AI",
3   "action": ["The SWML block to execute"]
4 }

Webhook Response Example:

We are using the SWML action to execute the SWML block that will send the SMS using the send_sms method and then connect the call to the destination number using the connect method.

1 {
2   "response": "Transferring call.",
3   "action": [
4     {
5       "transfer": true,
6       "SWML": {
7         "sections": {
8           "main": [
9             {
10               "send_sms": {
11                 "to_number": "+1XXXXXXXXXX",
12                 "from_number": "+1YYYYYYYYYY",
13                 "body": "Call coming from ${caller_id_num}"
14               }
15             },
16             {
17               "connect": {
18                 "to": "+1XXXXXXXXXX"
19               }
20             }
21           ]
22         }
23       }
24     }
25   ]
26 }

Full Example

1 {
2   "sections": {
3     "main": [
4       {
5         "ai": {
6           "prompt": {
7             "text": "Your name is Frank. You help the user with transferring calls.\n## Handling The User\n- You are asked to transfer a call.\n- You ask for the destination.\n- You use the 'transfer' function to transfer the call."
8           },
9           "post_prompt_url": "https://example.com/post_prompt_url",
10           "params": {
11             "swaig_allow_swml": true
12           },
13           "SWAIG": {
14             "functions": [
15               {
16                 "function": "transfer",
17                 "web_hook_url": "https://example.com/transfer",
18                 "description": "Get input from user and transfer to a destination department",
19                 "parameters": {
20                   "type": "object",
21                   "properties": {
22                     "destination": {
23                       "type": "string",
24                       "description": "The destination to transfer to"
25                     }
26                   }
27                 }
28               }
29             ]
30           },
31           "hints": ["transfer"]
32         }
33       }
34     ]
35   }
36 }

1	{
2	"SWAIG": {
3	"functions": [
4	{
5	"function": "transfer",
6	"description": "Get input from user and transfer to a destination department",
7	"parameters": {
8	"type": "object",
9	"properties": {
10	"destination": {
11	"type": "string",
12	"description": "The destination to transfer to"
13	}
14	}
15	},
16	"data_map": {
17	"expressions": [
18	{
19	"string": "${args.destination}",
20	"pattern": ".*",
21	"output": {
22	"response": "Transferring call.",
23	"action": [
24	{
25	"transfer": true,
26	"SWML": {
27	"sections": {
28	"main": [
29	{
30	"send_sms": {
31	"to_number": "+1XXXXXXXXXX",
32	"from_number": "+1YYYYYYYYYY",
33	"body": "Call coming from ${caller_id_num}"
34	}
35	},
36	{
37	"connect": {
38	"to": "+1XXXXXXXXXX"
39	}
40	}
41	]
42	}
43	}
44	},
45	{ "stop": true }
46	]
47	}
48	}
49	]
50	}
51	}
52	]
53	}
54	}

1	{
2	"sections": {
3	"main": [
4	{
5	"ai": {
6	"prompt": {
7	"text": "Your name is Frank. You help the user with transferring calls.\n## Handling The User\n- You are asked to transfer a call.\n- You ask for the destination.\n- You use the 'transfer' function to transfer the call."
8	},
9	"post_prompt_url": "https://example.com/post_prompt_url",
10	"params": {
11	"swaig_allow_swml": true
12	},
13	"SWAIG": {
14	"functions": [
15	{
16	"function": "transfer",
17	"description": "Get input from user and transfer to a destination department",
18	"parameters": {
19	"type": "object",
20	"properties": {
21	"destination": {
22	"type": "string",
23	"description": "The destination to transfer to"
24	}
25	}
26	},
27	"data_map": {
28	"expressions": [
29	{
30	"string": "${args.destination}",
31	"pattern": ".*",
32	"output": {
33	"response": "Transferring call.",
34	"action": [
35	{
36	"transfer": true,
37	"SWML": {
38	"sections": {
39	"main": [
40	{
41	"send_sms": {
42	"to_number": "+1XXXXXXXXXX",
43	"from_number": "+1YYYYYYYYYY",
44	"body": "Call coming from ${caller_id_num}"
45	}
46	},
47	{
48	"connect": {
49	"to": "+1XXXXXXXXXX"
50	}
51	}
52	]
53	}
54	}
55	},
56	{ "stop": true }
57	]
58	}
59	}
60	]
61	}
62	}
63	]
64	},
65	"hints": ["transfer"]
66	}
67	}
68	]
69	}
70	}

1	{
2	"response": "The response to the AI",
3	"action": ["The SWML block to execute"]
4	}