Customizing the Script widget

Contact center admins can add and edit the Script widget. The Script widget allows you to perform specific actions in the flow so that you don't need to rely on the UI to build flows. Keys, secrets, and other credentials are hidden by default in Script widgets.

Requirements for customizing the Script widget

Table of Contents

How to add or edit the Script widget

  1. Sign in to the Zoom web portal as an admin with the privilege to edit flow settings.
  2. In the navigation menu, click Contact Center Management then Flows.
  3. Click a flow's display name to edit it.
  4. In the left-side widgets panel, click and drag Script onto the preferred location in the flow.
  5. Select the Script widget.
  6. (Optional) Click Rename to change the display name of the widget.
  7. Click Add Script to add a new script to the widget, then specify these options:
  8. Click Add.
  9. Enter your JavaScript code.
  10. To test your code locally, on the right side, use the Input Parameter panel to input parameters for the script in JSON format. Make sure to include the appropriate key/value pairs as required by your JavaScript code. When testing your code locally, you will need to provide all expected key/value pairs as Input Parameters. For example, if you need to pass the ANI into your Script for testing, you can use the JSON object {"global_system.Engagement.ANI":"+16505551234"}
  11. Click run.
    The result will appear in the Result section.
  12. Click Close.
  13. Click Save to save the script.
  14. (Optional) In the Settings tab, use these options:
  15. Output variables: Click Add Output then select a local or global variable in the Script.value drop-down menu.
  16. Click the Exits tab to customize exit settings.

Note: To better understand usage of the Script widget, see example configurations.

Script variable mapping

After configuring the Script widget and running it, you can map the script variable values to a flow variable.

You can also map variables in the Output variables section when customizing the Script widget.

Example of script mapping

See the account number example for details.

How to program scripts

  1. Add all dependencies to your code. See lines 2 to 4 in the example code below.
  2. Pass your function to module.exports so that code engine can extract your JS function. Use async only when you need await in your function. There is no need to call the function within the code panel.
    Note: Strict mode is turned on automatically.

Example of script programming

async function main () {
  // your code starts here
}

Note: 
#### Supported built-in functions: (no need to import again)

## Variable Get/Set:
var_get()[string]; var_set(string, string); global_var_set(string, string)

## Http Requests:
req.get(url[, config]); req.delete(url[, config]); req.head(url[, config]); req.options(url[, config])
req.post(url[, data[, config]]); req.put(url[, data[, config]]); req.patch(url[, data[, config]])

## Logging
log.debug(string), log.info(string), log.warn(string), log.error(string)

Note: At this time, only the built-in functions above are available. External modules are not supported.

How to use logging

You can log information in your scripts by leveraging the 'log' built-in function as shown below. To view the logs, you will need to enable the Flow debug console.

Example of logging

You can implement logging by using these functions:

log.debug("debugging enabled")
log.error("error detected")
log.info("info: yes")
log.warn("WARNINGS: ")

How to implement HTTP requests

You can send HTTP requests using the Script widget. The Script widget javascript code provides you the ability to send HTTP requests using the built-in function 'req'.

Note: You can implement HTTP requests using the standard Http Call widget which allows you to perform HTTP requests without writing JavaScript functions. However, using a Script widget and the 'req' built-in function to perform HTTP requests is available for more advanced use cases.

Example of HTTP request

Below is an example of an HTTP request.

const response = await req.get("https://api.example.com")

Refer to the Axios Support site for more information.

How to get variables within the Script widget

You can get variable information in your scripts by leveraging the 'var_get' built-in function as shown below. A common use case for this is to read global variable data into your script code, and then perform action based on the variable values. To do this, you will read a global variable and temporarily access/store it in your script.

Use the var_get function to get the value of the variable. The var_get function can access the value of both local and global variables.


Example for reading Global System variable:

let first_name = var_get()["global_system.Consumer.firstName"]

Example for reading Global Custom variable:

let account_number = var_get()['global_custom.General.account_number']

Note: System global variables are defined by default, but global custom global variables must be defined first.  In the above Global Custom variable example, a custom variable group named "General" was created and a custom global variable named "account_number" was created in the group.

Note: For more information on global variables, including whether values are shared across multiple engagements, please consult the global variables and review the difference between "Linked Value", "Default Value", and "Undefined" variable types.

How to set local variables within the Script widget

You can set local variable values in your scripts by leveraging the 'var_set' built-in function as shown below. A common use case for this is to store some data generated in your script (e.g. API response) into a local variable.

  1. Add and configure the Script widget in your flow. For this example, rename the Script widget from Script to Script1.
  2. Use the var_set function to set the value for a local widget variable. The first parameter is the full name of the local widget variable; the second parameter is the value.
    Example:var_set("account_number", “99999")
    The value of this variable will now be accessible within this flow as Script1.account_number
  3. Alternatively, map the local widget variable on the exit of the Script widget. Return to the Script widget, and click on the Add Output link.
  4. In the Script Variable field, enter the name of the variable. For this example, it's "account_number".
  5. In the Map output to dropdown, select a local flow variable or global variable for mapping.
  6. If your script has multiple var_set functions to store variables, repeat steps 4-6 for each variable.

How to set global variables within the Script widget

You can set global variable values in your scripts by leveraging the 'global_var_set' built-in function as shown below. A common use case for this is to store some data generated in your script (e.g. API response) into a global variable, which can then be used in ZCC logs and/or displayed to the Contact Center agent.

  1. Add and configure the Script widget in your flow.
  2. Use the global_var_set function to set the value for a global variable. The first parameter is the full name of the global variable; the second parameter is the value.
    Example:
    global_var_set("global_system.Consumer.firstName", "Your Name")

Note: While global variables are defined globally on the system, any value that you set in a global variable within a flow is limited in scope to the active engagement.

Important: