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). For regular incoming calls this duration does not include the ringing duration, only the actual time of the conversation that was made. For calls of type queue this parameter will include also the waiting time of the call in the queue. | "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 }]" |
aiData | JSON object that shows the entire AI data for the call. Contains these objects: insights, emotions and transcript. The service is currently supported in Hebrew and English. To add additional languages, please send a request to the Voicenter support department. | |
insights | This object contains the data analysis of the call. It contains questions(AI prompts), the call summary, and the participants' analysis. | "insights":{ "questions":[ { "key":"category", "question":"Categorize the call to exactly one of the possible categories:“technical issue”,“billing issues”,“general support issues”", "answer":"technical issue" } ], "participants":{ "caller":{ "name":null, "personality_traits":[] }, "callee":{ "name":"Steve", "personality_traits":[] } }, "summary":"The caller had clash phone service issue. Steve tried troubleshooting steps like restarting the phone and resetting network settings, which solved the issue." } |
questions | This array contains an object of the questions(prompts) that the AI engine will analyze. It contains: key - the name of the current category. question - the prompt question. data_type - the classification of the returned value type of the AI analysis(text, number, array, etc.). answer - the return value of the AI service analysis. The questions can be managed in the Cpanel in Account Management advanced settings. | { "questions": [ { "key": "category", "question": "Categorize the call to exactly one of the possible categories: “technical issue”, “sales”, “other issues”", "data_type": "string", "answer": "technical issue" }, { "key": "issue", "question": "What was the technical issue?", "data_type": "string", "answer": "The caller was experiencing issues with their phone service." } ] } |
key | The category name of each question. | "key": "call_type" |
question | The prompt question for the AI engine to analyze. | "question": "Categorize the call to exactly one of the possible categories: “technical issue”, “billing issues”, “general support issues”, “sales”, “other issues”" |
data_type | The data type that the response answer field will be. The data types are: 1-boolean, 2-string, 3-number, 4-json array, 5-json object list, 6-json object | "data_type": "string" |
answer | The question returned value. | "answer": "technical issue" |
participants | This object analyzes the caller and the callee's personality traits. It contains objects for the caller and the callee with each name(if recognized) and each person's traits. | { "participants": { "caller": { "name": null, "personality_traits": [] }, "callee": { "name": "Steve", "personality_traits": [ "professional", "patient", "trying to explain clearly" ] } } } |
name | The name of the call\callee. | "name": "Steve" |
personality_traits | An array that contains the personal characteristics of the caller and the callee. | "personality_traits": [ "professional", "patient", "trying to explain clearly" ] |
summary | Summarize the transcript of the conversation in a few lines. | "summary": "The customer wanted to exchange virtual numbers and purchase a new virtual number. The representative helped the customer change 7 virtual numbers and purchase 1 new virtual number, a total of 8 new numbers. The representative explained to the customer the costs involved and the customer approved the costs. In the end, the representative confirmed that he would email the new numbers to the customer." |
emotions | This object contains the emotional analysis of the caller and callee. The AI engine returns each sentence and the emotion associated with it. The size of this object can vary. It depends on the length of the call and the ability of the AI engine to recognize each sentence's emotions(there may be sentences in which no distinct emotion was detected). | { "emotions":{ "sentences":[ { "sentence_id":28, "emotion":"frustrated", "emotion_direction":-1, "confidence_emotion":0.88, "intensity_emotion":0.75, "personality_trait":"impatient", "confidence_trait":0.85 }, { "sentence_id":34, "emotion":"professional", "emotion_direction":1, "confidence_emotion":0.92, "intensity_emotion":0.85, "personality_trait":"helpful", "confidence_trait":0.88 } ] } } |
sentences | This array contains objects of each sentence that the AI engine succeeded in recognizing an emotion. | {"sentence_id": 28, "emotion": "frustrated", "emotion_direction": -1, "confidence_emotion": 0.88, "intensity_emotion": 0.75, "personality_trait": "impatient", "confidence_trait": 0.85 }, {"sentence_id": 34, "emotion": "professional", "emotion_direction": 1, "confidence_emotion": 0.92, "intensity_emotion": 0.85, "personality_trait": "helpful", "confidence_trait": 0.88 }, |
sentence_id | Each transcripted line of the call has an ID starting from 0. | "sentence_id": 56 |
emotion | The recognize emotion of the sentence. | "emotion": "frustrated" |
emotion_direction | This field gives a numeric direction of sentence emotion: 1: positive, -1: negative, 0: neutral. | "emotion_direction": -1 |
confidence_emotion | The AI engine numerically evaluates (between 0-1) how likely the emotion it detected is correct. | "confidence_emotion": 0.92 |
intensity_emotion | The AI engine numerically evaluates (between 0-1) the level of intensity of the detected emotion. | "intensity_emotion": 0.8 |
personality_trait | The recognized personality trait of the sentence. | "personality_trait": "patient" |
confidence_trait | The AI engine numerically evaluates (between 0-1) how likely the trait it detected is correct. | "confidence_trait": 0.82 |
transcript | The full call transcript. It contains all sentences separated into objects. | { "speaker": "Speaker0", "text": "H: Good afternoon", "startTime": 1.87, "endTime": 1.89, "sentence_id": 0 }, { "speaker": "Speaker0", "text": "thank you for calling voice and support", "startTime": 3, "endTime": 5.2, "sentence_id": 1 } |
speaker | Speaker0 is the representative. Speaker1 is the client. | { "speaker": "Speaker0", "text": "how can i assist you today", "startTime": 8, "endTime": 9.64, "sentence_id": 3 }, { "speaker": "Speaker1", "text": "hi i'm having some issue", "startTime": 13.46, "endTime": 13.48, "sentence_id": 4 } |
text | The transcript text of the current sentence. | "text": "how can i assist you today" |
startTime | The start time of the current sentence. In seconds, since the conversation started. | "startTime": 8 |
endTime | The end time of the current sentence. In seconds, since the conversation started. | "endTime": 9.64 |
sentence_id | Each transcripted line of the call has an ID starting from 0. | "sentence_id": 3 |
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