Engage Voice | Using the JavaScript tool

The JavaScript tool is a choose-your-own-adventure type of tool. That’s because you can do just about anything you want with it. It has a number of native functions, including the ability to go to any tool in the script, load files from your server to host, and even switch scripts for agents based on any conditions you specify within the script.
 
As you may have guessed, this is an advanced functionality (and we do recommend you have some working knowledge of JavaScript to use it), but we’ll review the basics here so you can get an idea of how to configure the system to do anything and everything you need it to.

JavaScript tool uses

The JavaScript tool has a multitude of uses. For example, you can use it to create multiple background processes that trigger themselves to run without your agents ever having to see or do anything. Bundle several actions into one unseen process (or trigger them via a button click on the agent side if you prefer); transfer a call, end the agent’s leg of the call, fire off a web service that sends call, lead, and custom info to your database, and send in a disposition — all at once. 
 
Because this tool has so many possibilities, we’ll give you all the information you’ll need to fully engage with it, along with some caveats, examples, and use cases. Let’s start with a few helpful tips:
  • At any time you can click into the JavaScript text editor and press Ctrl + Spacebar to bring up all helper commands and a list of all available functions. When the helper window appears, you can begin typing the name of the command you’re looking for and the system will autocomplete it for you. Don’t forget to scroll to see more options!
  • Please note that all the capabilities available within this tool are also available in the advanced Scripting tab located in any Page tool element that allows for advanced agent scripting configuration
  • Please also note that any agent scripting command on an input control will only take place after the user has interacted with the input — in other words, the command must be triggered by an action before it will run

JavaScript objects

Now, let’s talk about JavaScript objects. Your lead, call, and model objects contain values that can be accessed throughout the Script Studio, in any element or tool that contains custom JavaScript agent scripting capabilities. You can see a list of available values at any given time by pressing Ctrl + Spacebar either from the JavaScript tool itself or from the Scripting tab located in any element that allows for advanced agent scripting configuration.
Lead and call objects
The lead object references any data related to an outbound lead. Please note that the lead object will be null for any inbound call unless the call has campaign callback mapping attached to it. Meanwhile, the call object references any data related to a call or chat/SMS. Please note that chat/SMS object will also be null unless there’s a campaign match attached to it.
 
Both the lead and call objects contain a number of predefined properties, which we’ll get into in just a moment.
Model object
The model object allows you to create and reference your own custom reportable script properties (that have a key value relationship). These are then made available in various places throughout the system via tagging. Please note that any time you see the phrase ‘reportable script data,’ it’s a reference to your custom model data. 
 
Items belonging to the model object include any element in your script that generates data — like the Buttons and Checkboxes elements — but not elements like the Page Break element. The model object also holds any input/responses received while the agent is on a call or chat. 
 
A quick clarification on the model object: You may notice that there exists two model names (e.g., {{model.model.property_name}}) in the custom script tag notation. Just remember that the first model is the container for all of the objects, and the second model refers to the custom script data object itself.
 
When a custom script data property is created, it will appear as {{model.model.your_property_name}} in tag notation. You can also, however, reference it via the getData() JavaScript method as getData(“model.model.your_property_name”). Using this notation, you can retrieve information off the model via the getData() method, and you can set data to the model via the putData() method.
 
Please note that any Page tool element value that gets set (e.g. a checkbox, select menu, text area field, etc.) will be stored on the custom model object. Custom SIP headers from IVRs can also be passed into a script’s data via the model object, and they can be found under {{model.call.baggage}}.
Object properties
In the following tables, each property key is named for both the lead and call objects, then identified by its type (string, object, or array), and followed by the specific value name attached to it. The call object table also tells you which properties are nullable, and the conditions under which each property is present/not present. The last column in the call table gives you some context; is the property available for chat/SMS? Calls? Or both?
JavaScript lead properties table
JavaScript tool call and chat/SMS properties table
*This is available for any chat queue that has a DNIS assigned to it (e.g., if a customer manually sends an SMS to the chat queue, and/or if an agent sends a manual SMS chat to a customer)
**Any extra data attached to your lead (lead.extraData) will appear as key value pairs under the ‘baggage’ object in the following syntax: {{model.call.baggage.name_of_extra_data_property}}
***In that case, it is only present if the ANI is mapped to a lead existing in the corresponding campaign

API methods

The JavaScript API in Script Studio exposes several methods you can use to help build custom scripts that meet the needs of your organization, from script flow to custom data to call controls. Below we’ll discuss all of the API methods available in any of our JavaScript tools. Please note that many of these methods are also available through the use of the Page tool’s element call control settings.
Call controls
For a complete list of API call control methods, check out Call controls.
Script data
  • putData(modelAttr, data); This request allows you to put data onto the model object using the model attribute and a specific data property. Please note that the {{model.model.attribute}} syntax does not apply when using the putData method. Here, you only need to write model once; the system supplies the second model for you
  • getData(modelAttr); This request allows you to get data from the lead, call, or model object using the model attribute
Here’s an example of how these two requests might look for the model object:
putData('tableData', [
{ propane: "HD5", amount: "5"},
{ propane: "HD10", amount: "10"},
{ propane: "Commercial", amount: "15"}
]);
console.log("Table Data Created");
var data = getData('model.model.tableData');
var tableResults = data[0];
console.log("Table Data: " + tableResults);
And here’s how the “getData()” request might look for the call object:
var queueName = getData(model.call.queueName);

if (queueName=="Strickland Propane Customer Service"){
    dispositionCall("Pass");
    warmRequeue(140063); // skillId is optional
};
Script Flow
  • goTo(toolName);  This request allows you to navigate to any other tool in the script tool by name
  • changeScript(scriptId); This request allows you to switch from one script to another. Please note that any script data captured in the current script will be carried over to a new script

What to expect of your packet

Below you’ll find a sample JSON packet that demonstrates the syntax and formatting you can expect from your data object packet.
 
This example contains all object information that is available while an agent is on a call:

  "model":{ 
      "hide":{ 
        "value":[ 

        ],
        "leadField":""
      }
  },
  "lead":{ 
      "leadId":"5339080",
      "leadPhone":"7207738416",
      "externId":"7207738416",
      "title":"",
      "firstName":"Bill",
      "lastName":"Dauterive",
      "suffix":"",
      "email":"",
      "address1":"123123",
      "address2":"",
      "city":"",
      "state":"TX",
      "zip":"",
      "gateKeeper":"umm",
      "auxPhone":"",
      "auxData1":"",
      "auxData2":"",
      "auxData3":"H",
      "auxData4":"",
      "auxData5":""
  },
  "call":{ 
      "uii":"201808031050010131000000000237",
      "ani":"7207738416",
      "dnis":"888555121231",
      "dispositions":[ 
        { 
            "contactForwarding":false,
            "dispositionId":"9",
            "isComplete":true,
            "isDefault":false,
            "requireNote":false,
            "saveSurvey":true,
            "xfer":false,
            "disposition":"Done"
        },
        { 
            "contactForwarding":false,
            "dispositionId":"10",
            "isComplete":false,
            "isDefault":false,
            "requireNote":false,
            "saveSurvey":true,
            "xfer":false,
            "disposition":"Callback"
        },
        { 
            "contactForwarding":false,
            "dispositionId":"15",
            "isComplete":false,
            "isDefault":false,
            "requireNote":false,
            "saveSurvey":true,
            "xfer":false,
            "disposition":"Maybe Callback"
        },
        { 
            "contactForwarding":false,
            "dispositionId":"39",
            "isComplete":true,
            "isDefault":false,
            "requireNote":false,
            "saveSurvey":true,
            "xfer":false,
            "disposition":"Abandon"
        },
        { 
            "contactForwarding":false,
            "dispositionId":"40",
            "emailTemplateId":"8",
            "isComplete":true,
            "isDefault":false,
            "requireNote":false,
            "saveSurvey":true,
            "xfer":false,
            "disposition":"email"
        },
        { 
            "contactForwarding":true,
            "dispositionId":"44",
            "isComplete":true,
            "isDefault":false,
            "requireNote":false,
            "saveSurvey":true,
            "xfer":false,
            "disposition":"Contact Forward"
        },
        { 
            "contactForwarding":false,
            "dispositionId":"77",
            "isComplete":true,
            "isDefault":false,
            "requireNote":true,
            "saveSurvey":true,
            "xfer":false,
            "disposition":"Note"
        },
        { 
            "contactForwarding":false,
            "dispositionId":"1003",
            "isComplete":true,
            "isDefault":false,
            "requireNote":false,
            "saveSurvey":true,
            "xfer":false,
            "disposition":"Success!"
        },
        { 
            "contactForwarding":false,
            "dispositionId":"1007",
            "isComplete":true,
            "isDefault":false,
            "requireNote":false,
            "saveSurvey":true,
            "xfer":false,
            "disposition":"Dnc"
        },
        { 
            "contactForwarding":false,
            "dispositionId":"1050",
            "isComplete":false,
            "isDefault":false,
            "requireNote":false,
            "saveSurvey":true,
            "xfer":false,
            "disposition":"Copy test"
        }
      ],
      "baggage":{ 
        "allowUpdates":true,
        "showLeadPasses":true,
        "showListName":true,
        "customLabels":[ 
            { 
              "aux_1Label":"Income",
              "aux_2Label":"Age",
              "aux_3Label":"Favorite food",
              "aux_4Label":"Weight",
              "aux_5Label":"Eye color"
            }
        ],
        "genericKeyValuePairs":"",
        "zip":"",
        "auxData3":"H",
        "auxData4":"",
        "auxData1":"",
        "midName":"",
        "auxData2":"",
        "address2":"",
        "city":"",
        "address1":"123123",
        "externId":"7207738416",
        "lastName":"Dauterive",
        "auxPhone":"",
        "title":"",
        "suffix":"",
        "gateKeeper":"umm",
        "state":"TX",
        "firstName":"Bill",
        "leadId":"5339080",
        "email":"",
        "auxData5":"",
        "ani":"7207738416",
        "dnis":"888555121231",
        "uii":"201808031050010131000000000237",
        "sourceId":"529",
        "sourceName":"new queue",
        "sourceDesc":"",
        "sourceType":"INBOUND",
        "agentFirstName":"Ross",
        "agentLastName":"M",
        "agentExternalId":"",
        "agentType":"SUPERVISOR",
        "agentEmail":"",
        "agentUserName":"rm",
        "destination":"7207738416"
      },
      "agentExternId":"",
      "agentFirstName":"Hank",
      "agentLastName":"Hill",
      "agentType":"SUPERVISOR",
      "agentEmail":"",
      "agentUsername":"hh",
      "campaignName":"",
      "campaignId":"",
      "queueName":"new queue",
      "queueId":"529"
  },
  "renderFormValid":true
© 1999-2022 RingCentral, Inc. Tous droits réservés.
Thanks!
We've sent you a link, please check your phone!
Please allow a full minute between phone number submissions.
There was an issue with SMS sending. Please try again. If the issue persists, please contact support.