Call Detail Record (CDR)

Beta Feature
This feature is a closed beta and is not turned on by default for all customers. To enable this feature, contact support with an explanation of how you will use it.

A call detail record (CDR) is a transaction detail that shows all of the billable information about a call, transcription, or text message. When a call ends, a message is sent, or a transcription is completed, Tropo creates a CDR and uses it to bill for that transaction.

Tropo provides a webhook to send these CDRs to your web server. Using these webhooks, the CDRs are sent to your web server each time a call, SMS, or transcription occurs.

Setting up the webhook is done on the application detail page. Edit the "App Callback URL" to provide us with a URL (http or https) where we'll send CDRs, and select the format - JSON or XML - that you'd like to receive the CDRs.

It is also possible to specify the callback URL and format from inside your application. Both the `call` and `transfer` functions accept a parameter `callbackUrl` that tells Tropo where to send the CDR Webhook for that application instance. See the documentation for call and transfer for details.

Fields

name

String

The name of the webhook. This is user-settable, although for webhooks that do not have self-service configuration available, this will be set by support when your webhook is configured.

resource

String

The type of event this CDR is for. Possible values are "call", "sms", and "transcription".

event

String

Included in all webhooks, this identifies the type of webhook you are receiving. For CDRs, this will always be "cdrCreated".

CDR Data

The data element contains all the information specific to the CDR.

sessionId

String

An identifier for the session that this CDR is from. This represents a single execution of your Tropo application. Because your application may have several calls, messages, or transcriptions within a single session, you may receive several CDRs containing the same session ID. For example, if your application records and transcribes a telephone call, then sends a text message at the end of the call, you will get three CDRs with the same session ID. One for the call, one for the transcription, and one for the text message.

accountId

Integer

The account ID that owns the session this webhook is from. Useful if you are processing webhooks from several applications and accounts with a single web application.

applicationId

Integer

The application ID the webhook is from. All webhooks generated from a single application will have the same application ID. This corresponds to one of the applications in your account, and the ID will match the ID you see in the URL when looking at an application on the Tropo site. It will also match the application ID found when using the Tropo Applications REST API.

callId

String

An identifier for the call or message that this webhook is from. This represents a single call leg or text message from your Tropo application. This is globally unique, and if your application makes several calls or sends multiple messages in a single session, each will have a different call ID.

If you send a message longer than the maximum length and Tropo splits that message, you will receive a webhook for each message. The Call ID for each will share a common prefix, and will have a suffix indicating the number of messages.

Transcription CDRs will have a call ID matching the call the transcription is from. This means you may receive two CDR webhooks with the same call ID: one for the call and one for the transcription. Each would have a different resource type.

eventTimestamp

Integer

A timestamp indicating when this webhook was sent out. In Unix Epoch format.

applicationType

String

Which type of code did Tropo execute for this session? For WebAPI applications, this will be `tropo-web`. For Scripting API applications, this will be the language of the application: `js`, `groovy`, `jython`, `jruby`, or `php`.

applicationName

String

The name that you gave your application in the Tropo web site or Provisioning API.

startUrl

String

The URL where your application code was downloaded from for Scripting, or the URL we sent the Session object to for WebAPI. This will be a fully-qualified URL.

to

String

The number or SIP address that was called or that a message was sent to. For inbound calls or messages, this will be your Tropo number. For outbound calls or messages, this will be the number your call or message went out to.

from

String

The number or SIP address that made the call or sent the message. For outbound calls or messages, this will be your Tropo number. For inbound calls or messages, this will be the number your call or message came from.

direction

String

Set for call and message CDRs only, indicates if this was an incoming call or message (someone called or messaged your Tropo number) or an outgoing call or message (your Tropo application initiated it with the call or message API). Possible values are `in` or `out`.

network

String

Set for call and message CDRs only, the network the call or message was over. For voice calls, this will read SIP or PSTN. For text messages, this is SMS

initiationTime

String

The time the Tropo call or message setup with the remote carrier or network started. For voice calls, this is roughly the time the call began ringing. Value is a date and time in ISO 8601 format.

Example: "initiationTime": "2016-05-04T09:03:31.324+0000"

startTime

String

The time the call was answered or message was sent to the network (for outbound messages) or received by Tropo (for inbound messages. For text messages and transcriptions, this will usually be the same as initiation. The value is a date and time in ISO 8601 format.

Example: "startTime": "2016-05-04T09:03:47.050+0000"

endTime

String

Included in voice CDRs only, the time the Tropo call ended.

Example: "endTime": "2016-05-04T09:03:47.726+0000"

duration

Integer

Included in Voice CDRS only, the length of the call, in milliseconds. This is the same value as you would get by subtracting the `startTime` from the `endTime`.

Example: "duration": 676

status

String

For calls that completed normally, this field will be `SUCCESS`. For incomplete calls, including unanswered, busy, or system errors, this will be `FAIL`. This field should not be treated as case sensitive.

For text messages, `SUCCESS` only means that the message was delivered to the telephone network. It does not mean the text message reached the target number. This is because the SMS network may deliver or fail the message minutes or hours after the CDR is generated. If the message fails to be delivered to the network, this will say `FAIL`. See SMS Delivery Reports for information on how to get notified of the actual delivery status of the message.

For transcriptions, `SUCCESS` indicates that the transcription engine returned a successful transcription. Recordings with no transcribable audio will still say SUCCESS. If the transcription system is unable to be reached or returns an error, this value will be `FAIL`.

Example: "status": "Success"

reason

String

The detailed explanation of the `status` field. if the status was SUCCESS, then this field will also say `SUCCESS`.

For failures, the actual network response will appear here. For example, a call may show '486 Busy Here' when a busy signal is received. It is not possible to document all possible responses, as these are arbitrary and send by the remote network.

If the failure was due to an error in your code, this field will indicate that.

Example: "reason": "Script ended"

label

String

If your application set a label on this call or text message, the label will be shown here. See Labeling Your CDRs for details on how labels work.

Example: "label": "Cust-14823"

messageCount

Integer

Set for text messages only, this indicates how many 160 character text messages were required to send your message. If you send a long message, your message was split into this many parts, and you are billed for each part.