Engage Voice | Call controls reference

Table of contents

Call controls refer to actions that can be performed on an active call. They appear in various locations throughout the platform, and they can be useful in a variety of situations. For example, you can add them into scripts via elements to give agents the ability to take actions on calls themselves, or you can eliminate the agent interaction altogether and simply trigger them via API.
 
Call controls can range from a ‘hangup’ action to a call transfer action, and they can be configured in the admin interface and triggered manually via the agent interface or behind the scenes in a call or script. One way to give agents access to call controls is by adding a Button element to their script in Script Studio and configuring its call controls settings via the Actions tab.
 
The Button element allows you to create and configure a button that, when clicked by the agent, will perform whatever action you assigned to it, whether that’s dispositioning the call or transferring it to a supervisor. 
 
Another way to access and configure call controls can be found in the agent scripting JavaScript tool. You can use this tool to trigger any call action via API at any point in your script. Simply place the tool into your script flow wherever you would like the call control action to occur, then configure the JavaScript tool with the action(s) of your choice. 
 
In the next section, we’ll list all the call controls and their definitions, along with any dependencies associated with each control. Dependencies refer to any additional controls or settings that appear when you interact with a specific setting. 
 
For example, if you click on the Disposition Call control, you’ll be presented with a few additional options that allow for further configuration — whether that’s adding a note to the disposition or scheduling a callback. Each dependency will appear below the action/setting it modifies.
 
After that, we’ll go over call controls that can be accessed via API methods. 

Call controls in an agent script

The definitions provided below refer to call controls that can be manually accessed by an agent via a script. Any dependencies are listed below each control. A note about dependencies: when configuring these via the Button element in Script Studio, you can either enter information manually, or you can choose any data models you wish to access in tag format (via the {{add a tag}} button) and enter them into the provided fields below each dependency.
  • Disposition Call: This action will trigger a call disposition
    • Disposition: Provide the agent disposition you would like the agent to submit. Please note that the agent disposition name provided in this field must match the name of an existing disposition created at the queue or campaign level
    • Callback: Schedule a follow-up call
    • Callback Datetime: Set the date and time for the callback
    • Forward Phone Number: Set the phone number you wish to forward the call to upon agent disposition (the specific disposition referred to here relates to the Contact Forwarding setting you’ll find in your disposition’s configuration modal window settings)  
    • Notes: Choose the data you wish to enter into the disposition’s Notes field. Any data entered here will be available via reporting
  • Hangup: This action will hang up the call upon click
  • Hold Call: This action will place the call on hold upon click
  • Start Recording: This action will begin recording the call upon click
  • Pause Recording: This action will pause the call recording upon click

Helpful hint!

If you wish to trigger the Start and Pause Recording options, you must enable call recording via the Call Recordings setting in the Call Recording Settings section of your campaign’s configuration page. To enable call recording, simply select one of the following options within that setting: Yes - Record Full Call, Yes - Record Call (Agent Pause), Agent Triggered (Default: Don’t Record), or Agent Triggered (Default: Record)
  • Warm Transfer: This action will transfer the call to a destination of your choice while the agent remains on the line
    • Transfer To: Choose the destination you wish to transfer the call to upon click
    • Caller ID: Choose the Caller ID number you wish to display for the outgoing transfer
    • Add new custom SIP header: Use this option to add custom SIP header information to the call. You can add multiple values to the headers by clicking on this text for each new value, and you can remove a value by clicking the x icon at far right 
    • Header Label: Choose a name for the value you wish to add to your custom SIP header. This option represents the text that will display to identify the value you enter in the following Header Value field 
    • Header Value: Enter or select the tag value you wish to relay in the header
  • Cold Transfer: This action will transfer the call to a destination of your choice while removing the agent from the call. For definitions of all settings available for the Cold Transfer option, see the list of Warm Transfer setting definitions provided above
  • Warm Requeue: This action will place the call into a queue of your choice while the agent remains on the line. Here, you can choose to either
    • toggle on the Select from available queues button (under Requeue Settings) and choose a queue and queue group skill from the dropdown menus that appear, or
    • leave the Select from available queues button toggled off and simply enter your queue and queue group skill into the fields provided below (in the Available Queues setting)
  • Cold Requeue: This action will place the call into a queue of your choice while removing the agent from the call. For definitions of all settings available for the Cold Requeue option, see the list of Warm Requeue setting definitions provided above

Call controls via API

As discussed above, you can also trigger call controls via API at any point in a call. The Script Studio allows you to do so via the JavaScript tool (if you wish to trigger the action behind the scenes) or via any compatible element or tool that contains an advanced JavaScript section. 
 
You can either press Control + Space bar while in the advanced code editor or refer to the list below to see a full list of API call control methods that we offer.
  • startRecording(); This function triggers the system to begin recording the call
  • stopRecording(); This function stops the call recording
  • holdCall(); This function places the call on hold
  • resumeCall(); This function resumes the call that was placed on hold
  • warmRequeue(queueId, skillId); This function places the call into another queue while the agent remains on the line. You can identify the new queue via the queueId input. Please note that this action can be further refined by identifying an agent skill (skillId), but that input is optional here
  • coldRequeue(queueId, skillId); This function places the call into another queue while the agent is removed from the line. You can identify the new queue via the queueId input. Please note that this action can be further refined by identifying an agent skill (skillId), but that input is optional here
  • warmTransfer(dialDest, callerId); This function transfers the call to another destination (which can be specified via dialDest in phone number format; e.g., 5558675309) while the agent remains on the line. Please note that the callerId input refers to a phone number you can enter here that will override the Caller ID that the call will be made with (this parameter is optional. If you don't pass it in, the system will use the queue or campaign transfer Caller ID)
  • coldTransfer(dialDest, callerId); This function transfers the call to another destination (which can be specified via dialDest, in phone number format) while the agent is removed from the line. Please note that the callerId input refers to a phone number you can enter here that will override the Caller ID that the call will be made with (this parameter is optional. If you don't pass it in, the system will use the queue or campaign transfer Caller ID)
  • dispositionCall(disposition, notes, isCallback, contactForwardNum, callbackDts); This function submits an existing disposition for the call:
    • The disposition parameter you use here must be entered as a string value (case insensitive), and it must reference a valid disposition that is already assigned to/configured on your campaign or queue, otherwise this method will not work. This parameter is required
    • The notes parameter refers to a text block (entered in string format) that appears beside the disposition for agents to enter notes into. This is a setting you can configure yourself via the dispositions setting. It is not required by default, but you can configure it to be required in your queue/campaign disposition configuration settings
    • isCallback refers to whether or not you wish to flag this contact for a callback. The expected response is a T/F (true or false, or boolean) value. This parameter is not required
    • The contactForwardNum parameter can be used to set up another call to the contact at a new number of their choosing. You can input the new call destination here in phone number format (SIP is not available for this option). This is not a required parameter
    • The callbackDts parameter refers to the date and time the callback should occur. The expected format is YYYY-MM-DD hh:mm:ss (using the 24-hour time system). This is not a required parameter
  • hangup(); This function terminates the call
© 1999-2021 RingCentral, Inc. All rights reserved.
Close X
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.