Call Recording

About Call Recording

Setting up call recording allows you to have a permanent record of a conversation that took place.

Configuring Call Recording

Call recording can be enabled in a number of ways:

At the account level
At the user level
At the device level
Explicitly as a callflow action

Call recording requires you to either:

have a web server capable of receiving an HTTP PUT request with the contents of the recording, which you are then free to save in a way that meets your needs
configure a storage plan for call recordings

Account, User, or Device

Configuring recording at the account level means all calls, inbound and outbound, to this account will start the call recording system.

Configuring recording at the user level starts recording for any calls to/from a device owned by that user.

Configuring recording at the device level starts recording for any calls to/from the device.

Precedence of settings

Precedence of settings is: Device > User

If a user turns on call recording but a device has explicitly disabled it, the device will not be recorded when the user makes a call with it. If the device’s settings are left undefined, the user’s settings will be applied.

The account’s settings are considered independently of the endpoint’s. So a user who has disabled recording, within an account that has enabled recording, will still have calls recorded according to the account’s settings.

Recording settings matrix

Account Settings

When an onnet device makes an internal call:

Setting	Source	Destination	Recording Started
Account -> Inbound -> Onnet	onnet	onnet	yes
Account -> Inbound -> Offnet	onnet	onnet	no
Account -> Outbound -> Onnet	onnet	onnet	yes (if inbound -> onnet isn’t configured)
Account -> Outbound -> Offnet	onnet	onnet	no

When an onnet device makes an external call:

Setting	Source	Destination	Recording Started
Account -> Inbound -> Onnet	onnet	offnet	yes
Account -> Inbound -> Offnet	onnet	offnet	no
Account -> Outbound -> Onnet	onnet	offnet	no
Account -> Outbound -> Offnet	onnet	offnet	yes (if inbound -> onnet isn’t configured)

When an offnet device makes an internal call:

Setting	Source	Destination	Recording Started
Account -> Inbound -> Onnet	offnet	onnet	no
Account -> Inbound -> Offnet	offnet	onnet	yes
Account -> Outbound -> Onnet	offnet	onnet	yes (if inbound-offnet isn’t configured)
Account -> Outbound -> Offnet	offnet	onnet	no

Endpoint Settings

When an onnet device makes an internal call:

Setting	Source	Destination	Recording Started
Endpoint -> Inbound -> Onnet	onnet	onnet	yes¹
Endpoint -> Inbound -> Offnet	onnet	onnet	no
Endpoint -> Outbound -> Onnet	onnet	onnet	yes
Endpoint -> Outbound -> Offnet	onnet	onnet	no

¹ When the setting is enabled on the destination endpoint

When an onnet device makes an external call:

Setting	Source	Destination	Recording Started
Endpoint -> Inbound -> Onnet	onnet	offnet	no
Endpoint -> Inbound -> Offnet	onnet	offnet	no
Endpoint -> Outbound -> Onnet	onnet	offnet	no
Endpoint -> Outbound -> Offnet	onnet	offnet	yes

When an offnet endpoint makes a call to an onnet device:

Setting	Source	Destination	Recording Started
Endpoint -> Inbound -> Onnet	offnet	onnet	no
Endpoint -> Inbound -> Offnet	offnet	onnet	yes
Endpoint -> Outbound -> Onnet	offnet	onnet	no
Endpoint -> Outbound -> Offnet	offnet	onnet	no

Enabling recording

To enable call recording, add "call_recording":{...} to the document of choice. For example, if you have a user with user ID of {USER_ID}, you can patch the user’s document using Crossbar:

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data":{
    "call_recording":{...}
    }}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}

Concrete example

Sales wants calls to and from customers to be recorded but not calls within the account. The sales users would have their call_recording settings set as:

{
  "call_recording": {
    "inbound": {
      "offnet": {
        "enabled": true
      }
    },
    "outbound": {
      "offnet": {
        "enabled": true
      }
    }
  }
}

The call recording settings

Key	Description	Type	Default	Required	Support Level
`enabled`	is recording enabled	`boolean()`		`false`
`format`	What format to store the recording on disk	`string(‘mp3'	'wav’)`		`false`
`record_min_sec`	The minimum length, in seconds, the recording must be to be considered successful. Otherwise it is deleted	`integer()`		`false`
`record_on_answer`	Recording should start on answer	`boolean()`		`false`
`record_on_bridge`	Recording should start on bridge	`boolean()`		`false`
`record_sample_rate`	What sampling rate to use on the recording	`integer()`		`false`
`time_limit`	Time limit, in seconds, for the recording	`integer()`		`false`
`url`	The URL to use when sending the recording for storage	`string()`		`false`

Callflow action - Record Call

You can enable call recording on a per-callflow basis by using the record_call callflow action. The callflow action can take the following parameters:

Key	Description	Type	Default	Required
`action`	Whether to start or stop the recording	`string('start', 'stop')`	`start`	`true`
`format`	What format to store the recording on disk	`string('mp3', 'wav')`		`false`
`label`	Label to include in the origin of call recording	`string()`		`false`
`media_name`	the name of media	`string`		`false`
`record_min_sec`	The minimum length, in seconds, the recording must be to be considered successful. Otherwise it is deleted	`integer`		`false`
`record_on_answer`	Whether to delay the recording until the channel is answered	`boolean`	`false`	`false`
`record_on_bridge`	Whether to delay the recording until the channel is bridged	`boolean`	`false`	`false`
`record_sample_rate`	What sampling rate to use on the recording	`integer`		`false`
`time_limit`	Time limit, in seconds, for the recording	`integer`	`3600`	`false`
`url`	The URL to use when sending the recording for storage	`string`		`false`

Callflow action - Record Caller

The record_caller callflow action is meant for recording things like voicemails or IVR prompts. The schema for the callflow action is:

Key	Description	Type	Default	Required	Support Level
`format`	What format to store the recording on disk	`string(‘mp3'	'wav’)`		`false`
`method`	What HTTP method to use when sending the recording	`string(‘put'	'post’)`	`put`	`false`
`time_limit`	Time limit, in seconds, for the recording	`integer()`	`3600`	`false`
`url`	The URL to use when sending the recording for storage	`string()`		`false`

Interpreting call recordings and call direction

Call direction is a field found in CDRs that indicates, from KAZOO’s perspective, from whence the call was started. inbound indicates that the phone/carrier has sent the INVITE to Kazoo (inbound to KAZOO). outbound indicates that KAZOO is sending the INVITE to the phone/carrier (outbound from KAZOO).

inbound: PHONE ==INVITE==> KAZOO
outbound: PHONE <==INVITE== KAZOO

Now a lot of calls will involve two phones:

PHONE_A ==INVITE==> KAZOO ==INVITE==> PHONE_B

The INVITE from PHONE_A is the inbound call leg while the INVITE from KAZOO to PHONE_B is the outbound leg.

However, these directions are often not intuitive to end users. Most folks would say a call coming in from the PSTN is an inbound call while the call they place to the PSTN is an outbound call. UI clients, therefore, can’t rely on just displaying the call_direction field of a call to indicate the direction of the call from the end user’s perspective.

When call recording is configured, the leg being recorded will include the recording information in its CDR. Additionally, if a leg is coming in from or going out to the PSTN, it will include a resource_type field in the CDR’s custom_channel_vars. Fetching all legs involved (using the interaction_id), it should be possible to determine the direction of a call from the end user’s perspective for the simple case:

End User’s Direction	Call Direction (A leg)	Resource Type (A leg)	Call Direction (B leg)	Resource Type (B leg)	Description
`inbound`	inbound from PSTN	`offnet-origination`	outbound to the device	`undefined`	A call in from the PSTN to a registered device
`outbound`	inbound from a device	`undefined`	outbound to the PSTN	`offnet-termination`	A call from a registered device to the PSTN

Those are the simple cases, of course. Where it gets tricky is when a call comes in from the PSTN and is subsequently sent to a call-forwarded device (via PSTN). Both legs will have resource_type set. Or when a device calls another device, no resource_type will exist on either leg. Or when a call is transferred or parked/picked up (sometimes multiple times).

The leg where call recording is started will have media_recording_id set (among others) in the leg’s CDR under the custom_channel_vars object.

Hopefully this section can serve as a jumping off point for UI clients to determine how to communicate to end users the direction of calls so that labeling recordings can be done in a way that makes sense for the end user.