Call Detail Records

What is a CDR

Although named CDR (Call Detail Record), the file contains all types of callable events. A callable flow can be made up of many components (voice | sms | email | etc) and each flow can generate many events. When an event is generated, it is written to a CDR File which is then uploaded to an SFTP server every 10 minutes. In this document we will discuss how to obtain your files from SFTP and describe the CDR.

CDR Filename

The following filename

5f515fd1e390c45fbc95ace5_dev_DESKTOP-9SH83Q4_2020091420_5.txt

is made up from the following placeholders:

[orgID]_[environment]_[instanceID]_[YYYYMMDDHH]_[hourPart].txt

You can expect multiple CDR files per hour from multiple billing instances. As the callable cluster grows and shrinks, CDRs per hour will also increase or decrease.

Note billing instances are ephemeral and can be swapped in and out of services so please do not use [instanceID] as an internal identifier.

SFTP Access

SFTP (Secure File Transfer Protocol)

CDRs can be collected from sftp.callable.io

To access our SFTP server you will first need to generate a private & public key and send us the public key.

You can use ssh-keygen to generate a key pair:

ssh-keygen -t rsa -C callable.key -f callable.key -q -N 

This will generate two files:

• callable.key - This is the private key. You should store this in a safe place, since it will later be used for authentication.
• callable.key.pub - This is the public key. You should provide this so that you can grant the user access to SFTP Gateway.

Once we have applied the public key you can access your files using the username [orgID] which will be shared with you at the onboarding stage.

CDR Description

The CDR format is CSV (Comma Seperated Values) and consists of 31 Columns.

Column Mapping

Column Description

Date

For Voice, this will be the local date the call was answered.
For SMS/Email/API calls, this will be the time when the action was invoked.

Time

For Voice, this will be the local time the call was answered.
For SMS/Email/API calls, this will be the time when the action was invoked

Locale

Used to determine the time-zone of the call.

CallId

Generated OID for the leg of the call. Multiple CDR entires can share the same CallId as there can be multiple services called per call.

ParentCallId

Legs forked from original call will have ParentCallId OID populated with originating callId.

OrgId

Unique identifier for the organization.

OrgName

The Organization name.

AccountId

Unique identifier for the child account.

AccountName

The child account name.

OriginatingDevice

The originating device is the device which initiates the service. The following are some common devices:
• pstn
• sipGateway
• client
• teams
• api

TerminatingDevice

The terminating device is the device which receives the service request. The following are some common devices:
• pstn
• sipGateway
• client
• teams
• api

Leg

Originating calls will always have a Leg = 0. When a call is forked this field increments. Services such as ASR/TTS are invoked on the originating call leg and will have a Leg = 0 also. API generated calls will also have a Leg = 0.

BillableNumber

If an invalid number is present in the From/To field, we will inject the customer MBN, otherwise this will be a customer owned originating from/to number. This field is designed to give rating engines a field to bill against regardless of service.

From

The caller party is derived from the user in the FROM SIP URI. On originating calls, this can potentially be anything. 2001, 441234567890 or even myusername. For calls terminating on our proxy, we ensure that the From field is normalized and If the Originating Caller is not a an owned DDI, we inject the MBN into this field.

To

The called party is derived from the user in the TO SIP URI. Calls from our proxy are guaranteed to be valid DDIs. Calls from authorized endpoints such as SipGateway/Client can also dial internal extensions so this field may contain the following: 2001, 441234567890, 447850100100, 999, 119, 111 etc.

IP

If Applicable, this is the IP address of Originating Device for Leg = 0. If calls are forked, this will be the Terminating Device IP

Port

If Applicable, this is the port of Originating Device for Leg = 0. If calls are forked, this will be the Terminating Device Port

Zone

The zone or region that the service was handled on. For example eu-west-1.

Service

The type of service that was handled. This may be one of the following:
• voice
• sms
• email
• recording
• asr (Automatic Speech Recognition)
• tts (Text to Speech)
• plugin (Integration API Calls)

Unit

The billable unit type which is one of the following:

• mins - voice & SoftwareRecording minutes
• chars - 100 characters of text to speech (SoftwareTTS)
• requests - a plugin request (SoftwarePlugin)
• events - a plugin event (SoftwareEvent)
• words - a transcribed word (SoftwareASR). A minimum of 10 transcribed words per conversation will be billed

Code

For the voice service, this is the code determined by our rating engine and matches your rating plan column “RatingCode”
For recording service, this column is the recording product at the time the call was recorded and may be one of the following:
• SoftwareRecording1M
• SoftwareRecording3M
• SoftwareRecording4M
• SoftwareRecording6M
• SoftwareRecording1Y
• SoftwareRecording2Y
• SoftwareRecording3Y
• SoftwareRecording4Y
• SoftwareRecording5Y
• SoftwareRecording6Y
• SoftwareRecording7Y

Category

Rated voice category (If applicable, non-voice services will display “N/A” )

CountryCode

Rated voice country code (If applicable, non-voice services will display “N/A” )

Billable

Is this CDR leg billable. T = True, F = False

UnitPrice

The billable unit price of this service before bundling

Qty

Number of billable units before bundling

Total

Total Billable before bundling.

BundleStatus

Can be one of three statuses
• NB = no bundle
• IB = in bundle (bundle is valid and has been applied)
• OB = out of bundle (bundle is present but it is depleted)

BundleUnitPrice

IB & OB can have overridable unit prices. NB will always equal “UnitPrice” field.

BundleQty

Number of billable units after bundling has been applied. For NB, this will equal “Qty” field.

BundleTotal

Total Billable after bundling. Use this field to calculate the actual value you will be billed.

RateUUID

A universally unique identifier for either the product or the rate.