Click-to-Call

Click-to-Call lets your contacts The person interacting with an agent, IVR, or bot in your contact center. call a live agent with one single click. From a button on your website, visitors can start a direct call to an agent. This can help you to reduce or eliminate:

Extra steps when connecting to a Sales or Support team.
Overhead costs, such as service number fees and mobile surcharges.

Click-to-Call works through a software development kit (SDK) written in JavaScript. To get it set up, you must work with a developer to implement the SDK in your website. You must also work with a Account Representative who can provide specific credentials.

Key Facts About Click-to-Call

Click-to-Call is supported on desktop browsers. It is not currently supported for mobile.
Click-to-Call is currently supported in these regions:
- Canada
- Germany
- Japan
- UK
- US
Key information about the Click-to-Call SDK includes:
- SDK Download: Contact your NICEAccount Representative
- SDK Language: JavaScript (using the AudioCodes WebRTC SDK)
- Supported browsers: GoogleChrome, Microsoft Edge, and Mozilla Firefox
- Microphone Permission: Contacts The person interacting with an agent, IVR, or bot in your contact center. must allow their browser to use their microphone
The SDK consists of a single clicktocall.js file. This must be included or referenced on each webpage where you want the Click-to-Call button to display. You must also implement your own UI components, like the Click-to-Call button and call controls. The Click-to-Call button must invoke the makeCall function in the SDK, which initiates a WebRTC call. If the call request is authenticated by CXone Mpower, the call is placed.
The SDK provides an option to pass user data, website metadata, and routing data as part of the SIP invite request using X-headers. You must configure your Studio script associated with the Click-to-Call point of contact The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address. to get the take and use it as needed. This might include displaying user data in a screen pop for agents or using the routing data to make routing decisions.

This provision is optional and you should only set it up if you need it. If you do not need it, you can set up the makeCall() function without passing any data.

Collecting and passing data is your responsibility. The SDK only provides the mechanism to transmit the data. It doesn't generate, validate, or manage the data.

Integration Prerequisites

To prepare to integrate Click-to-Call into your site, complete the following:

Obtain a Client ID from your NICE Account Representative.
Work with your NICE Account Representative to provision phone numbers specific for Click-to-Call.
Implement a POST API on your own server. This API must generate a JWT token for authentication. This validates that incoming call requests are legitimate.
Learn more
Click-to-Call authentication uses a JWT. You must generate a pair of RSA asymmetric keys with a size of 2,048 bits in the PKCS#1 format. The first is a private key which you use to generate your JWT or JWT1. The JWT must be signed using the RS256 algorithm. The second is a public key, which you must provide to NICE. When initiating a phone call, you must include the JWT1 in the request. CXone Mpower validates the JWT1 in the incoming request with the public key that you provided. Ensure that the JWT1 token's expiry time doesn't exceed 20 seconds.

You must generate the JWT1 with a POST API. You must implement this API on your own server. The SDK expects this API to accept the point of contact The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address. (contact address) and ClientID in the request body. It should return the JWT token with ContactAddress and ClientId as claims.

You can find example code snippets in the IntegrationHelpers/Templates directory of the SDK package. These are written in .NET and Java. They exemplify how to generate the asymmetric keys for authentication and also the POST API you need to implement.

Example API endpoint:
```
POST /generate-jwt1-token
Content-Type: application/json
{
	"ContactAddress": "<CONTACT_ADDRESS>",
	"ClientId": "<CLIENT_ID>"
}
							
	// API response:
"GENERATED_JWT1_TOKEN"
```
Example JWT1 token API endpoint URL:
```
let getJWT1TokenURL = '<YOUR_TOKEN_ENDPOINT_URL>'; //This is where you enter the URL for the POST API you implement.
```
Provide the public key to your Account Representative for authentication.
Consider your UI design. You must develop your own UI for the contact side of the call, including buttons for call controls like mute or ending the call. The SDK includes sample React and Angular components that your developers can use for reference and inspiration. The agent side of the call is handled in their agent application, therefore UI development is only needed for the contact side.

CXone Mpower Setup

In addition to adding the Click-to-Call functionality to your website, you must also ensure your routing components are set up in CXone Mpower. Your CXone Mpower administrator can set up the necessary components.

Be sure you have:

An inbound voice ACD skill created with the necessary agents assigned to it.
Points of contact (POC) set up for the voice calls. These must be phone POCs for each Click-to-Call phone number. The developer implementing Click-to-Call on your site must use this for contactAddress in the JavaScript file.
A Studio script to route the calls to an agent.

Depending on your CXone Mpower setup, you may be able to use existing routing components, or you might need to create and set up new ones.

SDK Integration

Be sure you have completed or prepared the necessary items in the prerequisites section.

Incorporate the clicktocall.js file into your webpage as you see fit.
In the clicktocall.js file, set the API endpoint URL of your POST API.
```
let getJWT1TokenURL = '<YOUR_TOKEN_ENDPOINT_URL>';
```
Add the following UI components to your website. Be sure to give each component a unique identifier. The SDK package includes sample UI components in React and Angular. You can find these in the IntegrationHelpers/UIComponents directory.
- Button to start the voice call.
- Button to hang up or disconnect the call.
- Button to mute and unmute the call audio.
- Button to display a keypad for DTMF inputs.
- A <div> for displaying the keypad keys.
- Label to display call success or error messages.
- An <audio> tag to play certain sounds like dialing tones or call connection sounds.

Update the clicktocall.js file with references to the UI components you added in the previous step.

let clickToCallButtonId = '<YOUR_CLICK_TO_CALL_BUTTON_ID>';
let hangUpButtonId = '<YOUR_HANG_UP_BUTTON_ID>';
let muteAudioButtonId = '<YOUR_MUTE_AUDIO_BUTTON_ID>';
let keypadButtonId = '<YOUR_KEYPAD_BUTTON_ID>';
let dtmfKeyDivId = '<YOUR_DTMF_KEY_DIV_ID>';
let callStatusMessageLabelId = '<YOUR_CALL_STATUS_MESSAGE_LABEL_ID>';
let remoteAudioId = '<YOUR_AUDIO_CONTROL_ID>';

Set your preferences in the configurations section of the clicktocall.js file. This is a section with several configuration variables that control certain types of behavior.

Set the retry count with retryCount. If a call disconnects, this is the number of times the system attempts to reconnect the call. The default is 3.
Set the POCREnvironmentXHeaderValue value to PROD.

Set the configuration settings for the phone server in phoneServerConfig and clientId.

let phoneServerConfig = {
	domain: '<Domain of the SIP server>', //Set value of this configuration to 'cxonevoice.com'
	addresses: [], //Keep this array empty
	iceServers: [], //Keep this array empty
	userName: '<username>', //This configuration is a human-readable string used to identify the sender in a more friendly way. In agent applications like CXone Agent, this might be displayed on the screen during a call. Tthis value should not contain any spaces and should not exceed 20 characters. 
	displayName: '', // This is an optional field and its value can be kept the same as userName 
	password: '' //Keep this field empty
}
let clientID = '<YOUR_CLIENT_ID>'; //Set the value of this configuration as provided by CXone

If you want to customize the contact-side notifications related to calls failing or disconnecting, change the text strings in the following variables in clicktocall.js.

callFailedToConnectErrorMessage
uiErrorMessage
contactSupportTeamMessage

let callFailedToConnectErrorMessage = 'Call failed to connect. Service not available!';
let uiErrorMessage = {
'Default': 'Error occurred. Please try again!',
'Terminated': 'Call ended successfully!',
'Canceled': 'Call cancelled. Please try again!',
'Failed': callFailedToConnectErrorMessage,
'login failed': callFailedToConnectErrorMessage,
'disconnected': callFailedToConnectErrorMessage,
'logout': callFailedToConnectErrorMessage,
'SIP Failure Code': callFailedToConnectErrorMessage,
'RTP Timeout':  'RTP Timeout': 'The call ended unexpectedly due to network issues. Please ensure your internet is stable and try placing the call again!',
'Token Claims': 'An error occurred during the call attempt. Please retry!'
						}
let contactSupportTeamMessage = "We're sorry, could not connect the call. Please try again later or contact our support team!";

Configure location-based resources if you want to allocate the nearest resources to handle Click-to-Call requests. To do so, do the following in clicktocall.js:
1. Use the getAvailableLocations() function to return a list of locations where the required resources, such as Session Border Controllers (SBCs) are deployed. These locations help determine the best resource for processing Click-to-Call requests.
2. Integrate the location selection into the UI. You can do this in one of two ways:
  - User-selectable control: Provide a selectable element, like a drop-down or radio button, that allows contacts to select their nearest location from the options provided by the getAvailableLocations() function.
  - Automatic mapping: If the system can determine the contact's location, map it to one of the locations exposed by the getAvailableLocations() function and pass it to the makeCall() function.
3. Configure the default location. To do so, set the defaultLocation variable to the location your contacts most often call from. The default location must be one of the locations returned by the getAvailableLocations() function.
```
// Variable to store default location
let defaultLocation = "US";
```
Add the makeCall(contactAddress, [location], [userData], [routingData]) method to the Click-to-Call button. The location, userData, and routingData parameters are optional.

The userData, and routingData parameters pass user and routing data for use in routing decisions or for display in Agent. This is done as part of the SIP invitation request using X-headers. You can then process the data in the Studio script used for the point of contact.
- userData: Displays user-related information.
- routingData: Displays data used for routing decisions.
These parameters must be provided as objects containing key-value pairs. The SDK converts both objects into strings using JSON.stringify() and transmits them as X-headers in the SIP invite request:
- X-user-data: Contains the userData object.
- X-routing-data: Contains the routingData object.
userData and routingData are separate objects for the convenience of separating the data if you need to. However, you can pass all required data in only one of the parameters if you prefer. You can also transmit all data within a single X-header if your Studio script is configured accordingly.

Due to limitations on the size of data that can be passed in X-headers, the character length of each userData and routingData object should not exceed 1,000 characters (1 KB) after string conversion.

Refer to the following examples to configure it for your particular use case:
- Without passing any parameters:
```
makeCall(contactAddress);
```
- Passing only location:
```
makeCall(contactAddress, "US");
```
- Passing location, userData, and routingData:
```
makeCall(contactAddress, "US", { name: "Elizabeth Bennet", age: 20 }, { skill: "sales" });
```
- Passing only userData:
```
makeCall(contactAddress, undefined, { name: "John Doe", age: 30 }, undefined);
```
If you configured the makeCall() method to use the userData or routingData objects, you must process the X-header data in the Studio script associated with the Click-to-Call point of contact The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address. using these actions:
- SIPGetHeader action: Reads the data from the X-headers.
- RunApp action: Displays the data as a screen pop A pop-up window with information about the contact that appears on an agent's screen after an event such as connecting to a contact. in Agent when the call is connected.
- Snippet action: Parses the data from the X-header and routes calls based on that data.
To send DTMF tones, call the guiSendDTMF(digit) function when a DTMF button is clicked.
Test your configuration to ensure it can initiate and route calls successfully.