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.
3. Along with our powerful AI processor you will be analyze your calls in more advanced manner, such as:
- Receive the call's transcript to allow you to track key moments in the call easily.
- You could view the emotions expressed in the call by your agents and your clients and their positive/negative emotional volatility.
- The entire info from our AI processor will allow you to measure your support agent's or salesmen much more efficiently coupled with the info from your CRM (amount of ticket closed/leads converted).
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 }]" |
decriptai_uuid | Unique identifier of the AI transaction. | "decriptai_uuid":"110b22e33344ddf6ca777a88a9dc0e2", |
aiData | JSON object that shows the entire AI for the call. | { "aiData":{ "job_id":"110b22e33344ddf6ca777a88a9dc0e2", "call_data":{ "id":"5397bc37-3141", "timestamp":"2023-09-11T14:46:16.257Z", "speakers":[ ] }, "keyId":2245, "transcript":[ { "text":"וויסנטר שלום מדבר ניסן במה אוכל לעזור", "start":2.26, "end":6.02, "end_time":8, "speaker":"0", "emotion":"cheerful" }, { "text":"כן בסדר מה העניינים", "start":3.8, "end":8.045, "end_time":10.24, "speaker":"1", "emotion":"cheerful" } ] } } |
job_id | Unique ID of the job done by the AI. | "job_id":"110b22e33344ddf6ca777a88a9dc0e2", |
call_data | A JSON object that displays the serial identifier of the call, a time stamp and the number of participants in the call. | "call_data":{ "id":"5397bc37-3141-4313-a3c6-8f76166139a8", "timestamp":"2023-09-11T14:46:16.257Z", "speakers":[ ] } |
id | A parameter within the call_data object that displays the unique identifier of the call. | "id":"5397bc37-3141-4313-a3c6-8f76166139a8", |
speakers | An array with the numbering of the participants in the conversation, each number represents one participant. | "speakers":["0","1","2","3"] |
keyId | Numeric ID for Voicenter internal use. | "keyId":1111 |
transcript | An array of JSON that contains the transcript of the conversation according to the sentences of each participant in the conversation.. | "transcript":[ { "text":"Voicenter hello this is Nisan speaking", "start":2.26, "end":6.02, "end_time":8, "speaker":"0", "emotion":" neutral" } ] |
text | The text spoken in the conversation by one of the participants. | "text":"Voicenter hello this is Nisan speaking" |
start | Shows the timestamp in the conversation when the participant started saying the sentence. | "start":2.26 |
end | The timestamp in the conversation when the sentence ended. | "end":6.02, |
end_time | The duration of the spoken sentence. | "end_time":8, |
speaker | Serial number of the participant in the call. | "speaker":"0" |
emotion | This field indicates the emotion in which the sentence was said by the participant. | "emotion":"cheerful" |
insights | A JSON object that shows insights from the AI about the conversation, insights such as: general conversation summary. conversation summary by chapter heads. | "insights":{} |
summary | Another object that contains the general conversation summary. | "summary":{ "result":[ "השיח הזה כולל משוב מלקוח שמתאים ללקוחות ולנציג. במהלך השיח, הלקוח טוען gk קיום בעיות באינטרנט שלו. הנציג מודה בבעיות ומבטיח לבדוק את העניין ולנסות לסייע.]} |
result | A parameter that contains the call summary | "result":["This conversation includes feedback from a customer and a representative. During the conversation, the customer claims an internet problem in the office. The representative promises to look into the matter and try to help. To the customer's delight, he speaks with this representative who succeeded Solve the problem."] |
error | Displays whether there was an error in the process of summarizing the call. If there is no error, the parameter will display null. | "error":null |
problems | A JSON object that shows problematic key points in the conversation. For example, points in the conversation when the customer complained about a problem and receiving a solution from the representative. | "problems":{} |
result | "result":[ { "title":"Internet problems", "messages":[ ] } ] | |
title | A title showing the main topic of the conversation. | "title":"Internet problems" |
messages | A JSON array that shows sentences and important points about the topic of the conversation said by one of the participants during the conversation. | "messages":[ { "problem_source":"Internet Problems", "start":0.036, "end":0.644, "speaker_id":1, "solved":true, "solution_start":0.64, "solution_end":2.486 , "resolution_summary":"Router is turned off, "solving_time":null, "solving_time_ratio":null } ] |
problem_source | The source of the problem the customer complained about. | "problem_source":"Turning on the router", |
start | The start time of the sentence is a key related problem. | "start":0.036, |
end | End time key sentence related problem. | "end":0.644, |
speaker_id | The participant who said the key sentence. | "speaker_id":1, |
solved | Is the problem solved? | "solved":true, |
solution_start | The start time of the solution in the conversation. | "solution_start":0.64, |
solution_end | End time of the solution in the conversation. | "solution_end":2.486, |
resolution_summary | A brief summary of the proposed or implemented solution. | "resolution_summary":"Router was turned on", |
solving_time | How long did it take to solve the problem? | "solving_time":6.315, |
solving_time_ratio | The time ratio in which the fault was resolved. | "solving_time_ratio":null |
topics | A JSON object that shows the main topics in the conversation. | "topics":{ "result":[ "ups", "internet ", "router" ] } |
result | Displays keywords in the conversation that are related to the solution to the problem presented by the customer. | "result":[ "router", "modem", "ups" ] |
metrics | A JSON object that shows various metrics that the AI has regarding the conversation. You can see more detail about the metrics below. | "metrics": { "overall": { } } |
total_call_duration | Total call duration time in seconds. | "total_call_duration":166.339, |
speaker_to_silence_ratio | A JSON object that shows the ratio between talk time and quiet time of each participant in the conversation. The object will specify the ratio for each participant by their ID (0,1 etc). | "speaker_to_silence_ratio":{ "0":1.3940357793507159, "1":2.308343135434078 } |
total_speech_to_silence_ratio | The field shows the ratio of speech to absolute silence. | "total_speech_to_silence_ratio":0.38894520251245407 |
speaker_speech_ratio | Relative time in which each participant in the conversation spoke. | "speaker_speech_ratio":{ "0":0.4025874869994408, "1":0.29132674838732947 } |
simultaneous_speech_time | The amount of time that the participants in the conversation spoke at the same time. | "simultaneous_speech_time":11.942999999999994, |
simultaneous_speech_ratio | The ratio of time the participants spoke at the same time. | "simultaneous_speech_ratio":0.071799157142943, |
csat_rate | Satisfaction index of the conversation participant. | "csat_rate":{ "0":4, "1":5.833333333333333 }, |
dsat | A measure that shows the dissatisfaction of a participant in the conversation. | "dsat":{ "0":0.6, "1":0.4166666666666667 } |
interruption_count | The number of times each participant in the conversation interrupted another participant. | "interruption_count":{ "0":2, "1":5 } |
interruption_rate | The rate of interruption of each user. | "interruption_rate":{ "0":0.029865902099572926, "1":0.1031800078416806 } |
emotional_volatility | Emotional volatility of each participant in the conversation. This means the amount of change in emotions during the conversation of each participant. | "emotional_volatility":{ "0":2.8571428571428568, "1":3.6363636363636367 } |
emotional_evolution | Was the change in emotion positive or negative for each participant in the conversation. | "emotional_evolution":{ "0":-0.04653854194665952, "1":0.05437586413256579 } |
emotional_phrases | Key sentences said and their association with the emotion in which they were said. | "emotional_phrases":{ "0":{ "cheerful":[ "Vicenter hello speaking Nissan, how can I help you" ], "neutral":[ "Are the modem and router connected to electricity right now" ], "hopefull":["Let's wait A few seconds and we'll see if the internet comes back"] }, "1":{ "frustrated":["Yes, there is a modem here and I see it's not on either"], "stressed":[ "We can't make calls" ], "cheerful ":[ "One of the representatives has already received an incoming call" ] } } |
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. |
ProductiveCall Leg1 | 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. |
ProductiveCall Leg2 | 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").
Request Example With AI