×

To get call details of a CCM call, you will need to make an HTTP GET request to

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/calls/<call_sid>

Example (For Singapore Stamp)-

GET

https://<your_api_key>:<your_api_token>@ccm-api.exotel.com/v2/accounts/<your_sid>/calls/<call_sid>

Example (For Mumbai Stamp)

GET

https://<your_api_key>:<your_api_token>@ccm-api.in.exotel.com/v2/accounts/<your_sid>/calls/<call_sid>

  • Replace <your_api_key> and <your_api_token> with the API key and token created by you OR use Basic Authentication.
  • Replace <your_sid> with your “Account sid”
  • Replace <subdomain> with the region of your account
    1. <subdomain> of Singapore cluster is @ccm-api.exotel.com
    2. <subdomain> of Mumbai cluster is @ccm-api.in.exotel.com
  • Replace <call_sid> with the Call Sid provided during CCM Make Call API request.

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

curl -X GET 
  https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/calls/<call_sid> 
  -H 'content-type: application/json' 

var request = require("request");

var options = { method: 'GET',
  url: 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/calls/<call_sid>',
  headers: 
   { 'content-type': 'application/json' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
<?php

$request = new HttpRequest();
$request->setUrl('https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/calls/<call_sid>');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'content-type' => 'application/json',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
import requests

url = "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/calls/<call_sid>"

headers = {
'content-type': "application/json"
    }

response = requests.request("GET", url, headers=headers)

print(response.text)
package main

import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)

func main() {

url := "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/calls/<call_sid>"

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("content-type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)

fmt.Println(res)
fmt.Println(string(body))

}

HTTP Response:

  • On success, the HTTP response status code will be 200
  • the HTTP body will contain an JSON similar to the one below:
  • Example Response
{
    "request_id": "57ba69db00c0432e88a5ca6d644bbd40",
    "method": "GET",
    "http_code": 200,
    "metadata": null,
    "response": {
        "code": 200,
        "error_data": null,
        "status": "success",
        "data": {
            "call_sid": "72827ead13a355d334338f53af71157s",
            "direction": "outbound",
            "virtual_number": "+91804568XXXX",
            "call_state": "terminal",
            "call_status": "completed",
            "assigned_agent_details": {
                "user_id": "12898c52573645739e64864ad308f0a9",
                "user_name": "Sarthak XXXX",
                "contact_uri": "+9199531XXXXX",
                "group_id": null,
                "group_name": null,
                "status": "completed"
            },
            "customer_details": {
                "contact_name": "Sarthak XXXXX",
                "contact_uri": "+9199531XXXXX",
                "status": "completed"
            },
            "created_time": "2021-07-28T03:07:12+05:30",
            "updated_time": "2021-07-28T03:07:33+05:30",
            "start_time": "2021-07-28T03:07:18+05:30",
            "end_time": "2021-07-28T03:07:32+05:30",
            "total_duration": null,
            "total_talk_time": 7,
            "custom_field": "12130y124b2f142",
            "app_id": null,
            "app_name": null,
            "digits": null,
            "recordings": [
                {
                    "url": "https://s3-ap-southeast-1.amazonaws.com/exotelrecordings/XXXXX/72827ead13a355d334338fXXXXXX.mp3"
                }
            ]
        }
    }
}

Details of GET API response-

Parameter Name Type & Value
request_id This indicates the unique id of the request. Useful for debugging and tracing purposes.
method This indicates the HTTP method for the request such as GET/POST/PUT etc.
http_code This indicates the HTTP code for the request such as 200, 400, 500 etc.
response

Response block contains the user device record matching the request URI. The block contains

  • code - This indicates the http code for the particular record in the response array like 200, 400 etc.
  • error_data - This block will be null if there is no error else contain error information for the response with following fields
    • code - This would be the error code useful for Exotel's team to debug and can be highlighted in case of unexpected errors.
    • description - This describes the details of the error.
    • message - This is the error message corresponding to the error code useful for Exotel's team to debug and can be highlighted in case of unexpected errors.
  • status - This field would indicate status of the response (success/failure).
  • data - This block will contain the information corresponding to the response array element and will contain the fields for a user record as explained below. 

Description of parameters under 'data' block:

Parameter Name Description
call_sid

string; an alpha-numeric unique identifier of the call
direction
  • inbound - Incoming call to a virtual number (Exophone)
  • outbound - Outbound calls (Initiated by the agent via Dashboard or API)
virtual_number

The virtual number (ExoPhone) where the call landed (Incoming) or was used to initiate the call (Outgoing)
call_state
  • active: call is not yet over OR post call processing data is yet to be processed
  • terminal: call is over and data is processed against it
call_status
  • completed - Call is completed and agent/customer had a conversation.
  • agent_unanswered - Agent leg was unanswered due to various reasons such as switched off, not reachable, no-answer, busy, connection failed etc.
  • customer_unanswered - Customer leg was unanswered due to various reasons such as switched off, not reachable, no-answer, busy, connection failed etc.
  • agent_canceled - Agent canceled the call while customer was dialed. This could happen during ringing, blank calls or during an operator message such as switched off, no-answer, busy etc.
  • customer_no_dial - There was no dial initiated to customer (rare scenario)
  • agent_no_dial - There was no dial initiated to agent (rare scenario)
assigned_agent_details

assigned_agent_details will be the details of the agent who is the primary agent assigned for the call. In case of-

  • Outbound Connecting 2 numbers: Assigned agent is corresponding to user_contact_uri as provided in 'from'  for outbound call connecting 2 numbers (Leg1)
  • Inbound / Outbound flow calls: Assigned agent is corresponding to the last agent that was attempted in the call flow (including transfer) who may or may not have answered (Leg2)

Fields

  • "user_id": unique UUID of the agent
  • "name": Name of the agent
  • "contact_uri": Phone Number or SIP device URI of the agent’s device
  • "group_id":  group id of which agent was part of as per the call attempt else set to null (in case of outgoing or direct transfer to agent)
  • "group_name": Name corresponding to the group id
  • "call_status": Indicates the call status of the agent leg
    • in-progress - The call was answered and is currently in progress
    • completed - The call was answered and has ended normally
    • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
    • busy - The caller received a busy signal
    • no-answer - The call ended without being answered
customer_details

This is the number the caller called from (for inbound calls), or the number the call was placed to (for outbound calls), and is equal to

  • leg2 (outbound call connecting 2 numbers)
  • leg1 (inbound calls / outbound call connecting to flow)

Fields-

  • "contact_name": Customer Name as stored in Address Book otherwise set as null
  • "contact_uri": Customer Phone Number
  • "call_status": Indicates the call status of the customer leg
    • in-progress - The call was answered and is currently in progress
    • completed - The call was answered and has ended normally
    • failed - The call could not be completed as dialled, most likely because the phone number was non-existent
    • busy - The caller received a busy signal
    • no-answer - The call ended without being answered
    • null - customer leg was not dialled or N/A
created_time

DateTime as per ISO 8601 date format at which the user initiated the call via API.
Eg- 2021-07-28T02:59:34+05:30
updated_time DateTime as per ISO 8601 date format at which the call data was last updated in our system
Eg- 2021-07-28T02:59:34+05:30
start_time DateTime as per ISO 8601 date format when the call request was initiated to the operator
Eg- 2021-07-28T02:59:34+05:30
end_time DateTime as per ISO 8601 date format when the call ended
Eg- 2021-07-28T02:59:34+05:30
total_duration Total call duration in seconds (From start_time to end_time)
total_talk_time

Total time a customer was on call. If there were more than one conversation, it would be the sum of all conversations.

Eg- Agent 1 spoke to Customer for 5 minutes and transferred to Agent 2 and spoke to customer for 10 minutes, total_talk_time for the call would be 15 minutes.
custom_field The value that was passed in the custom_field parameter of the API (if set during the request) will be populated here.
app_id

Flow ID which was used at the start of the call. Null if flow was not used.
app_name Flow Name which was used at the start of the call. Null if flow was not used.
digits

DTMF digits pressed during the call separated by “-” for different applets. Similar to how it is represented in Call Reports.
recordings

Array; It will contain all recordings associated with the call. Each array will contain

  • url - This will represent the playable URL for the corresponding recording

*Some of the above parameters would be null if not applicable for that call.

Possible error scenarios in case of this GET API - 

Http Code Error Code Description
404 3043 Call not found / unsupported in this API
404 3044 Call not found / unsupported in this API
404 3045 Call not found / unsupported in this API
500 1100 Internal Server Error
500 3042 Internal Server Error
500 3046 Internal Server Error
500 3075 Internal Server Error

*These will be populated under the `error_data` block of response