GENERAL DESCRIPTION
If you wish to store and document the call detail records including the url for the call recording in your client's page inside your CRM system this is the API for you.
This api will also enable you to do further automated processes such as:
1. If you are using a queue and once you receive a call detail record when a client abandoned the call while waiting in the queue you may send an sms or a whatsapp to the client and/or popup a notification to the call center manager to callback the client.
2. Based on the received information you may analyze your call center performance as part of organizational business logic:
- You will be able to exam which agents answer the most incoming calls.
- Which agents produce the most answered outgoing calls.
- In case you are performing outgoing calls to a variety of countries you can analyze which countries have the best answer ratio.
- You will be able to view what are you peak hours in which you receive the biggest amount of incoming calls, and much more.
How Does The API Work?
1. A call is made to\from your Voicenter call center. After the call has ended, Voicenter
converts the call data into a CDR.
2. Voicenter will send an HTTP request with your call data (CDR) to a Web-Service that
was provided to us.
3. HTTP response will be sent back to Voicenter (HTTP response status code: 200 OK), in order to acknowledge us that the data was received.
Request Parameters
1. POST-JSON
2. XML-RPC
3. Application/x-www-form-urlencoded
Response Parameters
1. POST-JSON
2. XML-RPC
3. Application/x-www-form-urlencoded
Voicenter Request - CDR Parameters
| Field | Description | Example |
| caller | Displays the caller’s phone number. The phone number that will show to the call destination. | "caller":"0722776772" |
| target | Displays the destination of the call. Can be a phone number or the extension SIP code. The phone number value will be sent with the international country prefix. | "target":"SIPSIP" / "target":"972722776772" |
| time | Displays the time that that the call was made in Epoch time (Israel time zone). | "time":1536855354 |
| duration | Displays the duration of the call(seconds). This duration does not include the ringing duration, only the actual time of the conversation that was made. | "duration":33 |
| ivruniqueid | Displays the ID code of the specific call. | "ivruniqueid":"20200720095iMlilHJs" |
| type | Displays the type of Call. For example: if it is an incoming/outgoing call? There are several call types(More details are in the next pages). | "type":"Incoming Call" / "type":"Extension Outgoing" / "type":"Click2Callleg1" |
| status | Displays what happened with the specific call? If the call had 2 "legs", this field will show the status of the leg 2 part of the call call(call types: Click2call, Automatic Dialer calls). There are several call statuses(More details are below. | "status":"ANSWER" / "status":"ABANDONE" / "status":"TE" |
| leg1DialStatusName | If the call had 2 legs, this field will show the status of the leg1 part of the call(call types: Click2call, Automatic Dialer calls). There are several call statuses(More details are in the next pages). | "leg1DialStatusName": "ANSWER"/ "leg1DialStatusName": "ABANDONE" / "leg1DialStatusName":"TE" |
| targetextension | Displays the extension SIP code that answered the incoming call. Sometimes this value will be identical to the "target" field. There are cases that the incoming call is received not directly to the extension, so the "target" can display different values. | "targetextension":"SIPSIP" |
| callerextension | Displays the extension SIP code that the call was dialed from. This value is different from the "caller" field. In the "caller" field we display the actual number that will appear to the call destination. | "callerextension":"SIPSIP" |
| did | Displays the origin phone number that the caller called to. This parameter will show value only on incoming calls. | "did":"0722776772" |
| queueid | If the call was directed to a queue service, it displays the queue code ID. The value of the field will be null in case there is on queue. | "queueid":1234567 |
| queuename | If the call was directed to a queue service, it displays the queue name. | "queuename":"Service Queue" |
| record | Displays the URL link to the call recording. | "record":"https://cpanel.voicenter.co.il/CallsHistory/PlayRecord/2022071916331502463359186d8ab5f5-aws-APIAPI-0722776772.mp3" |
| price | Displays the total price of the call in ILS cents (Agorot). | "price":7 |
| dialtime | Displays the ringing duration of the call(seconds). Not include the actual conversation duration. | "dialtime":23 |
| representative_name | Displays the Voicenter user name that the specific call was associated with. If a user was not logged in when the call was made, then this field will show the user name that the extension\DID is associated with. | "representative_name": "Walter Melon" |
| representative_code | Displays the Voicenter user ID code that the specific call was associated with. If a user was not logged in when the call was made, then this field will show the user name that the extension\DID is associated with. | "representative_code":"9996" |
| targetextension_name | Displays the Voicenter extension name that answered the specific call. | "targetextension_name": "Walter Melon" |
| callerextension_name | Displays the Voicenter extension name that this specific call was made from. | "callerextension_name": "Walter Melon" |
| target_country | Displays the country name that this outgoing call was made to. | "target_country":"Israel" |
| caller_country | Displays the country name that this incoming call was made from. | "caller_country":"Israel" |
| seconds_waiting_in_ queue | This field will only be sent, if the specific call was directed to a queue. It displays the duration (seconds) that the caller waited in the queue. | "seconds_waiting_in_queue":5 |
| OriginalIvrUniqueID | This field will only be sent if a specific call was related to another call. It displays the origin call code ID – "ivruniqueid". For example, when calls are transferred in the organization between representatives. | "OriginalIvrUniqueID": "201809131730110122A1212" |
| DepartmentName | Displays the department\account name(as it appears in Voicenter) that the call was associated with. | "DepartmentName": "Voicenter Account" |
| DepartmentID | Displays the department\account ID(as it appears in Voicenter) that the call was associated with. | "DepartmentId":123456 |
| TopDepartmentName | If the given account has a hierarchy, this field will display the name of the top account in the hierarchy. | "TopDepartmentID": "Voicenter Top Account" |
| TopDepartmentID | If the given account has a hierarchy, this field will display the ID of the top account in the hierarchy. | "TopDepartmentID":7654321 |
| IVR | An array type field. Displays the stages in the IVR that an incoming call went through. Fields: "layer_id" - The IVR layer Voicenter unique ID. "layer_name" – The IVR layer name as it appears in the Voicenter control panel (CPanel). "DTMF" – If the caller pressed on a digit\s. If the caller did not press an any digit the default value will be “0”. "LayerNumber" - The IVR layer ID. "dtmf_order" – The layer order that the call went through in the IVR. | "IVR": "[{ \"layer_id\":1234567, \"layer_name\":\"LayerName\, \"layer_number\":6, \"Dtmf\":0, \"dtmf_order\":1 }]" |
Call Types
| CDR Type Name | Description |
| Incoming Call | A regular incoming call that was dialed to a phone number and ended up in the IVR or an extension (did not end in a queue, which will make it type 4). |
| CC | A call that was made through a calling card (Access number) service. |
| Extension Outgoing | A regular outgoing call (manually dialed from the phone). |
| Queue | An incoming call that was received by a queue. |
| Click2Call leg1 | A call that was made by click2call (Not by Dialer), leg 1 of the call. Leg 1 - the initial connection of the call to the extension. This is the “Phone” parameter in the Click2call API. This part will contain info about the initial connection of the call. |
| Click2Call leg2 | A call that was made by click2call (Not by Dialer), leg 2 of the call. Leg 2 - the actual call that is being made to the destination. This is the “Target” parameter in the Click2call API. This part will contain the call details and call recording. |
| VoiceMail | A call that was answered by Voicenter voicemail. |
| Callference | A call that was made through Voicenter callference service. |
| XferCDR | A call that manually transferred from an extension to a DID/another extension. |
| ProductiveCallLeg1 | A "leg 1" Agents Auto Dialer calls. Leg1 - the initial connection of the call to the extension. This part will contain info about the initial connection of the call. |
| ProductiveCallLeg2 | A "leg 2" Agents Auto Dialer calls. Leg 2 -the actual call that is being made to the destination. This part will contain the call details and call recording. |
| Scrubber | A call that was made through Voicenter's Scrubber service. |
| Click 2 IVR | "Leg1" Predictive Dialer calls. Leg1 - the initial connection of the call to the destination. This part will contain info about the initial connection of the call. |
| Click 2 IVR Incoming | This is the "Leg 2" Predictive Dialer call. After the initial Leg1 (Click 2 IVR) call was answered, this new leg is dialing the IVR (a layer in Voicenter telephony menu) and Leg 1 is connected to the representatives. This call type is for all Click 2 IVR that did not enter a queue. If the call enters a queue service, the type will be type 15. This part will contain the call details and call recording. |
| Click 2 Queue Incoming | This is the "Leg 2" Predictive Dialer call. After the initial Leg1 (Click 2 IVR) call was answered, this new leg is dialing the IVR (a layer in Voicenter telephony menu) and Leg 1 is connected to the representatives. If the call enters a queue, then the call status will be - Click 2 Queue. Else, the call type will be type 14. This part will contain the call details and call recording. |
| FaxCdr | A call that was made through Voicenter's internal outgoing fax service. *Not released yet. |
| Attended CDR leg1 | A call that was transferred with consultation. |
| Attended CDR leg2 | A call that was transferred with consultation. This type will only be made in a case of an incoming call that was answered by representative "A", "A" will then put the call on hold and make another call (consult) to another person - "B". Afterward, "A" will transfer the initial call to "B". The "Leg 2" is the part of the call between "B" and the initial caller. |
| Auto forward | A call that was automatically transferred from an extension to a DID (usually representatives configure their phones manually to transfer calls when they are not available). |
Leg 1 & Leg 2 Call Types
In some call types, each call consists of two parts arranged in chronological order:
1. Click2Call – The first part of the call (Leg1) is the initial connection to the user extension. If the initial connection was established, then the
actual call to the destination is being made (Leg2).
2. Productive Dialer – The first part of the call (Leg1) is the initial connection to the user extension. If the initial connection was established, then
the actual call to the destination is being made (Leg2).
3. Predictive Dialer – The first part of the call (Leg1) trying to call the destination. If the initial connection was established to the call destination,
then the call is connected to your call center (Leg2).
The Leg2 call parts are often used because it is the actual call to the destination. Sometimes, in the case of Leg2 call part that failed to connect to
the destination (call status – NOTCALLED), the Leg1 part can show the reason that the call did not connect to the extension.
Call Statuses
| CDR Status Name | Description |
| NOTDIALED | Hang-up occurred before the call was made. |
| ANSWER | A call was answered. A successful dial. The caller reached the destination. Whenever we receive an answer response signal, also when the call reached local voicemail service and etc. |
| BUSY | Busy signal. The dial command reached its number but the number is busy. |
| NOANSWER | No answer. The dial command reached its number, the number rang for too long, then the dial timed out |
| CANCEL | A call is canceled. The dial command reached its number but the caller hung up before the call destination could answer. |
| ABANDONE | When using Voicenter's queue service, this status will appear in several cases: A caller hung up before the call destination could answer. A caller while waiting in the queue, chose to exit from the queue. A call has reached timeout in the queue. |
| VOEND | Hang-up during IVR without actual dialing. In this case, the caller waited in the IVR but hung up before the call rang in any extension. |
| TE | When an incoming call is directed to an IVR recording and afterward it configured to hung up the call. |
| NOTCALLED | A Leg2 Click2Call was not called. When using a click2call service and the Leg1 initial stage was not successful (not answered). |
| VOICEMAIL | Call entered to Voicenter voicemail service. |
Call Error Types
There maybe be time where while trying to make an outgoing call to certain destination you will receive an error. These error responses display cases when there was a problem connecting to the target destination.
It is mainly used for Voicenter internal Tracking.
The errors you may receive are as followed:
| Error Types | Error Description |
| CONGESTION | Congestion. This status is usually a sign that the dialed number is not recognized. |
| CHANUNAVAIL | Channel unavailable. On SIP, peer may not be registered. |
| INVALIDARGS | Error parsing dial command arguments. |
| SSWPREAUTH | SSW outgoing call cancel before actual dial. |
Client Response
It is important that we get a feedback to understand that all data was received.
In case, we do not receive a valid response we will re-send the CDR data that we failed to send.
The amount of retries and the time intervals between retries are set on Voicenter side.
| Name | Type | Exmple | Description |
| Err | Integer | 0 | Error codes: 0 – OK 1 – Parse error 2 – Application error |
| Errdesc | String | OK | Error description |
JSON Example (Outgoing Call):
In this example, a user (User 1) made an outgoing call from extension (SIPSIP), the call was dialed manually from the extension (not through Auto-Dialer or Click2call services).
The user called the phone number - "0501234567", the phone number that appeared to the call destination was - "0722776772".
This call was answered ("ANSWER").
The call rang 2 seconds, and the duration of the conversation was 11 seconds.
JSON Request Example (Incoming Call):
In this example, an incoming call was made from - "0501234567", the caller called the phone number "0722776772".
This call went through the IVR, first, on the "Main IVR" layer which then the caller pressed "2" and was directed to the
second layer – "Sales Department".
This call rang in the queue service ("Queue") name - "Sales Queue".
The caller waited in the queue for 20 seconds and decided to hang-up the call ("ABANDONE").