Overview
SimpleVoIP supports pulling ad-hoc CDR reports via our customer admin portal (at https://admin.simplevoip.us), but an ad-hoc report is inefficient if the goal is to import all call data into some behavioral analytics software.
For customers requiring that all call data be captured and stored, SimpleVoIP can set up automatic webhook notifications to one or more URLs. These webhooks will trigger on each individual completed call event (inbound or outbound) and should contain valuable information about the call.
Webhook Payload Structure
The body of the webhook will be a JSON object containing the following properties:
Property Name | JSON Type | Example Value | Description |
call_id
|
string | "151309175_116207117@208.93.141.211" | Unique ID of the call |
timestamp
|
int | 1680325200 | UNIX timestamp of the start of the call |
datetime_local
|
string | "2023-03-28T19:22:37-08:00" | ISO8601 time of the start of the call, in the site's local timezone |
site_name
|
string | "Latte Larry's - 304A" | |
site_number
|
string | "304A" | |
total_duration_secs
|
int | 324 | Seconds from INVITE to HANGUP of the call |
total_billing_secs
|
int | 307 | Seconds of active media on the call (see below) |
hangup_cause
|
string | "NORMAL_CLEARING" | See below. |
direction
|
string | "outbound" | outbound for calls initiated by a SimpleVoIP user, inbound for calls originating from outside SimpleVoIP's network |
caller_id_number
|
string | "+19605550234" | |
caller_id_name
|
string | "CAVE JOHNSON" | |
callee_id_number
|
string | "+12175550987" | |
callee_id_name
|
string | "RAOUL DIAZ" | |
total_user_talk_time
|
int | 185 | Total seconds that a SimpleVoIP user was connected |
max_user_ring_time
|
int|null | 27 | Longest amount of time that a SimpleVoIP user's phone rang before answering (see below) |
Example Payload
{ "call_id": "101189817_116019869@210.224.71.245", "timestamp": 1682361512, "datetime_local": "2023-04-24T13:38:32-05:00", "site_name": "SimpleVoIP", "site_number": "125", "total_duration_secs": 177, "total_billing_secs": 176, "hangup_cause": "NORMAL_CLEARING", "direction": "inbound", "caller_id_number": "7145002742", "caller_id_name": "CAVE JOHNSON", "callee_id_number": "8558998647", "callee_id_name": "", "total_user_talk_time": 0, "max_user_ring_time": 61 }
Additional Info on CDR Properties
Total Billing Seconds
The total_billing_secs
property represents the number of seconds between initiation of an RTP media stream and the HANGUP event.
- For a call that was never answered, this value is 0 seconds.
- For a call that rang straight to an individual or to a ring group, this value is the
total_billing_secs
minus the ring time of the call. - If a call is answered immediately by an auto-attendant, this initiates a media stream right away, so this value should be roughly equivalent to the
total_duration_secs
(maybe a second or two less, depending on the time required to set up the media stream).
Hangup Cause
Our platform is based on the FreeSwitch PBX, so these hangup codes should correspond to FreeSwitch hangup codes. There are relatively few that we see commonly on CDRs, though:
Hangup Code | Description |
NORMAL_CLEARING | The call completed successfully from the PBX's perspective. |
ORIGINATOR_CANCEL | The caller hung up before the recipient answered. |
NORMAL_UNSPECIFIED | No one answered the call, and no overflow destination was set. |
UNALLOCATED_NUMBER | The number dialed is not assigned to a specific user. |
USER_BUSY | Busy signal was received. |
NO_ROUTE_DESTINATION | The system was unable to route the call. This usually indicates that the user dialed an invalid number (e.g. left out a digit). |
Max User Ring Time
The largest number of seconds that a SimpleVoIP user's phone rang. This should only be populated with an integer value for inbound calls.
If an inbound call doesn't ring a user, this value will be null
. This occurs when the caller hangs up at an automated menu, or selects an option that doesn't result in a call to the store.
Deriving More Details
The basic, empirical metrics supplied in the webhook payload can be used with knowledge of your routing setup to derive additional information about your calls.
Handled by Menu
If your main line routes to a menu prior to ringing your users, you can determine how many calls were handled entirely by the menu:
- A call with
total_billing_seconds > 0
was handled- You can adjust your filtering thresholds however you like to exclude wrong numbers (likely just a few seconds in duration), robocalls, etc.
- If
max_user_ring_time == null
, the call did not attempt to ring a user, so either the caller hung up prior to the user-facing part of the callflow, or they selected a menu branch that does not route to a user.
FAQ
- What type of authentication is supported on CDR webhooks?
- We currently don't support authentication on webhook POST requests. Mention this to your account manager if you would like to see this implemented!
- Can the webhook body be customized to fit our data needs?
- Yes! We can customize these webhooks to include additional data. This will require some development time, and may incur a cost for the engineering hours. Please reach out to your account manager for details.