CDR REC API

CDR Report

CDR (Call Detail Record) is a data record generated by the UCM6xxx series that contains attributes specific to a single instance of phone calls handled by the PBX. It has several data fields to provide a detailed description of the call, such as the phone number of the calling party, phone number of the receiving party, start time, call duration…

CDR Filter

On the UCM6XXX, the CDR can be accessed under web GUI🡪CDR🡪CDR. Users could filter the call report by specifying the date range and criteria, depending on how the users would like to include the logs in the report. Click on the ”Display Filter” button to display the filter criteria, a second click will start the search.

Table 1: CDR Filter Criteria

The call report will display as the following figure shows and since firmware version 1.0.15.16, the report will display only CDR records for the current month since it’s split month by month.

In order to get records from previous months, users would need to use the filter search and specify a start date and end date to get records from the required period of time.

CDR Report Data Fields

The CDR report has the following data fields:

Example of a CDR report Data fields:

• Account code: —
• Caller Number: 1000
• Callee number: 7000
• Context: ext-did-1
• Caller ID: “1000” <1000>
• Source Channel: PJSIP/trunk_1-00000000
• Dest Channel: —
• Lastapp: ForkCDR
• Lastdata: ae
• Start time: 7/13/2018 12:00:12 PM
• Answer time: 7/13/2018 12:00:12 PM
• End time: 7/13/2018 12:00:32 PM
• Call time: 19 (in seconds)
• Talk Time: 19
• Disposition: ANSWERED
• Amaflags: DOCUMENTATION
• UniqueID: 1531497605
• Userfield: Inbound
• Dest channel extension: 7000
• Caller name: 1000
• Answer by: 7000
• Session: 1531497605793100-1000
• Action owner: 1000
• Action type: DIAL.
• Source Trunk name: test
• Dest Trunk name: —

CDR Report Operations

Users could perform the following operations on the CDR report.

• Sort by “Start Time”

Click on the header of the column to sort the report by “Start Time”. Clicking on “Start Time” again will reverse the order.

• Download Searched Results

Click on “Download Search Result(s)” to export the records filtered out to a .csv file.

• Download All Records

Click on “Download All Records” to export all the records to a .csv file.

• Delete All

Click on the “Delete All” button to remove all the call report information.

• Recording File Options

Recording file is available to play or download if the PBX records the call, click on and the following options will be displayed.

: Download the voice recording for the call

: Play the voice recording for the call

: Delete the voice recording for the call

• Automatic Download

The user could configure the UCM6XXX to automatically download the CDR records and send the records to multiple email recipients in a specific hour. Click on “Automatic Download”, and configure the parameters in the dialog below.

To receive CDR records automatically from Email, check “Enable” and select a time period “By Day” “By Week” or “By Month”, select Hour of the day as well for the automatic download period. Make sure you have entered an Email or multiple email addresses where to receive the CDR records.

• Options

Click on the icon to view more details about the call.

CDR CSV FILE

The downloaded CDR .csv file has a different format from the web UI CDR. Here are some descriptions.

• Caller number, Callee number

“Caller number”: the caller ID.

“Callee number”: the callee ID.

If “Caller number” shows empty, “Callee number” shows “s” (see the below figure), and the “Source Channel” contains “DAHDI”, this means the call is from FXO/PSTN line. For FXO/PSTN line, we only know there is an incoming request when there is an incoming call but we don’t know the number being called. So we are using “s” to match it where “s” means “start”.

• Context

There are different context values that might show up in the downloaded CDR file. The actual value can vary case by case. Here are some sample values and their descriptions.

• from-internal: internal extension makes outbound calls.
• ext-did-XXXXX: inbound calls. It starts with “ext-did”, and “XXXXX” content varies case by case, which also relate to the order when the trunk is created.
• ext-local: internal calls between local extensions.
• Source Channel, Dest Channel

Sample 1:

DAHDI means it is an analog call, FXO or FXS.

For UCM6102/6202, DAHDI/(1-2) are FXO ports, and DAHDI(3-4) are FXS ports.

For UCM6104/6204, DAHDI/(1-4) are FXO ports, and DAHDI(5-6) are FXS ports.

For UCM6108/6208, DAHDI/(1-8) are FXO ports, and DAHDI(9-10) are FXS ports.

For UCM6116, DAHDI/(1-16) are FXO ports, and DAHDI/(17-18) are FXS ports.

For UCM6510, DAHDI/(1-2) are FXO ports, and DAHDI(3-4) are FXS ports.

Sample 2:

“PJSIP” means it’s a SIP call. There are three possible formats:

PJSIP/NUM-XXXXXX, where NUM is the local SIP extension number. The last XXXXX is a random string and can be ignored.

PJSIP/trunk_X/NUM, where trunk_X is the internal trunk name, and NUM is the number to dial out through the trunk.

PJSIP/trunk_X-XXXXXX, where trunk_X is the internal trunk name and it is an inbound call from this trunk. The last XXXXX is a random string and can be ignored.

There are some other possible values, but these values are almost the application name that is used by the dialplan.

• IAX2/NUM-XXXXXXX: it means this is an IAX call.
• Local/@from-internal-XXXXX: it is used internally to do some special feature procedure. We can simply ignore it.
• Hangup: the call is hung up from the dialplan. This indicates there are some errors or it has run into abnormal cases.
• Playback: play some prompts to you, such as 183 response or run into an IVR.
• ReadExten: collect numbers from user. It may occur when you input PIN codes or run into DISA.

CDR Stored in GDMS Cloud

UCM630x and UCM630xA series provide the service of automatically storing CDR data in the GDMS cloud, the related configuration can be found under the Value-added Features🡪UCM RemoteConnect🡪Plan Settings page, the option is called CDR Stored in GDMS Cloud which is disabled by default, so please make sure to enable this service on the UCM in order to start storing the CDR data in GDMS.

After the “CDR Stored in GDMS Cloud” option is enabled, the UCM server will only retain up to 3 months of CDR data locally. To view historical CDR data, you need to download the CDR data file from GDMS and use the CDR View Assistant tool to view it. The UCM63xx must have been added to GDMS cloud beforehand under UCMRC🡪UCM Device page,

Customers can access the CDR record stored in GDMS by pressing on CDR in GDMS cloud option as shown in the figure below:

API Configuration

The UCM6XXX supports a CDR API interface to interact with third-party external billing software and collect recording details files from the PBX. The API uses HTTPS to request the CDR data and call recording data matching given parameters as configured on the third-party application, as well as a new API interface to query, edit PBX settings and implement multiple call functions on another server connected to it via API.

This guide will focus on the CDR API configuration and for more details about the new supported API, please refer to the below link:

https://documentation.grandstream.com/knowledge-base/https-api/

API Configuration

Before accessing the CDR API (to access call detail records) and REC API (to access call recording files), the administrators need to enable API and configure the access/authentication information on the UCM6XXX first under Value-added Features🡪API Configuration.

Table 2: API Configuration Parameters

CDR API – Access Call Detail Records

CDR API URL Format

The format of the HTTPS request for the CDR API is shown as below. This is used to request the CDR data matching given parameters as set by the third-party application.

https://[UCM IP]:[Port]/cdrapi?[option1]=[value]&[option2]=[value]&…

By default, the port number for the API is 8443.

CDR API URL Parameters

The options included in the above request URI control the record matching and output format. For CDR matching parameters, all non-empty parameters must have a match to return a record. Parameters can appear in the URI in any order. Multiple values given for caller or callee will be concatenated.

The following table shows the parameter list used in the CDR API.

Table 3: CDR API URL Parameters

Example Queries

The following illustrates the format of queries to accomplish certain requests. In most cases, multiple different queries will accomplish the same goal, and these examples are not intended to be exhaustive, but rather to bring attention to particular features of the CDR API connector.

• Query 1: Request all records of calls placed on extension 5300 which last between 8 and 60 seconds (inclusive), with results in CSV format.

https://192.168.254.200:8443/cdrapi?format=CSV&caller=5300&minDur=8&maxDur=60

-OR-

https://192.168.254.200:8443/cdrapi?caller=5300&minDur=8&maxDur=60

• Query 2: Request all records of calls placed on extension 5300 or in the range 6300-6399 to extensions starting with 5, with results in XML format.

https://192.168.254.200:8443/cdrapi?format=XML&caller=5300,6300-6399&callee=5@

-OR-

https://192.168.254.200:8443/cdrapi?cdrapi?format=XML&caller=5300&caller=6300-6399&callee=5@

• Query 3: Request 10 records of calls placed on extension 5300 with results in JSON format.

https://192.168.254.200:8443/cdrapi?format=JSON&caller=5300&numRecords=10

• Query 4: Request all records of calls placed on extensions containing substring “53” prior to January 23, 2013 00:00:00 UTC to extensions 5300-5309, with results in CSV format.

https://192.168.254.200:8443/cdrapi?caller=@53@&callee=5300-5309&endTime=2013-01-23

-OR-

https://192.168.254.200:8443/cdrapi?caller=@53@&callee=530_&endTime=2013-01-23T00:00:00

• Query 5: Request all records of calls placed by an Anonymous caller during July 2013 Central Standard Time to extensions starting with 2 or 34 or ending with 5, with results in CSV format.

https://192.168.254.200:8443/cdrapi?caller=Anonymous&callee=2@,34@,@5&startTime=2013-07-01T00:00:00-06:00&endTime=2013-07-31T23:59:59-06:00

• Query 6: Request all records during July 2013 Central Standard Time, 200 at a time, with results in CSV format.

https://192.168.254.200:8443/cdrapi?startTime=2013-07-01T00:00:00-06:00&endTime=2013-07-31T23:59:59-06:00&numRecords=200&offset=0

-THEN-

https://192.168.254.200:8443/cdrapi?sstartTime=2013-07-01T00:00:00-06:00&endTime=2013-07-31T23:59:59-06:00&numRecords=200&offset=200

-THEN-

https://192.168.254.200:8443/cdrapi?startTime=2013-07-01T00:00:00-06:00&endTime=2013-07-31T23:59:59-06:00&numRecords=200&offset=400

Output

Fields

From UCM6XXX firmware 1.0.11.x and higher, the CDR output has the following changes:

• New output fields are added for all format (CSV, XML and JSON):
  • session
  • action_owner
  • action_type
  • src_trunk_name
  • dst_trunk_name
• For XML and JSON format output, sub record is added for certain call scenarios, e.g., call transfer. (CSV format doesn’t have sub record added).

“session”

The new field “session” is the unique identifier for the call record and it exists in all CDR for this call. The same “session” value indicates this is the same call. The value of the “session” consists of the time when the channel is generated and the caller extension number, for example, 1461920017104140-1000.

“action_owner”

The new field “action_owner” indicates the owner of the CDR record, which is the initiator of this call. In a call transfer scenario, sub-record 1 has A as the action_owner and sub-record 2 has B as the action_owner who is performing the call transfer.

“action_type”

The new field “action_type” indicates the type for the call record. If this call type has its own extension number or name, it will be listed in [ ]. For example, if an extension calls conference number 6300, the action_type will be CONFERENCE [6300]. Here are the possible values of action_type:

• DIAL: basic call
• TRANSFER: call transfer
• PAGE: paging/intercom
• CALLFORWARD: call forward always, call forward no answer, call forward busy
• IVR: enter IVR or call from IVR
• RINGGROUP: ring group
• VM: voice mail
• VMG: voice mail group
• CONFERENCE: conference call by calling into UCM’s conference extension
• DISA: enter DISA or call from DISA
• FAX: FAX
• VFAX: VFAX
• Announcements: Announcement center
• FOLLOWME: Follow Me
• QUEUE: call queue
• CALLBACK: call back

“src_trunk_name”

Source trunk name indicates the name of the trunk for the inbound call. For example, if the FOLLOWME call is from trunk, this call record will have source trunk name field.

“dst_trunk_name”

Destination trunk name indicates the name of the trunk for the outbound call. Only outbound call has dst_trunk_name field.

XML Output

On UCM6XXX, the XML output looks like below:

<cdr session=xxxxx-xxxx>
<main_cdr>
...
</main_cdr>
<sub_cdr>
<AcctID>1</AcctID>
...
</sub_cdr>
<sub_cdr>
<AcctID>2</AcctID>
...
</sub_cdr>
</cdr>

Example:

Assuming the following scenario:

Extension A: 5000

Extension B: 5001

Extension C: 5002

A calls B->B answers->B Transfers the call to C.

• The XML output for the scenario above looks like below:

<root>
<cdr session="1461920017104140-1000">
<main_cdr>
<AcctId/>
<accountcode/>
<src>1000</src>
<dst>1001</dst>
<dcontext/>
<clid/>
<channel/>
<dstchannel/>
<lastapp/>
<lastdata/>
<start>2016-04-29 02:53:37</start>
<answer/>
<end/>
<duration>16</duration>
<billsec>9</billsec>
<disposition/>
<amaflags/>
<uniqueid/>
<userfield/>
<channel_ext/>
<dstchannel_ext/>
<service/>
<caller_name/>
<recordfiles/>
<dstanswer/>
<chanext/>
<dstchanext/>
<session>1461920017104140-1000</session>
<action_owner/>
<action_type>DIAL</action_type>
<src_trunk_name/>
<dst_trunk_name/>
</main_cdr>
<sub_cdr>
<AcctId>1</AcctId>
<accountcode/>
<src>1000</src>
<dst>1001</dst>
<dcontext>from-internal</dcontext>
<clid>"John Doe" <1000></clid>
<channel>PJSIP/1000-00000003</channel>
<dstchannel>PJSIP/1001-00000004</dstchannel>
<lastapp>Dial</lastapp>
<lastdata>PJSIP/1001/sip:1001@192.168.124.179:5066,60,ztTkKA(dialog-being-recorded)M(reco</lastdata>
<start>2016-04-29 02:53:37</start>
<answer>2016-04-29 02:53:44</answer>
<end>2016-04-29 02:53:49</end>
<duration>12</duration>
<billsec>5</billsec>
<disposition>ANSWERED</disposition>
<amaflags>DOCUMENTATION</amaflags>
<uniqueid>1461920017.7</uniqueid>
<userfield>Internal</userfield>
<channel_ext>1000</channel_ext>
<dstchannel_ext>1001</dstchannel_ext>
<service>s</service>
<caller_name>John Doe</caller_name>
<recordfiles>auto-1461920017-1000-1001.wav@</recordfiles>
<dstanswer>1001</dstanswer>
<chanext/>
<dstchanext/>
<session>1461920017104140-1000</session>
<action_owner>1000</action_owner>
<action_type>DIAL</action_type>
<src_trunk_name/>
<dst_trunk_name/>
</sub_cdr>
<sub_cdr>
<AcctId>2</AcctId>
<accountcode/>
<src>1000</src>
<dst>1002</dst>
<dcontext>from-internal-xfer</dcontext>
<clid>"John Doe" <1000></clid>
<channel>PJSIP/1000-00000003</channel>
<dstchannel>PJSIP/1002-00000005</dstchannel>
<lastapp>Dial</lastapp>
<lastdata>PJSIP/1002/sip:1002@192.168.124.136:5066,60,ztTkKb(callee-handler^s^1)</lastdata>
<start>2016-04-29 02:53:49</start>
<answer>2016-04-29 02:53:49</answer>
<end>2016-04-29 02:53:54</end>
<duration>4</duration>
<billsec>4</billsec>
<disposition>ANSWERED</disposition>
<amaflags>DOCUMENTATION</amaflags>
<uniqueid>1461920017.7</uniqueid>
<userfield>Internal</userfield>
<channel_ext>1000</channel_ext>
<dstchannel_ext>1002</dstchannel_ext>
<service>s</service>
<caller_name>John Doe</caller_name>
<recordfiles/>
<dstanswer>1002</dstanswer>
<chanext/>
<dstchanext/>
<session>1461920017104140-1000</session>
<action_owner>1001</action_owner>
<action_type>TRANSFER</action_type>
<src_trunk_name/>
<dst_trunk_name/>
</sub_cdr>
</cdr>
</root>

JSON Output

In general, the JSON output format looks like below:

{cdr_root:[
{
cdr: xxxx-xxxx,
main_cdr:{...},
sub_cdr_1:{...},
...
sub_cdr_n:{...}
},
...
{
cdr: xxxx-xxxx,
src: 2003,
...,
action_type:DIAL
}]
}

• cdr_root represents the JSON array that has all the call records in this query.
• The above result highlighted in red indicates the current call. The “cdr” value is the unique identifier for this call, similar to the <session> element in XML format output.
• main_cdr is the primary record displayed.
• sub_cdr_x is the sub record for this call.

Example:

Assuming the following scenario:

Extension A: 5000

Extension B: 5001

Extension C: 5002

A calls B🡪B answers🡪B Transfers the call to C.

• The JSON output format for the above scenario looks like this:

{
"cdr_root": [
{
"cdr": "1461920017104140-1000",
"main_cdr": {
"AcctId": "",
"accountcode": "",
"src": "1000",
"dst": "1001",
"dcontext": "",
"clid": "",
"channel": "",
"dstchannel": "",
"lastapp": "",
"lastdata": "",
"start": "2016-04-29 02:53:37",
"answer": "",
"end": "",
"duration": "16",
"billsec": "9",
"disposition": "",
"amaflags": "",
"uniqueid": "",
"userfield": "",
"channel_ext": "",
"dstchannel_ext": "",
"service": "",
"caller_name": "",
"recordfiles": "",
"dstanswer": "",
"chanext": "",
"dstchanext": "",
"session": "1461920017104140-1000",
"action_owner": "",
"action_type": "DIAL",
"src_trunk_name": "",
"dst_trunk_name": ""
},
"sub_cdr_1": {
"AcctId": "1",
"accountcode": "",
"src": "1000",
"dst": "1001",
"dcontext": "from-internal",
"clid": "\"John Doe\" <1000>",
"channel": "PJSIP/1000-00000003",
"dstchannel": "PJSIP/1001-00000004",
"lastapp": "Dial",
"lastdata": "PJSIP/1001/sip:1001@192.168.124.179:5066,60,ztTkKA(dialog-being-recorded)M(reco",
"start": "2016-04-29 02:53:37",
"answer": "2016-04-29 02:53:44",
"end": "2016-04-29 02:53:49",
"duration": "12",
"billsec": "5",
"disposition": "ANSWERED",
"amaflags": "DOCUMENTATION",
"uniqueid": "1461920017.7",
"userfield": "Internal",
"channel_ext": "1000",
"dstchannel_ext": "1001",
"service": "s",
"caller_name": "John Doe",
"recordfiles": "auto-1461920017-1000-1001.wav@",
"dstanswer": "1001",
"chanext": "",
"dstchanext": "",
"session": "1461920017104140-1000",
"action_owner": "1000",
"action_type": "DIAL",
"src_trunk_name": "",
"dst_trunk_name": ""
},
"sub_cdr_2": {
"AcctId": "2",
"accountcode": "",
"src": "1000",
"dst": "1002",
"dcontext": "from-internal-xfer",
"clid": "\"John Doe\" <1000>",
"channel": "PJSIP/1000-00000003",
"dstchannel": "PJSIP/1002-00000005",
"lastapp": "Dial",
"lastdata": "PJSIP/1002/sip:1002@192.168.124.136:5066,60,ztTkKb(callee-handler^s^1)",
"start": "2016-04-29 02:53:49",
"answer": "2016-04-29 02:53:49",
"end": "2016-04-29 02:53:54",
"duration": "4",
"billsec": "4",
"disposition": "ANSWERED",
"amaflags": "DOCUMENTATION",
"uniqueid": "1461920017.7",
"userfield": "Internal",
"channel_ext": "1000",
"dstchannel_ext": "1002",
"service": "s",
"caller_name": "John Doe",
"recordfiles": "",
"dstanswer": "1002",
"chanext": "",
"dstchanext": "",
"session": "1461920017104140-1000",
"action_owner": "1001",
"action_type": "TRANSFER",
"src_trunk_name": "",
"dst_trunk_name": ""
}
}
]
}

CSV Output

 AcctId,accountcode,src,dst,dcontext,clid,channel,dstchannel,lastapp,lastdata,start,answer,end,duration,billsec,disposition,amaflags,uniqueid,userfield,channel_ext,dstchannel_ext,service,caller_name,recordfiles,dstanswer,chanext,dstchanext,session,action_owner,action_type,src_trunk_name,dst_trunk_name
1201,,6039,6011,from-internal,"GVC Test" <6039>,PJSIP/6039-0000069e,PJSIP/6011-0000069f,Dial,"PJSIP/6011/sip:6011@218.17.227.162:5062&PJSIP/6011/sip:6011@218.17.227.163:38102,30",2015-11-10 17:58:47,,2015-11-10 17:58:51,4,0,NO ANSWER,DOCUMENTATION,1447207127.4182,Internal,6039,6011,s,GVC Test,,,,1447207127558984-6039,6039,DIAL,, 

REC API – Access Call Recording Files

REC API URL Format

The format of the HTTPS request for the REC API is shown below. This is used to request call recordings, or a list of recording files within the Asterisk spool directories, matching given parameters as set by the third-party application.

https://[UCM IP]:[Port]/recapi?[option1]=[value]&[option2]=[value]&…

By default, the port number for the API is 8443.

REC API URL Parameters

REC API takes two parameters: filedir and filename. Both parameters are optional, and the response depends on which parameters are included in the request.

• Case 1: Neither parameter is set.

Example Request:

https://192.168.254.200:8443/recapi

Response:

A CSV file listing all directories under ast_config_AST_SPOOL_DIR.

• Case 2: Only filedir is set.

In this case, multiple file directories are supported, separated by ‘@’.

Example Request:

https://192.168.254.200:8443/recapi?filedir=monitor@meetme@voicemail/default

Response:

A CSV file listing the contents of each directory listed (relative to ast_config_AST_SPOOL_DIR).

• Case 3: Both filedir and filename are set.

In this case, multiple file names are supported, separated by ‘@’; multiple file directories are not currently supported.

Example Request:

Response:

The matching WAV file (if only one valid file found, in WAV format).

-OR-

A tarball containing all matching files, named [timestamp].tar, where the timestamp is set at the start of the API callback function.

-OR-

404: Not Found (if no matching files are found).

• Case 4: Only filename is set.

This case is the same as Case 3, with the file directory defaulting to “monitor”.

Example Request:

Response:

See Case 3.