Script widget examples

Contact center admins can add and edit the Script widget. This article contains various example configurations using the new syntax of the Script widget.

Requirements for customizing the Script widget

Table of Contents

Example 1: Look up caller ID using the Script widget and global variables

The following example shows how to use a Script widget to place an REST API call using the built-in request function. The values from the API response will be returned and then later accessed within the Flow.

In this example, we will query a REST API for the Caller’s phone number. If the caller’s phone number is found in the external database, the API response will return account number information about the caller. The flow will then take the API response and check whether a match was found in the external database. If a match was found, the flow will play back the account number for the caller and then send the caller to a queue.

Prerequisites

Define the custom global variables shown below. These variables will be populated in the script based on the response from an API query.

Custom Variable Group NameCustom Variable Name
GeneralaccountNumber
GeneralaccountStatus
GeneralqueueName
SecretscrmApiKey

Flow layout

Script widget

Script widget contains the following script:

async function main () {
  let caller_number = var_get()["Start.From"];
  let callee_number = var_get()["Start.To"];


  log.info("Call from " + caller_number + " to " + callee_number);


  try {


    const result = await req.get('https://crm.example.com', 
      { headers: {'Authorization': var_get()["global_custom.Secrets.crmApiKey"]}, params: { ani: caller_number } });


    let jsonResponseBody = result.data;  // Store the API response


    log.debug("API Response jsonResponseBody=" + JSON.stringify(jsonResponseBody));


    // Set Global Variables
    global_var_set("global_custom.General.accountNumber",jsonResponseBody.account_number);
    global_var_set("global_custom.General.accountStatus",jsonResponseBody.account_status);
    global_var_set("global_system.Consumer.email",jsonResponseBody.email_address);
    global_var_set("global_system.Consumer.firstName",jsonResponseBody.first_name);
    global_var_set("global_system.Consumer.lastName",jsonResponseBody.last_name);


  } catch (error) {
    log.debug("Received error " + error);    
  }


  return; 
}

Condition Widget

Condition widget settings

Condition widget exits

Exit 1: This exit is used to determine if we have matched on an account number. In the above example, the API needs to return {“account_status”:”active”} for the flow to match on the caller ID.

No Match: Select Route_to_Queue

Send Media widget

Script widget debugging

The Input Parameter section of the Script widget can be used for debugging. Within the Input Parameter box, enter JSON encoded variables that are required as input for the script. If you are accessing any global variables within the script, you will need to populate them here for debugging purposes.

Enter the following in the Input Parameter panel to test the above script:

{
"Start.From":"+16505551234",
"global_custom.Secrets.crmApiKey":"this_is_the_api_secret"
} 

Example output in the Result section:

Wed Jul 27 2022 15:22:12 GMT-0700 (Pacific Daylight Time) [INFO] Call from +16505551234 to undefined
Wed Jul 27 2022 15:22:13 GMT-0700 (Pacific Daylight Time) [DEBUG] API Response jsonResponseBody={"account_number":"99999","account_status":"active","email_address":"john@example.com","first_name":"John","last_name":"Doe"}

Example 2: Script widget with Local Widget variable

Note: This section shows an example configuration and is not meant to be a complete configuration guide.

This example demonstrates how to use the Collect Input widget to gather data (e.g., an account number) from a caller. The collected data is processed using a Script widget, and the result is played back to the caller via the Send Media widget. This example uses local widget variables instead of global variables.

Flow Overview:

  1. The Collect Input widget collects an account number entered by the consumer.
  2. The Script widget processes the input and sets a local widget variable (account_status).
  3. The Send Media widget plays back the account number or account status using the local widget variable.

Script widget

The Script widget utilizes the var_set function to define a local widget variable (account_status). Below is the script:

async function main () {
 var account_number = var_get()["GetAccountNum.Digits"]; // Get Account Number input
 log.info("Received Account Number " + account_number);
  
 // do something with account Number
 // add your business requirements here
 let account_status = "active";

 // create a new local variable called ‘account_status’ for this widget
 var_set("account_status",account_status);  // this is just an example on how to set a local widget variable
  
 return
}

Flow layout

Since we are using a local widget variable, there is no need to configure Output variable mapping.

Send Media widget

To reference the local widget variable account_status in the flow, use the variable in the format AccountScript.account_status. For example, you can configure the Send Media widget to play back the account status to the caller.

Example 3: Script widget with Local Flow variable

This example builds upon Example 2 but demonstrates how to map a local widget variable to a local Flow variable, which can then be reused in subsequent widgets.

Script widget

The script remains identical to Example 2.

 async function main () {
 var account_number = var_get()["GetAccountNum.Digits"]; // Get Account Number input
 log.info("Received Account Number " + account_number);
  
 // do something with account Number
 // add your business requirements here
 let account_status = "active";

 // create a new local variable called ‘account_status’ for this widget
 var_set("account_status",account_status);  // this is just an example on how to set a local widget variable
  
 return
}

Flow layout

In this case, map the local widget variable account_status to a local Flow variable (e.g., accountStatus) in the Output Variables section of the Script widget configuration.

Send Media widget

You can reference the Flow variable accountStatus in the Send Media widget or other parts of the flow.

Example 4: Script widget with variable in return

This example demonstrates returning a variable directly from the Script widget without using the var_set function. Instead, the variable is returned via the return statement.

Note: The return statement only supports returning a single variable.

Script widget

Below is the script:

async function main () {
 var account_number = var_get()["GetAccountNum.Digits"]; // Get Account Number input
 log.info("Received Account Number " + account_number);
  
 // do something with account Number
 // add your business requirements here
 let account_status = "active";

 // return account status variable when script completes
 return account_status
}

Flow layout

In the Outbound Variables section of the Script widget configuration, map the returned value (Script.value) to a local Flow variable (e.g., accountStatus).

Note: The Script.value in the Output variables section represents the data that the script code returns using the return statement. 

Send Media widget

After mapping the return value to the Flow variable, you can use accountStatus in the Send Media widget or other subsequent flow steps.

Summary of differences between examples

 
FeatureExample 1Example 2Example 3Example 4

Variable Type

Global Variables

Local Widget Variable

Local Flow Variable

Script Return Variable

Variable Creation

global_var_set

var_set

var_set

return

Variable Scope

Accessible across all flows and widgets

Limited to the widget

Accessible throughout the current flow

Accessible throughout the current flow

Output Mapping

Not required (global variables are pre-defined)

Not required

Widget variable mapped to Flow variable

script.value mapped to Flow variable

Use Case

Query external database and process results

Use within specific widget scope

Share variables across widgets in a single flow

Simplified return of single variable for reuse

Important: