Handle SWAIG function calls inline

Overview

The data_map object is a crucial component of SWAIG Functions in the ai SWML method. Data Maps are used to request, process, and transform incoming data, and trigger specific actions or responses, directly within the serverless context of your SWML Script.

In particular, the data_map object facilitates a full range of input processing, interfacing with external APIs, and state management. The capabilities and use cases described in this guide include:

• Expressions: Evaluate user input with powerful pattern matching
• Webhooks: Integrate with external APIs to fetch data or push updates
• Outputs:
  • Feed information back to the AI Agent with Responses
  • Comprehensively control the SWML Script and SWAIG function with Actions

This guide also explains how to utilize stored variables in the context of Data Maps.

Expressions

Expressions in data_map are used to match patterns in incoming data. They help identify specific pieces of data passed from the user while interacting with the AI agent and trigger actions or responses based on the expression match.

Expressions are particularly useful in scenarios where user inputs need to be dynamically evaluated and processed locally. By utilizing Perl Compatible Regular Expressions (PCRE), data_map can effectively parse and handle a wide variety of inputs, enabling flexible and powerful data processing within your SWML scripts. Multiple expressions can be stated inside the data_map.expressions field. These expressions are evaluated in the order they are stated until one of the expressions has a matching pattern.

Key points to note about expressions:

• Pattern Matching: The pattern field uses regular expressions to identify specific data patterns in the input, allowing for sophisticated and granular control over input data processing.
• Dynamic Value Assignment: The string field leverages placeholders to dynamically or statically set values based on the matched patterns, enabling real-time data processing.
• Conditional Actions and Responses: The output section defines the actions and responses that are conditionally triggered based on the expression match, allowing for highly customized behavior in response to user inputs.
• Local Processing: Expressions are capable of processing data locally within the SWML script. This removes the need to host a server to perform certain actions conditionally, based on user responses.

Example

1
{
2
  "data_map": {
3
    "expressions": [
4
      {
5
        "pattern": "\\w+",
6
        "string": "${meta_data.table.${lc:args.target}}",
7
        "output": {}
8
      },
9
      {
10
        "pattern": ".*",
11
        "string": "${args.target}",
12
        "output": {}
13
      }
14
    ]
15
  }
16
}

• Pattern Matching: The pattern field contains a Perl Compatible Regular Expressions (PCRE) to match specific data in the input.

  • In the example we have two expressions with different patterns. The \w+ pattern matches any word characters, and the .* pattern matches any character.
    • The \w+ pattern is used to match a specific target value, while the .* pattern is a catch-all for any input.

• String Field: The string field allows you to dynamically or statically set values based on the matched pattern.

  • In the example, ${meta_data.table.${lc:args.target}} fetches the target from the SWAIG.functions.<function>.meta_data field.

    1
    {
    2
      "meta_data": {
    3
        "table": {
    4
          "support": "+1XXXXXXXXXX",
    5
          "sales": "+1YYYYYYYYY"
    6
        }
    7
      }
    8
    }

    It parses the table object and retrieves the target based on the args.target value. The lc: function is used to convert the target to lowercase for case-insensitive matching.

  • In this scenario, a valid target can be either support or sales.

  • If the target is found in meta_data.table, the call is connected to the respective number.

  • If the target is not found in meta_data.table, the string field returns empty and does not match the first expression object. This leads to matching the second expression, which is a catch-all for any string that returns any valid character. Since an empty string is a valid character, this causes a successful match.

• Output: Based on the match, specific actions or responses can be triggered. This allows performing conditional tasks depending on the user’s input. Each expression object contains its own output.

Webhooks

Webhooks extend the capabilities of your SWML scripts by enabling communication with external systems. This can be essential for integrating with APIs, fetching real-time data, or pushing updates to external services.

Key points to note about webhooks:

• External Interaction: Webhooks enable your SWML scripts to make HTTP requests to external endpoints, facilitating integration with third-party services.
• Dynamic Requests: The url field can include dynamic values, making it possible to construct requests based on the current state or input data.
• Method Specification: The method field allows you to define the HTTP method (GET, POST, etc.) to be used for the request, providing flexibility in how data is sent or received.
• Response Handling: The output section specifies how the response from the webhook should be processed, including actions to be taken and responses to be fed to the AI agent.

Example

1
{
2
  "data_map": {
3
    "webhooks": [
4
      {
5
        "url": "https://icanhazdadjoke.com/search?term={lc:args.type}",
6
        "method": "GET",
7
        "output": {
8
          "response": "Tell the user: ${array[0].results[0].joke}.",
9
          "action": []
10
        }
11
      }
12
    ]
13
  }
14
}

Detailed Explanation

• URL Construction: The url field specifies the endpoint to which the HTTP request should be made.

  • In the example, https://icanhazdadjoke.com/search?term={lc:args.type} constructs the URL with a query parameter term based on the args.type value.
    • The url https://icanhazdadjoke.com/search is used to fetch jokes based on the query parameter term.
    • args.target is a SWAIG.function argument that contains the target value passed by the user when interacting with the AI agent.
  • The lc: function is used to convert the args.type value to lowercase for consistency.

• HTTP Method: The method field defines the HTTP method to be used for the request.

  • In the example, GET is used to fetch data from the specified URL.

• Webhook Response Handling: The output section specifies how the response from the webhook should be processed and if any actions should be taken.

  • When making a request to the icanhazdadjoke API, the response contains an array of jokes that we can access and play back to the user.
  • In the output section, the response field is used to tell the AI agent to relay the joke to the user.
    • The array[0].results[0].joke syntax is used to access the first joke in the results array.

  Example Response:

  1
  {
  2
    "current_page": 1,
  3
    "limit": 20,
  4
    "next_page": 1,
  5
    "previous_page": 1,
  6
    "results": [
  7
        {
  8
            "id": "qrHJ69M7hFd",
  9
            "joke": "What cheese can never be yours? Nacho cheese."
  10
        },
  11
        {
  12
            "id": "SSCQCdi39Ed",
  13
            "joke": "Did you hear about the cheese factory that exploded in France? There was nothing left but de Brie."
  14
        }
  15
    ],
  16
    "search_term": "Cheese",
  17
    "status": 200,
  18
    "total_jokes": 2,
  19
    "total_pages": 1
  20
  }

Outputs

Outputs define the responses and actions that should be taken when an expression matches or a webhook request completes. This can include sending messages, triggering functions, or modifying variables.

Outputs are the mechanisms through which your SWML script communicates and reacts to data. They enable the script to provide feedback to the user, execute actions, and modify the script’s state based on input data and external interactions.

Example:

1
{
2
  "data_map": {
3
    "expressions": [
4
      {
5
        "pattern": "\\w+",
6
        "string": "${meta_data.table.${lc:args.target}}",
7
        "output": {
8
          "action": [
9
            { "say": "Please stand by while I connect your call." },
10
            {
11
              "transfer": true,
12
              "SWML": {
13
                "version": "1.0.0",
14
                "sections": {
15
                  "main": [
16
                    {
17
                      "connect": {
18
                        "to": "${meta_data.table.${lc:args.target}}"
19
                      }
20
                    }
21
                  ]
22
                }
23
              }
24
            },
25
            { "stop": true }
26
          ],
27
          "response": "transferred, the call has ended."
28
        }
29
      }
30
    ]
31
  }
32
}

Responses

Responses in data_map are used to provide feedback to the AI agent based on the user’s input or external data. They can include messages, prompts, or other forms of communication to guide the user through the interaction.

Key points to note about responses:

• Immediate Feedback: Responses provide immediate feedback to the user based on the matched patterns or webhook responses, ensuring a seamless and interactive user experience.
• Dynamic Content: Responses can include dynamic content, leveraging placeholders to incorporate real-time data into the messages sent to the user.

Example:

1
{
2
  "data_map": {
3
    "expressions": [
4
      {
5
        "pattern": ".*",
6
        "string": "${args.target}",
7
        "output": {
8
          "response": "I'm sorry, I was unable to transfer your call to ${args.target} due to being an invalid destination."
9
        }
10
      }
11
    ]
12
  }
13
}

Detailed Explanation

• Response Message: The response field contains the message to be relayed to AI agent. This message can be instructive, informative, or conversational, depending on the context.
  • In the example, I'm sorry, I was unable to transfer your call to ${args.target} due to being an invalid destination. is the message that will be sent to the AI agent if the args.target is not found in the meta_data.table object. This will cause the AI to inform the user that the transfer destination is invalid.
  • The ${args.target} placeholder is used to dynamically insert the target value provided by the user into the response message.

Actions

Actions in data_map define what should happen when the swaig.function executes and a specific expression matches or a webhook request completes.

Actions can include triggering functions, modifying variables, controlling the flow of the current SWML script or even starting a new SWML script.

Key points to note about actions:

• Operational Control: Actions provide fine-grained control over the script’s behavior, allowing for complex and dynamic interactions based on user inputs and external data.
• State Management: Actions can be used to manage the state of various components within the SWML script, including an AI’s context, functions, meta_data, playbacks, and more. The action can also

Example:

1
{
2
  "data_map": {
3
    "webhooks": [
4
      {
5
        "url": "https://icanhazdadjoke.com/search?term={lc:args.type}",
6
        "method": "GET",
7
        "output": {
8
          "response": "Tell the user: ${array[0].results[0].joke}.",
9
          "action": [
10
            {
11
              "toggle_functions": [
12
                { "active": true, "function": "transfer" },
13
                { "active": false, "function": "get_joke" }
14
              ]
15
            }
16
          ]
17
        }
18
      }
19
    ]
20
  }
21
}

Detailed Explanation

• Action Definition: The action field specifies the actions to be taken based on the webhook response.
  • In the example, the action is to toggle the transfer and get_joke functions based on the response from the webhook.
    • The transfer function is activated (active: true) to enable the user to be transferred to the target department.
    • The get_joke function is deactivated (active: false) to prevent further joke requests after the first one has been fulfilled.

Variable scopes in data_map

When working with data_map, you have access to several special variable scopes that are only available in SWAIG/AI contexts:

• args - Function arguments passed to the SWAIG function
• meta_data - Function-level metadata that persists across function calls
• global_data - Application-wide data accessible across all functions
• prompt_vars - Built-in template variables for call and AI session information

For complete technical specifications, types, and properties, see the SWAIG Variables Reference.

For general SWML variable scopes like call, params, and vars, see the Variables Reference.

Utilizing stored values

When working with data_map, there are several ways to utilize stored values, such as function.argument (args), function.meta_data, and SWML variables (vars).

Function Arguments

SWAIG function arguments are processed as args and can be accessed within the data_map section. These arguments are defined in the functions section of the SWAIG object. Initially, the value of the argument is empty, but as the user interacts with the AI, the value is updated based on the user’s input.

To access the value of a specific argument, use ${args.<argument_name>}. For example, if the argument is named target, you can access its value using ${args.target}.

Global Data & Function Meta Data

Both global_data and function.meta_data are versatile environmental objects that can store arbitrary data. This data can be set initially in the SWML script or dynamically through the SWML set_global_data or set_meta_data actions.

• meta_data: Stores data specific to a particular function.
• global_data: Accessible across all functions within the SWML script.

Accessing Meta Data

To access the value of a specific meta_data key, use ${meta_data.<key>}. For example, if the key is table, you can access its value with ${meta_data.table}.

For global_data, access the value of a specific key using ${global_data.<key>}. For example, if the key is table, you can access its value with ${global_data.table}.

If your meta_data or global_data is an object, you can access a specific property using ${meta_data.<key>.<property>} or ${global_data.<key>.<property>}. For example, if the key is table and the property is support, you can access its value with ${meta_data.table.support} or ${global_data.table.support}.

SWML Variables

SWML variables (vars) store data created by a SWML request or set method.

To access the value of a specific SWML variable, use ${vars.<variable_name>}. For example, if the variable is joke, you can access its value with ${vars.joke}.

This structure helps efficiently manage and retrieve data within your SWML scripts, providing a clear and consistent way to handle environmental data and variables.

Comprehensive example

Below is a comprehensive example that incorporates all aspects of data_map and is ready to be used in a SWML script.

1
{
2
  "sections": {
3
    "main": [
4
      {
5
        "ai": {
6
          "prompt": {
7
            "text": "Your name is Frank. You help transfer to the right department. Use the 'get_joke' function to get a joke.\n\n## Greetings\nGreet the user, and inform them that your name is Frank and you can help assist them in transferring the call to Support or Sales. However, let them know the only way to be transferred is to hear a joke.\n\n## Rules\n- A user cannot be transferred until they have asked for at least one joke throughout the call.\n- When a user is able to be transferred, use the 'transfer' function. Only provide one joke to the user.\n- If the user asks for more jokes after the first one, tell them you are no longer giving out jokes, but can help with transferring the call to a different department.\n\n## Steps to follow\n1. Greet the user.\n2. Tell them they can be transferred to either support or sales, but first they need to hear a joke.\n3. If the user asks for a joke, first ask what kind of joke they want to hear, then use the 'get_joke' function.\n  3.1. If the user doesn't want to hear a joke, tell them you can't transfer them until they hear a joke.\n  3.2. If the joke returned from the function is empty, tell the user you couldn't find a joke.\n  3.3. Do not make up a joke if the function returns empty.\n4. Tell the user the joke.\n  4.1. If the user asks for another joke, tell them you can't give them another joke, but you can transfer them to the right department.\n5. If the user asks to be transferred, use the 'transfer' function."
8
          },
9
          "post_prompt": "Summarize the call as a json object",
10
          "post_prompt_url": "https://example.site.com/summarize",
11
          "SWAIG": {
12
            "functions": [
13
              {
14
                "function": "transfer",
15
                "active": "false",
16
                "description": "use to transfer to a target",
17
                "parameters": {
18
                  "type": "object",
19
                  "properties": {
20
                    "target": {
21
                      "description": "the target to transfer to",
22
                      "type": "string"
23
                    }
24
                  }
25
                },
26
                "data_map": {
27
                  "expressions": [
28
                    {
29
                      "pattern": "\\w+",
30
                      "string": "${meta_data.table.${lc:args.target}}",
31
                      "output": {
32
                        "action": [
33
                          { "say": "Please stand by while I connect your call." },
34
                          {
35
                            "transfer": true,
36
                            "SWML": {
37
                              "version": "1.0.0",
38
                              "sections": {
39
                                "main": [
40
                                  {
41
                                    "connect": {
42
                                      "to": "${meta_data.table.${lc:args.target}}"
43
                                    }
44
                                  }
45
                                ]
46
                              }
47
                            }
48
                          },
49
                          { "stop": true }
50
                        ],
51
                        "response": "transferred, the call has ended."
52
                      }
53
                    },
54
                    {
55
                      "pattern": ".*",
56
                      "string": "${args.target}",
57
                      "output": {
58
                        "response": "I'm sorry, I was unable to transfer your call to ${args.target} due to being an invalid destination."
59
                      }
60
                    }
61
                  ]
62
                },
63
                "meta_data": {
64
                  "table": {
65
                    "support": "+1XXXXXXXXXX",
66
                    "sales": "+1YYYYYYYYYY"
67
                  }
68
                }
69
              },
70
              {
71
                "function": "get_joke",
72
                "description": "used to get a joke",
73
                "parameters": {
74
                  "type": "object",
75
                  "properties": {
76
                    "type": {
77
                      "type": "string",
78
                      "description": "Type of joke to get"
79
                    }
80
                  }
81
                },
82
                "data_map": {
83
                  "webhooks": [
84
                    {
85
                      "url": "https://icanhazdadjoke.com/search?term={lc:args.type}",
86
                      "method": "GET",
87
                      "output": {
88
                        "response": "Tell the user: ${array[0].results[0].joke}.",
89
                        "action": [
90
                          {
91
                            "toggle_functions": [
92
                              { "active": true, "function": "transfer" },
93
                              { "active": false, "function": "get_joke" }
94
                            ]
95
                          }
96
                        ]
97
                      }
98
                    }
99
                  ]
100
                }
101
              }
102
            ]
103
          }
104
        }
105
      }
106
    ]
107
  }
108
}

Key points

• Expressions are used to match patterns and trigger actions or responses based on user input.
• Webhooks are used to fetch data from external sources and integrate it into the SWML script.
• Outputs define the responses and actions based on the matched patterns or fetched data.
• Stored Values such as args, meta_data, and SWML variables can be accessed within the data_map section.