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:
- 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. - 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. - 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. - 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 |
| METHOD | Will always be "IVR_LAYER_INPUT". | String |
| DATA | Data object of an IVR request. | String |
| DID | DID number that the call was received on(Incoming number). | String |
| CALLER_ID | Caller ID of the current caller. | String |
| IVR_UNIQUE_ID | Voicenter unique ID of a call. Can be used for state purposes. | String |
| DTMF | If 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_ID | The current layer ID in the IVR that the request is sent from. | Integer |
| PREVIOUS_LAYER_ID | If 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.
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 |
| STATUS | 0 - OK. 1 - Error has occurred on client's side. | Integer | Mandatory |
| ACTION | 1. 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. | String | Mandatory |
| Layer | Layer number that the call will be redirected to. | Integer | Mandatory |
| CALLER_ NAME | Caller name that will be shown on the destination phone (Supported only for Voicenter extensions). | String | Optional |
| CUSTOM_ DATA | Internal CRM information about the client that can be passed for pop-up screen or CDR logs purposes. | String | Optional |
Client Response (Without Custom Data)
Below is an example of a response with GO_TO_LAYER action, the response is without custom data.
Response With Custom Data
If you wish to send a response along with custom data can do so the following way:
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
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
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 |
| STATUS | 0 - OK. 1 - Error has occurred on client's side. | String | Mandatory |
| ACTION | SAY_DIGITS | String | Mandatory |
| NEXT_LAYER | Layer number that the call will be redirected to after completing the announcement. | Integer | Mandatory |
| LANGUAGE | The 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. | String | Mandatory |
| DATA | A 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. | String | Mandatory |
Say Method Response Example
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 |
| STATUS | 0 - OK. 1 - Error has occurred on client's side. | Integer | Remarks |
| ACTION | DIAL | String | Mandatory |
| CALLER_ID | The phone number that will be shown to dialed destination. Example “0722776772”. | String | Mandatory |
| CALLER_NAME | A name that will be shown to the dialed destination. Only if the destination is a Voicenter extension. | String | Optional |
| MAX_CALL_ DURATION | Total duration of the call(seconds). Actual call not include dialing duration. | Integer | Mandatory |
| MAX_DIAL_ DURATION | Total dialing duration of the call(seconds). Not include the actual answered call duration. | Integer | Mandatory |
| NEXT_VO_ID | In 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. | Integer | Mandatory |
| RECORDING | Whether to record the call? Accepts: “yes” or “no”. The default behavior is not to record the call. | String | Mandatory |
| TARGETS | A 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. | String | Mandatory |
| CUSTOM_ DATA | Internal CRM information about the client that can be passed for pop-up screen or CDR logs purposes. | String | Mandatory |
Dial Method Response Example
External Layer API – Setting Up Layers
General Description
Each layer in Voicenter IVR can direct the call to one of the following methods:
- Call – dial 1 or more extensions or external destinations. Once the first destination
answers – it stops ringing the other destinations. - Layer – transfer the caller to another IVR Layer.
- 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.