<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2176/25/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/Asterisk+12+CDR+Specification">Asterisk 12 CDR Specification</a></h2>
<h4>Page <b>added</b> by <a href="https://wiki.asterisk.org/wiki/display/~mjordan">Matt Jordan</a>
</h4>
<br/>
<div class="notificationGreySide">
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This specification is still in draft form. If you would like to comment on this specification, please contact the asterisk-dev mailing list.</td></tr></table></div>
<div>
<ul>
<li><a href='#Asterisk12CDRSpecification-Introduction'>Introduction</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-Scope'>Scope</a></li>
<li><a href='#Asterisk12CDRSpecification-HistoryofCDRs'>History of CDRs</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-Terminology'>Terminology</a></li>
<li><a href='#Asterisk12CDRSpecification-CDROverview'>CDR Overview</a></li>
<li><a href='#Asterisk12CDRSpecification-SemanticsandSyntax'>Semantics and Syntax</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-CDRLayout'>CDR Layout</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-StandardFields'>Standard Fields</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-Dispositions'>Dispositions</a></li>
<li><a href='#Asterisk12CDRSpecification-AMAFlags'>AMA Flags</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-UserDefinedFields'>User Defined Fields</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-CDRAPIs'>CDR APIs</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-Types'>Types</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-astcdrbe'>ast_cdrbe</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-DataStructures'>Data Structures</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-structastcdr'>struct ast_cdr</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-Functions'>Functions</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-astcdrregister'>ast_cdr_register</a></li>
<li><a href='#Asterisk12CDRSpecification-astcdrunregister'>ast_cdr_unregister</a></li>
</ul>
</ul>
<li><a href='#Asterisk12CDRSpecification-CDRSemantics'>CDR Semantics</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-Lifetime'>Lifetime</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-Creation'>Creation</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-DialingParties'>Dialing Parties</a></li>
<li><a href='#Asterisk12CDRSpecification-ChoosingthePartyAchannel'>Choosing the Party A channel</a></li>
<li><a href='#Asterisk12CDRSpecification-LinkedIDPropagation'>LinkedID Propagation</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-Finalization'>Finalization</a></li>
<li><a href='#Asterisk12CDRSpecification-Dispatch'>Dispatch</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-Consolidation'>Consolidation</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-Scenarios'>Scenarios</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-Unanswered%22Inbound%22Call'>Unanswered "Inbound" Call</a></li>
<li><a href='#Asterisk12CDRSpecification-Unanswered%22Outbound%22Call'>Unanswered "Outbound" Call</a></li>
<li><a href='#Asterisk12CDRSpecification-SingleParty'>Single Party</a></li>
<li><a href='#Asterisk12CDRSpecification-BasicTwoPartyCall'>Basic Two Party Call</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-BasicCall'>Basic Call</a></li>
<li><a href='#Asterisk12CDRSpecification-UnansweredDial'>Unanswered Dial</a></li>
<li><a href='#Asterisk12CDRSpecification-ParallelDial'>Parallel Dial</a></li>
<li><a href='#Asterisk12CDRSpecification-CallForward'>Call Forward</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-Transfers'>Transfers</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-BlindTransfer'>Blind Transfer</a></li>
<li><a href='#Asterisk12CDRSpecification-AttendedTransfertoChannel'>Attended Transfer to Channel</a></li>
<li><a href='#Asterisk12CDRSpecification-AttendedTransfertoApplication'>Attended Transfer to Application</a></li>
<li><a href='#Asterisk12CDRSpecification-BlondeTransfer'>Blonde Transfer</a></li>
<li><a href='#Asterisk12CDRSpecification-ThreeWayCall'>Three Way Call</a></li>
<li><a href='#Asterisk12CDRSpecification-SIPAttendedTransfer'>SIP Attended Transfer</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-LocalChannels'>Local Channels</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-NonoptimizingLocalChannels'>Non-optimizing Local Channels</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-Localchanneltoanapplication'>Local channel to an application</a></li>
<li><a href='#Asterisk12CDRSpecification-Localchannelbetweenbridges'>Local channel between bridges</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-LocalChannelOptimization'>Local Channel Optimization</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-CallHold'>Call Hold</a></li>
<li><a href='#Asterisk12CDRSpecification-CallPark'>Call Park</a></li>
<li><a href='#Asterisk12CDRSpecification-CallQueues'>Call Queues</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-CallQueueExample1'>Call Queue - Example 1</a></li>
<li><a href='#Asterisk12CDRSpecification-CallQueueExample2'>Call Queue - Example 2</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-ConferenceCall'>Conference Call</a></li>
<li><a href='#Asterisk12CDRSpecification-AComplexExample'>A Complex Example</a></li>
</ul>
</ul>
<li><a href='#Asterisk12CDRSpecification-AsteriskCDRAPIs'>Asterisk CDR APIs</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-Applications'>Applications</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-NoCDRAST%3AASterisk11ApplicationNoCDR'> NoCDR</a></li>
<li><a href='#Asterisk12CDRSpecification-ForkCDRAST%3AAsterisk11ApplicationForkCDR'> ForkCDR</a></li>
<li><a href='#Asterisk12CDRSpecification-ResetCDRAST%3AAsterisk11ApplicationResetCDR'> ResetCDR</a></li>
</ul>
<li><a href='#Asterisk12CDRSpecification-Functions'>Functions</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-CDRAST%3AAsterisk11FunctionCDR'> CDR</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-Example%3ASettingthecalledpartyasPartyAoftheCDR'>Example: Setting the called party as Party A of the CDR</a></li>
</ul>
</ul>
<li><a href='#Asterisk12CDRSpecification-Configuration'>Configuration</a></li>
<ul>
<li><a href='#Asterisk12CDRSpecification-GeneralSettings'>General Settings</a></li>
</ul>
</ul>
</ul></div>
<h1><a name="Asterisk12CDRSpecification-Introduction"></a>Introduction</h1>
<p>This Call Detail Record (CDR) specification describes the records produced by Asterisk providing call information suitable for billing systems. It includes:</p>
<ul>
<li>An overview of CDRs in Asterisk</li>
<li>The definition of the fields in a CDR, including:
<ul>
<li>Storage requirements</li>
<li>Access control restrictions</li>
<li>C APIs available that backends may use to receive CDRs from Asterisk</li>
</ul>
</li>
<li>Semantics of how Asterisk produces CDRs</li>
</ul>
<h2><a name="Asterisk12CDRSpecification-Scope"></a>Scope</h2>
<p>This CDR specification applies to Asterisk 12. It does not cover CDRs in prior versions of Asterisk.</p>
<p>Note that this does not include a comprehensive analysis as to how CDRs can be produced in all call scenarios in Asterisk. It defines the behavior for common scenarios, but certain scenarios are deliberately left unspecified. The behavior of CDRs in said scenarios is <b>undefined</b>.</p>
<p>It is known that the behavior of CDRs will not allow all applications to capture the billing requirements for their systems. If CDRs cannot meet the requirements of your application, <a href="/wiki/display/AST/Channel+Event+Logging+%28CEL%29" title="Channel Event Logging (CEL)">Channel Event Logging</a> provides call information at a much finer granularity, allowing complex billing systems to be constructed.</p>
<h2><a name="Asterisk12CDRSpecification-HistoryofCDRs"></a>History of CDRs</h2>
<p>CDRs have been around in Asterisk for a long, long time. In fact, portions of it were taken from the <tt>Zapata</tt> library, as noted in <tt>cdr.c</tt>:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: c; gutter: false">*
* \note Includes code and algorithms from the Zapata library.
*</pre>
</div></div>
<p>CDRs have always attempted to provide the billing information between two parties. Their simplicity has been their biggest advantage, but has also been their largest disadvantage. As Asterisk evolved into a telephony toolkit, it quickly became difficult to express the full details of a call within a single CDR. Compounding this problem, the way in which bridging was performed in Asterisk made multi-party call scenarios incredibly difficult to track and coalesce into one or more CDRs. Numerous attempts were made to address this problem in CDRs with varying degrees of success.</p>
<p>In <a href="/wiki/display/AST/New+in+1.8#Newin1.8-Newin1.8ChannelEventLogging">Asterisk 1.8</a>, CEL was introduced as an alternative to CDRs. Unlike CDRs, where a single record is produced for a call, CEL provides a sequence of events regarding the state of channels within Asterisk. It was always envisioned that CEL would eventually replace CDRs, and that CDRs would be produced from CEL records. Unfortunately, this effort never really took off.</p>
<p>Asterisk 12 has, for better or worse, forced CDRs to be upgraded. Major changes to the <a href="/wiki/display/AST/Asterisk+12+Bridging+Project" title="Asterisk 12 Bridging Project">way in which Asterisk performs bridging</a> will remove much of the code in Asterisk that attempts to construct CDRs in two-party and transfer scenarios. While we would, in some ways, prefer to abandon CDRs and simply advocate CEL, CEL requires a system integrator to develop their own billing system, which is a non-trivial task. While some post-processing is needed for CDRs as well, it is much less work and far easier to consume (although, of course, significantly less flexible and powerful).</p>
<h1><a name="Asterisk12CDRSpecification-Terminology"></a>Terminology</h1>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Term </th>
<th class='confluenceTh'> Definition </th>
</tr>
<tr>
<td class='confluenceTd'> CDR </td>
<td class='confluenceTd'> Call Detail Record. The thing that this document is attempting to describe. </td>
</tr>
<tr>
<td class='confluenceTd'> CEL </td>
<td class='confluenceTd'> Channel Event Logging. An alternative way to get billing information from Asterisk, that is significantly more flexible and powerful than CDRs but requires the billing logic to be completely implemented by the user. </td>
</tr>
<tr>
<td class='confluenceTd'> Party A </td>
<td class='confluenceTd'> A CDR always involves two parties. One party is always chosen as the 'owner' of the CDR. The CDR reflects the view of the call from that party. </td>
</tr>
<tr>
<td class='confluenceTd'> Party B </td>
<td class='confluenceTd'> A CDR always involves two parties. Party B is the target of the call. </td>
</tr>
<tr>
<td class='confluenceTd'> Stasis </td>
<td class='confluenceTd'> Stasis provides the internal message bus to Asterisk that conveys state to the CDR engine. </td>
</tr>
</tbody></table>
</div>
<h1><a name="Asterisk12CDRSpecification-CDROverview"></a>CDR Overview</h1>
<p>A CDR is a record of communication between two parties. As such, a CDR typically contains two parties: a Party A and a Party B. The CDR reflects the view of the call from the perspective of Party A, while Party B is the party that Party A is communicating with. Each CDR includes the following times:</p>
<ul>
<li>Start time - the time at which the CDR was created for Party A</li>
<li>Answer time - the time at which Party A and Party B could begin communicating</li>
<li>End time - the time at which Party A and Party B could no longer communicate<br/>