How to Retrieve Call Information

In this guide we will show you how to retrieve call information Bandwidth's platform. Please ensure you have followed our earlier guide on how to make an outbound call with Bandwidth.

Call information can provide information such as how the call ended, the length of the call, any errors that may have occurred, recording info, and more about the call.

Retrieve Call Information

Call information can be retrieved during or after a call has completed. The call information is near-real time, so it may take a few minutes for your call to be accessible using this endpoint.

To show how this works, first place an outbound call using our API.

Request Payload

Note: Remember to add authentication for your application if needed!

POST https://voice.bandwidth.com/api/v2/accounts/{accountId}
//Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD
{
    "from": "{BW_NUMBER}",
    "to": "{$USER_NUMBER}",
    "applicationId": "{APPLICATION_ID}",
    "answerUrl": "http://example.test/callbacks/answer",
}

cURL

Note: Remember to add authentication for your application if needed!

curl 'https://voice.bandwidth.com/api/v2/accounts/{BW_ACCOUNT_ID}/calls' \
    -X POST \
    -u '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \
    -H 'Content-Type: application/json' \
    -d '{
        "from": "{BW_NUMBER}",
        "to": "{$USER_NUMBER},
        "applicationId": "{APPLICATION_ID}",
        "answerUrl": "{ANSWER_URL}",
    }'

Java

import com.bandwidth.sdk.ApiClient;
import com.bandwidth.sdk.ApiException;
import com.bandwidth.sdk.Configuration;
import com.bandwidth.sdk.auth.*;
import com.bandwidth.sdk.models.*;
import com.bandwidth.sdk.api.CallsApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost");

    // Configure HTTP basic authorization: Basic
    HttpBasicAuth Basic = (HttpBasicAuth) defaultClient.getAuthentication("Basic");
    Basic.setUsername("YOUR USERNAME");
    Basic.setPassword("YOUR PASSWORD");

    CallsApi apiInstance = new CallsApi(defaultClient);
    String accountId = "9900000"; // String | Your Bandwidth Account ID.
    String voiceApplicationId = "BW_VOICE_APPLICATION_ID";
    String to = "USER_NUMBER";
    String from = "BW_NUMBER";
    String baseUrl = "BASE_CALLBACK_URL";
    String answerUrl = baseUrl.concat("/callbacks/answer");


    CreateCall createCall = new CreateCall(); // CreateCall | JSON object containing information to create an outbound call
      createCall.setApplicationId(voiceApplicationId);
      createCall.setTo(to);
      createCall.setFrom(from);
      createCall.setAnswerUrl(answerUrl);

    try {
      CreateCallResponse result = apiInstance.createCall(accountId, createCall);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling CallsApi#createCall");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

C#

using System;
using System.Threading.Tasks;
using Bandwidth.Standard;
using Bandwidth.Standard.Exceptions;
using Bandwidth.Standard.Voice.Models;

class Program
{
    static async Task Main(string[] args)
    {
        var username = System.Environment.GetEnvironmentVariable("BW_USERNAME");
        var password = System.Environment.GetEnvironmentVariable("BW_PASSWORD");
        var accountId = System.Environment.GetEnvironmentVariable("BW_ACCOUNT_ID");
        var applicationId = System.Environment.GetEnvironmentVariable("BW_VOICE_APPLICATION_ID");
        var to = System.Environment.GetEnvironmentVariable("USER_NUMBER");
        var from = System.Environment.GetEnvironmentVariable("BW_NUMBER");
        var baseUrl = System.Environment.GetEnvironmentVariable("BASE_CALLBACK_URL");
        var answerUrl = string.Concat(baseUrl, "/callbacks/answer");

        var client = new BandwidthClient.Builder()
            .VoiceBasicAuthCredentials(username, password)
            .Build();

        var request = new CreateCallRequest()
        {
            ApplicationId = applicationId,
            To = to,
            From = from,
            AnswerUrl = answerUrl
            //remember to add auth for your application if needed!
        };

        try
        {
            var response = await client.Voice.APIController.CreateCallAsync(accountId, request);
            Console.WriteLine(response.Data);
        }
        catch (ApiException e)
        {
            Console.WriteLine(e.Message);
        }
    }
}

Ruby

require 'bandwidth-sdk'

Bandwidth.configure do |config|
  config.username = ENV.fetch('BW_USERNAME')
  config.password = ENV.fetch('BW_PASSWORD')
end

calls_api_instance = Bandwidth::CallsApi.new

call_body = Bandwidth::CreateCall.new(
  application_id: ENV.fetch('BW_VOICE_APPLICATION_ID'),
  to: ENV.fetch('USER_NUMBER'),
  from: ENV.fetch('BW_NUMBER'),
  answer_url: "#{ENV.fetch('BASE_CALLBACK_URL')}/callbacks/outboundCall",
)

begin
  result = calls_api_instance.create_call(ENV.fetch('BW_ACCOUNT_ID'), call_body)
  p result.call_id
rescue Bandwidth::ApiError => e
  p e.code
end

NodeJS

import { CallsApi, Configuration } from 'bandwidth-sdk';

const BW_USERNAME = process.env.BW_USERNAME;
const BW_PASSWORD = process.env.BW_PASSWORD;
const BW_ACCOUNT_ID = process.env.BW_ACCOUNT_ID;
const BW_VOICE_APPLICATION_ID = process.env.BW_VOICE_APPLICATION_ID;
const BW_NUMBER = process.env.BW_NUMBER;
const USER_NUMBER = process.env.USER_NUMBER;
const VOICE_CALLBACK_URL = process.env.VOICE_CALLBACK_URL;

const config = new Configuration({
    BW_USERNAME,
    BW_PASSWORD
});

const callsApi = new CallsApi(config);

const makeCall = async () => {
    try {
        const { status, data } = await callsApi.createCall(BW_ACCOUNT_ID, {
            applicationId: BW_VOICE_APPLICATION_ID,
            to: USER_NUMBER,
            from: BW_NUMBER,
            answerUrl: VOICE_CALLBACK_URL,
            answerMethod: 'POST',
            callTimeout: 30.0
        });
        console.log(data);
    } catch (error) {
        console.error(error);
    }
};

makeCall();

Python

import os
import bandwidth
from pprint import pprint

configuration = bandwidth.Configuration(
    username=os.environ["BW_USERNAME"],
    password=os.environ["BW_PASSWORD"]
)

with bandwidth.ApiClient(configuration) as api_client:
    api_instance = bandwidth.CallsApi(api_client)
    account_id = os.environ["BW_ACCOUNT_ID"]
    create_call = bandwidth.CreateCall(
        to=os.environ["USER_NUMBER"],
        var_from=os.environ["BW_NUMBER"],
        answer_url=os.environ["VOICE_CALLBACK_URL"],
        application_id=os.environ["BW_VOICE_APPLICATION_ID"],
    )

try:
    api_response = api_instance.create_call(account_id, create_call)
    print("The response of CallsApi->create_call:\n")
    pprint(api_response)
except Exception as e:
    print("Exception when calling CallsApi->create_call: %s\n" % e)

PHP

require "vendor/autoload.php";

$BW_USERNAME = getenv("BW_USERNAME");
$BW_PASSWORD = getenv("BW_PASSWORD");
$BW_ACCOUNT_ID = getenv("BW_ACCOUNT_ID");
$BW_VOICE_APPLICATION_ID = getenv("BW_VOICE_APPLICATION_ID");
$BW_NUMBER = getenv("BW_NUMBER");
$USER_NUMBER = getenv("USER_NUMBER");
$VOICE_CALLBACK_URL = getenv("VOICE_CALLBACK_URL");

$config = new BandwidthLib\Configuration(
    array(
        'voiceBasicAuthUserName' => $BW_USERNAME,
        'voiceBasicAuthPassword' => $BW_PASSWORD,
    )
);
$client = new BandwidthLib\BandwidthClient($config);

$voiceClient = $client->getVoice()->getClient();

$body = new BandwidthLib\Voice\Models\CreateCallRequest();
$body->from = $BW_NUMBER;
$body->to = $USER_NUMBER;
$body->answerUrl = $VOICE_CALLBACK_URL;
$body->applicationId = $BW_VOICE_APPLICATION_ID;
#remember to add auth for your application if needed!

try {
    $response = $voiceClient->createCall($BW_ACCOUNT_ID, $body);
    print_r($response->getResult()->callId);
} catch (BandwidthLib\APIException $e) {
    print_r($e->getResponseCode());
}

Using the unique callId returned in the response, we will make a POST request to our API v2 /calls/{callId} endpoint to retrieve the call's information.

cURL

Note: Remember to add authentication for your application if needed!

curl 'https://voice.bandwidth.com/api/v2/accounts/{accountId}/calls/{callId}' \
    -u {BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}

Java

import com.bandwidth.sdk.ApiClient;
import com.bandwidth.sdk.ApiException;
import com.bandwidth.sdk.Configuration;
import com.bandwidth.sdk.auth.*;
import com.bandwidth.sdk.models.*;
import com.bandwidth.sdk.api.CallsApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost");

    // Configure HTTP basic authorization: Basic
    HttpBasicAuth Basic = (HttpBasicAuth) defaultClient.getAuthentication("Basic");
    Basic.setUsername("YOUR USERNAME");
    Basic.setPassword("YOUR PASSWORD");
    String accountId = "9900000"; // String | Your Bandwidth Account ID.

    try {

      ApiResponse<CallState> response = api.getCallStateAsync(accountId, callId);
      System.out.println(response);
    } catch (ApiException e) {
      System.err.println(e.getMessage());
      e.printStackTrace();
    }
  }
}

C#

using System;
using System.Threading.Tasks;
using Bandwidth.Standard;
using Bandwidth.Standard.Exceptions;
using Bandwidth.Standard.Voice.Models;

class Program
{
    static async Task Main(string[] args)
    {
        var username = System.Environment.GetEnvironmentVariable("BW_USERNAME");
        var password = System.Environment.GetEnvironmentVariable("BW_PASSWORD");
        var accountId = System.Environment.GetEnvironmentVariable("BW_ACCOUNT_ID");

        var client = new BandwidthClient.Builder()
            .VoiceBasicAuthCredentials(username, password)
            .Build();

        var callId = {CALL_ID};

        try
        {
            var response = await client.Voice.APIController.GetCallAsync(accountId, callId);
            Console.WriteLine(response.Data);
        }
        catch (ApiException e)
        {
            Console.WriteLine(e.Message);
        }
    }
}

Ruby

require 'bandwidth-sdk'

Bandwidth.configure do |config|
  config.username = ENV.fetch('BW_USERNAME')
  config.password = ENV.fetch('BW_PASSWORD')
end

calls_api_instance = Bandwidth::CallsApi.new

begin
  result = calls_api_instance.get_call(ENV.fetch('BW_ACCOUNT_ID'), ENV.fetch('CALL_ID'))
  p result.call_id
rescue Bandwidth::ApiError => e
  p e.code
end

NodeJS

import { CallsApi, Configuration } from 'bandwidth-sdk';

const BW_USERNAME = process.env.BW_USERNAME;
const BW_PASSWORD = process.env.BW_PASSWORD;
const BW_ACCOUNT_ID = process.env.BW_ACCOUNT_ID;

const config = new Configuration({
    BW_USERNAME,
    BW_PASSWORD
});

const callsApi = new CallsApi(config);

const getCall = async () => {
    try {
        const callId = 'c-abc12345-6defabc1-2345-6def-abc1-23456defabc1';
        const { status, data } = await callsApi.getCallState(
            BW_ACCOUNT_ID,
            callId
        );
        console.log(data);
    } catch (error) {
        console.error(error);
    }
};

getCall();

Python

import os
import bandwidth
from pprint import pprint

configuration = bandwidth.Configuration(
    username=os.environ["BW_USERNAME"],
    password=os.environ["BW_PASSWORD"]
)

with bandwidth.ApiClient(configuration) as api_client:
    api_instance = bandwidth.CallsApi(api_client)
    account_id = os.environ["BW_ACCOUNT_ID"]
    call_id = 'c-15ac29a2-1331029c-2cb0-4a07-b215-b22865662d85'

try:
    api_response = api_instance.get_call_state(account_id, call_id)
    print("The response of CallsApi->get_call_state:\n")
    pprint(api_response)
except Exception as e:
    print("Exception when calling CallsApi->get_call_state: %s\n" % e)

PHP

require "vendor/autoload.php";

$BW_USERNAME = getenv("BW_USERNAME");
$BW_PASSWORD = getenv("BW_PASSWORD");
$BW_ACCOUNT_ID = getenv("BW_ACCOUNT_ID");

$config = new BandwidthLib\Configuration(
    array(
        'voiceBasicAuthUserName' => $BW_USERNAME,
        'voiceBasicAuthPassword' => $BW_PASSWORD,
    )
);
$client = new BandwidthLib\BandwidthClient($config);

$voiceClient = $client->getVoice()->getClient();

$callId = {CALL_ID};

try {
    $response = $voiceClient->getCall($BW_ACCOUNT_ID, $callId);
    print_r($response->getResult()->callId);
} catch (BandwidthLib\APIException $e) {
    print_r($e->getResponseCode());
}

In the example above we have placed an outbound call and then retrieved the call information. Call information is kept for 7 days after the calls are hung up. If you attempt to retrieve information for a call that is older than 7 days, you will get an HTTP 404 response.

A call may have disconnected for several reasons. For example, if a call is rejected by the callee then a rejected state would appear in the disconnectCause. A list of possible values can be found here.

Where to next?

Now that you have learnt how to retrieve call information, check out some of the available actions in the following guides:

• How to manage queued calls