External Layer API

Extend the functionality of your Voicenter IVR and implement call routing based on the information in your organizational database or CRM systems in order to perform advanced routing of incoming calls.

 

GENERAL DESCRIPTION

 

Voicenter Request

 

With External IVR API, you can extend functionality of Voicenter IVR and connect it to your
organizational database or CRM systems in order to perform advanced routing of incoming calls.

For example, you can identify incoming call by phone number and determine if this is an existing client
or a new potential client, and perform different routing scenarios accordingly, such as:

 

  1. Caller number is registered as an existing lead: Your CRM can check if one of your sales
    representatives already spoke to this client and reply back with the layer of this
    representative in order to redirect the call directly to that specific sales representative.
    You want to do that in order to finalize sales process in a smoother more customer experience oriented
    IVR.
  2. Caller number is registered as an existing account: Your CRM can check if there is an
    ongoing open ticket/case and transfer the call to the right customer services
    representative/desk - in order to resolve the issue and provide personal service faster.
  3. Caller number does not exist in your CRM: Your CRM can transfer these calls to sales
    representatives or as an alternative you can ask from the client to provide some
    identification information in order to transfer the call to the right desk.
  4. In addition, callers can be asked to dial their personal ID, account number or anything else,
    and this data can be process by your organizational database or CRM systems in order to
    perform varied actions. These digits pressed during the navigation in the IVR are called
    DTMFs.

 

External IVR API utilizes existing layers of Voicenter IVR in order to route calls.
Further explanation about creating and managing IVR layer can be found at the end of this
chapter.

 

In order to utilize advanced features of the External Layer IVR, the system needs an end
point URL to address when calling the Layer. This URL can be managed in the Layer settings
tab.


Once the call is received, Voicenter IVR will initiate a POST request to this endpoint. This
request will contain the following information:

 

Reqeust Format

1. POST-JSON

 

Response Format

1. POST-JSON

 

Request Parameters

 

After implementing your endpoint in the relevant layer/s in your Voicenter IVR you will start receiving request with the following parameters:

Field Name Description Type
METHODWill always be "IVR_LAYER_INPUT".String
DATAData object of an IVR request.String
DIDDID number that the call was received on(Incoming number).String
CALLER_IDCaller ID of the current caller.String
IVR_UNIQUE_IDVoicenter unique ID of a call. Can be used for state purposes.String
DTMFIf the caller was requested to enter identification information, this input will be passed in this parameter.
*In case the caller did not enter any value(did not make any dial action), the default value will always be “0”.
String
LAYER_IDThe current layer ID in the IVR that the request is sent from.Integer
PREVIOUS_LAYER_IDIf the call was passed to the layer from another layer, the previous layer will be shown here.Integer

 

Reqeust Example

 

Below is an example of a request your endpoint will receive from the Voicenter IVR.

{
"METHOD": "IVR_LAYER_INPUT",
"DATA": {
"DID": "0722776772",
"CALLER_ID": "0501234567",
"IVR_UNIQUE_ID": "1bcd7954224861f85a2d70612f2",
"DTMF": "1234",
"LAYER_ID": 5,
"PREVIOUS_LAYER_ID": 5
}
}

 

Caller ID in this request can be used in order to check if there is an existing record in the
CRM. Also, the caller dial input(DTMF) can be used as well.

 

 

Client Response

 

Response Parameters

 

Once it you have received the request from Voicenter and processed your automated process, a response needs to be formulated and sent back to Voicenter as part of the HTTP protocol process.


The response must contain the following parameters:

 

Field Name Description Type Remarks
STATUS0 - OK.
1 - Error has occurred on client's side.
IntegerMandatory
ACTION1. GO_TO_LAYER - Will pass the call to a layer within a Voicenter IVR and continue as set in layer.

2. SAY – Will announce the caller with a data that was sent in this method and will then pass the call to a layer within a Voicenter IVR.
More info about the SAY method below.

3. DIAL - Will dial an external number or a Voicenter extension.
More info about the DIAL method below.
StringMandatory
LayerLayer number that the call will be redirected to.IntegerMandatory
CALLER_ NAMECaller name that will be shown on the destination phone (Supported only for Voicenter extensions).StringOptional
CUSTOM_ DATAInternal CRM information about the client that can be passed for pop-up screen or CDR logs purposes.StringOptional

Client Response (Without Custom Data)

 

Below is an example of a response with GO_TO_LAYER action, the response is without custom data.

 

{
"STATUS": 0,
"ACTION": "GO_TO_LAYER",
"LAYER": 12
}

Response With Custom Data

 

If you wish to send a response along with custom data can do so the following way:

 

{
"STATUS": 0,
"ACTION": "GO_TO_LAYER",
"LAYER": 22,
"CALLER_NAME": "Shlomi",
"CUSTOM_DATA": {
"CRM_cleint_ID": "12345",
"Last_ticket_ID": "222",
"Last_representative": "John Doe"
}
}

 

Case Example

 

You identify a caller by pressing their personal ID in a given Layer in the IVR (in this request example its "5").
Play the Layer recording (configured in the Cpanel incoming interface), asking the caller to press his ID
(in the following request example “12345678").
After the caller has finished pressing, we will send a JSON request as followed:

 

Case Example JSON Request

 

{
"METHOD": "IVR_LAYER_INPUT",
"DATA": {
"DID": "0722776772",
"CALLER_ID": "0501234567",
"IVR_UNIQUE_ID": "1bcd7954224861f85a2d70612f2",
"DTMF": "12345678",
"LAYER_ID": "5",
"PREVIOUS_LAYER_ID": "5"
}
}

 

The data on the "DTMF" field is the data that the caller pressed.
Next, we should get a Response indicating how the caller should be routed on the IVR.

 

Case Example JSON Response

 

{
"STATUS": 0,
"ACTION": "GO_TO_LAYER",
"LAYER": 12,
"CALLER_NAME": null,
"CUSTOM_DATA": null
}

In this response, the caller was transferred to layer "12" in the IVR.
When we setup the integration, we create in advance, all the IVR scenarios (layers) according to the account
preferences and business needs.
For example, layer "12" can be a layer indicating a successful caller identification and the caller will be
directed to your representatives.
If the identification of the caller was not successful, the caller can be
redirected to layer "13" where we can ask to press the ID again, or any other option desired.

 

Say Method

 

The SAY functionality of Voicenter external IVR service can be used to announce callers with dynamic data
from your external system.
For example, you can inform your clients regarding the status of their order or let them know the amount of
credits that currently left in their account, automatically through the IVR.
The initial request that is sent from Voicenter to your system is the same, as described above.
In order to use the "SAY" functionality we need to receive a response in the following format: POST- JSON.
Below is a table with the parameters you will need to use with a response example to provided afterwards.

 

Response Parameters

Field Name Description Type Remarks
STATUS0 - OK.
1 - Error has occurred on client's side.
StringMandatory
ACTIONSAY_DIGITSStringMandatory
NEXT_LAYERLayer number that the call will be redirected to after completing the announcement.IntegerMandatory
LANGUAGEThe language in which the client will hear the response:
1. HE – Hebrew.
2. EN – English.
3. AR – Arabic.
4. RU – Russian.
More languages can be supported upon request.
StringMandatory
DATAA data array contains the data that needs to be played to the caller.
Types of data:
1. Digits (integer) - The IVR will announce the data digit-by-digit. Example: a phone number.
2/ Number (integer) - The IVR will announce a number. Example: amount of credits left in the caller account.
3. Date (String) - The IVR will announce the date. Date in ISO 8601 format: YYYY-MM-DD. Example: 2019-12-14.
4. DateTime (String) - Announcement of date and time, ISO 8601 format, Example: 2019-12-14T10:12:59.
StringMandatory

Say Method Response Example

 

{
"STATUS": 0,
"ACTION": "SAY_DIGITS",
"NEXT_LAYER": 2,
"NEXT_LAYER_IF_FAILED": 1,
"LANGUAGE": "EN",
"DATA": [
{
"RecordType": "Recording",
"Content": "9899115_20849570029.mp3"
}
{
"RecordType": "Digits",
"Content": "0501234567"
}
{
"RecordType": "Number",
"Content": "112"
}
{
"RecordType": "Date",
"Content": "2019-12-14"
}
{
"RecordType": "DateTime",
"Content": "2019-12-14T10:12:59"
}
{
"RecordType": "Recording",
"Content": "98972915_209570029.mp3"
}
]
}

 

Say Method Response Explanation

 

The Digits, Number, Date and DateTime content will play in the language that was requested in the
“LANGUAGE” field.

In this case, the data will be announced in English(“EN”).


The IVR will play the caller the data content in the order it was sent:


1. The caller will hear the recording - 9899115_20849570029.mp3.
2. Then the IVR will play the digits “zero, five, zero, one, two, three, four, five, six, seven”.
3. After that the number "one hundred and twelve".
4. Date – “fourteenth of December two thousand nineteen".
5. Date and time – “fourteenth of December two thousand nineteen at ten and twelve minutes and
fourteen seconds”.
6. The caller will hear the recording - 98972915_20897670025.mp3.


After playing the data that was sent, the caller will be directed to the layer that was specified in
NEXT_LAYER. In this case, the call will be directed to layer 2.

 

Dial Method

 

The DIAL functionality of Voicenter external IVR service can be used to direct calls to an external phone
number or to a Voicenter extension.

For example, if your representatives are working with their personal mobile phones during night shifts and you wish to direct some calls to a specific representative mobile.
With the DIAL functionality you can easily do that.
The initial request that is sent from Voicenter to your system is the same, as described above.
In order to use the "SAY" functionality we need to receive a response in the following format: POST- JSON.
Below is a table with the parameters you will need to use with a response example to provided afterwards.

 

Response Parameters

 

Field Name Description Type Remarks
STATUS0 - OK.
1 - Error has occurred on client's side.
IntegerRemarks
ACTIONDIALStringMandatory
CALLER_IDThe phone number that will be shown to dialed destination. Example “0722776772”.StringMandatory
CALLER_NAMEA name that will be shown to the dialed destination.
Only if the destination is a Voicenter extension.
StringOptional
MAX_CALL_ DURATIONTotal duration of the call(seconds). Actual call not include dialing duration.IntegerMandatory
MAX_DIAL_ DURATIONTotal dialing duration of the call(seconds). Not include the actual answered call duration.IntegerMandatory
NEXT_VO_IDIn case of the destination is not reachable, the Voicenter IVR layer that the call will be directed to.
Important- it does not include busy\voicemail\dialed to the destination and the destination did not answer.
Only in cases of some kind of malfunction with the destination.
IntegerMandatory
RECORDINGWhether to record the call? Accepts: “yes” or “no”.
The default behavior is not to record the call.
StringMandatory
TARGETSA data array that contains the requested call destination:
TYPE - accepts “PHONE” or “EXTENSION” (Voicenter Extensions). Value is case sensitive.
TARGET – accepts phone number or Voicenter extension SIP code.
Phone numbers outside Israel must be sent with international prefix.
StringMandatory
CUSTOM_ DATAInternal CRM information about the client that can be passed for pop-up screen or CDR logs purposes.StringMandatory

 

Dial Method Response Example

 

{
"STATUS": 0,
"ACTION": "DIAL",
"CALLER_ID": "0722776772",
"CALLER_NAME": "Voicenter",
"MAX_CALL_DURATION": 1800,
"MAX_DIAL_DURATION": 60,
"NEXT_VO_ID": 15,
"RECORDING": "yes",
"TARGETS": [
{
"TYPE": "PHONE",
"TARGET": "0501234567"
}
]
"CUSTOM_DATA": {
"CRM_cleint_ID": "12345",
"Last_ticket_ID": "222",
"Last_representative": "John Doe"
}
}

 

External Layer API – Setting Up Layers

 

General Description

 

Each layer in Voicenter IVR can direct the call to one of the following methods:

  1. Call – dial 1 or more extensions or external destinations. Once the first destination
    answers – it stops ringing the other destinations.
  2. Layer – transfer the caller to another IVR Layer.
  3. Queue – Transfer the caller to a Queue in the system.

IVR structure and Layers settings are configurable from Voicenter Cpanel, in the “Incoming
interface”.

Creating Layers to be used in the External IVR API is done in Voicenter Cpanel.


Once the IVR flow was determined and you finished creating the endpoint, please log in to Voicenter Cpanel.


Go the Settings -> DIDs -> click the IVR column of the desired DID to open the Incoming interface.

In this page – press the Layers menu (the puzzle icon), and click the layer to configure:

 

 

Under the "Layer settings" tab check "Allow mini external IVR" checkbox and configure
the following options:
MiniExternalUrl - Your system endpoint URL for this layer. This is where we are sending
you the request:

 

 

MiniExternalDTMFLen - If your IVR requires an input from the caller(DTMF), determine
what’s the maximum digits allowed. Once this limit has been reached the Request will be
sent.

Delay - When requesting a caller to dial digits – it usually takes a few seconds. Use this
field to determine how many seconds after the announcement the system will wait before
timing out(valid delay values are 1-9).

 

 

The IVR will finish waiting for one of the following:
1. The caller response until it reaches the max digits input ("MiniExternalDTMFLen" field).
2. The delay timeout (seconds configured in "Delay" field) has passed.

 

MiniExternalDefaultMethodData - Select a failover layer in case the endpoint configured in
MiniExternalUrl fails or times out.
If there is a problem to reach your endpoint, in order to prevent losing calls to
simply hung-up because of malfunction, we usually configure a default layer so calls will be directed to it.