EPICODE iraCPA API
Version- v1.2
Date: 14th Jan 2023
─
1 Overview
The Epicode iraCPA API allows users to do call progress analysis for their dialer applications. With these API one can:
Determine if a call is answered by an answering machine, live voice or fax machine.
Listen to specific frequency tones like beeps from an answering machine.
Stop the analysis upon receiving one of these events.
Each API is a json body request over a websocket connection. The following sections describe the json request and response, and how to send the RTP data.
2 API Interface
The API interface is over a websocket connection. The API caller just needs to know the IP address and the port number to connect to the iraCPA service. The url could be http://IP_ADDRESS:PORT. The deployment can contain multiple EC2 instances or multiple physical servers running iraCPA software on Hive, a HA framework from Epicode. The load balancing can be achieved either by using a floating IP address or by using round-robin across all the servers.
If the port number is an even number, use plain websocket. If the port number is an odd number, use a secure websocket.
3 Detection Mechanism
Epicode’s iraCPA works by analyzing the speech pattern of the voice. There is no objective way to separate an answering machine greeting from a live voice, unless a pure tone (single frequency) is detected. Therefore a collection of methods are used, and whichever method scores a strike within the time limit determines if the voice is live or a recording.
IraCPA promises to determine the AMD result in mere 1750 milliseconds. This is very important to meet the compliance requirements from TCPA or PECR. This is not offered by competitors of iraCPA, they just let the customers pick the timeout and other tuning values. Meanwhile, iraCPA engine comes pre-tuned to deliver best possible determination within 1750 milliseconds.
- iraCPA is language agnostic. It doesn’t depend on the callee saying Hello in any language. It only looks at the speech pattern and energy density that matches either a recording greeting or live voice. The pattern recognition logic is proprietary. This is a stochastic algorithm and not a deterministic one. The accuracy is consistently above 80%, however we have heard customers reporting above 90% in some installations.
- iraCPA also looks for pure tone that indicates non-human source. Human voice is a collection of harmonic frequencies, each of low energy. A pure tone will have very high energy in comparison to other harmonic frequencies. If a pure tone is detected, live voice can be ruled out. The iraCPA can be configured to look for many pure tones, to support many different voicemail providers and fax devices with well known tones. This only works if the tone is present in the initial 1750 milliseconds.
- iraCPA also detects perfect/ambient silence and has tuning parameters to ignore the initial silence. In addition, it can detect ambient silence beyond the initial 1750ms, and can send silence detection events. If the called party is silent for the entire 1750ms, it is interpreted as a live voice, since answering machines usually respond by that time.
4 Set CPA parameters
This API allows configuration of the various parameters which controls the behaviour of the call progress analysis engine. Some prominent configurations that can be set are:
Time limit for first detection, that LV or AM.
The specific frequencies to detect other than identifying humans and answering machines.
The detection event on which the CPA engine can stop the analysis.
Total analysis time limit.
4.1 Request Body (json)
Use text mode in the websocket to send this json request. Keep listening to any replies asynchronously.
Key |
Description |
Example |
Default |
|
request_name REQUIRED | string |
Specify the request name |
request_set_cpa_config |
None |
|
tenant_id REQUIRED | string |
Name of the licensee |
acme |
None |
|
api_version REQUIRED | string |
Currently use 1.1 |
1.1 |
None |
|
config_name REQUIRED | string |
Unique name for the configuration |
“my_setup” |
None |
analysis |
Name of the call progress analysis |
amd |
None |
|
min_ambient_energy integer |
Threshold that separates perfect initial silence and ambient silence |
1 |
1 |
|
initial_silence_ignore integer |
If the energy level is lower than minimum ambient energy, ignore the RTP packets |
5000 |
750 |
sensitivity |
Just use the value 5 for now |
4 |
4 |
|
tones object(key, value pairs) |
The single tone frequencies to be detected and the tolerance levels for each frequency. This is a json object with the each key being a name for the frequency and value being the frequency and tolerance in Hertz separated by a pipe(|) |
"{ “FX” : “2100|5”, “MD” : “1662|5”, “BP” : “ 1000|10” }” |
{} |
|
log_top_freq integer |
Log top frequency for every second. Use only for debugging purposes. False will disable this. |
True |
False |
|
log_voice string |
Tells the system whether or not to record and store the analysis stream. Must be True/False |
True |
False |
|
break_events string |
Comma separated list of frequencies or events on which the CPA analysis can stop. |
“FX,AM,LV” |
None |
|
total_timeout integer |
The time in milliseconds at which the analysis will stop. |
20000 |
15000 |
|
log_rtp_history string |
Log the history of rtp packets sent. Must be True/False |
True |
False |
frequency_count |
The number of harmonic frequencies measured |
200 |
200 |
4.2 Sample Request (json)
|
{
"request_name" : "set_cpa_params",
"tenant_id" : "acme",
"api_version" : "1.0",
"config_name" : "my_setup",
"time_limit" : 1750,
"log_voice" : "no",
"tones" :
{
"FX" : "2100|5",
"MD" : "1662|5"
},
"break_events" : "FX,MD,BP",
"total_timeout" : "20000"
}
|
4.3 Response Body (json)
Field |
Description |
|
result string |
OK - No error 01 - Mandatory fields are not specified 02 - Could not save the CPA configuration |
|
reason string |
Will provide the descriptive message about the result |
If the cpa parameter is set in one server, it will take effect in every server in the iraCluster. You can set the cpa_parameter using one server, and use config_name in the next server.
5 Make CPA request
This API sends the CPA request, followed by the RTP data.
5.1 Request Body (json)
Use text mode in the websocket to send this json request. Keep listening to any replies asynchronously.
Key |
Description |
Example |
Default |
|
tenant_id REQUIRED | string |
Name of the licensee |
acme |
None |
|
api_version REQUIRED | string |
Currently use 1.0 |
1.0 |
None |
|
config_name REQUIRED | string |
Unique name for the configuration |
“my_setup” |
None |
5.2 Sample Request (json)
{ |
This API request will initialize the CPA analyser. After the request is sent, the websocket mode should be changed to binary, and RTP data should be sent in 16 bit PCM format. Preferably send 4000bytes every 250milliseconds. The results will be coming back whenever the CPA analyser makes a detection.
5.3 Response Body (json)
Field |
Description |
|
result string |
LV - Live voice found AM - Answering Machine found TO - Time out, total time exceeded The result could also be a custom tone specified under tones. 01 - Mandatory fields are not specified 03 - Specified CPA configuration not found 04 - No license available for the tenant 05 - Specified CPA analyzer not found 06 - RTP data was sent without initializing the analyser |
|
reason string |
Will provide the descriptive message about the result. |
|
break string |
yes/no - Tells the caller to stop sending RTP and disconnect the session. |
|
max_energy string |
The maximum energy found in the voice data. |
|
pattern string |
Energy pattern seen in the voice data. |
|
duration string |
Duration of the data analysed. |
|
request_count string |
Count of the requests handled so far. |
|
real_time string |
Time taken to send the audio to IraCpa for Analysis. |
6 Version History
Version 1-1-1-3
Added amplitude settings to tones.
Version 1-1-1-4
Added silence detection, to return SL if silence follows after initial AM/LV detection.
Version 1-1-1-5
Version 1-1-2-0
1. Added api version 1.1 with an enhanced AMD engine.
Version 1-1-2-1
1. Improved beep detection algorithm