How to make Outbound Calls

In this guide we will show you how to make outbound calls using Bandwidth's platform. Please ensure you have followed our quick start guide and ordered your first phone number.

You can embed outbound calling capabilities directly into your application or product using our API without having to handle legacy telecom infrastructure.

Make an outbound call

To create an outbound call from a Bandwidth number, you must make a POST request to our API v2 /calls endpoint. This can be done through our SDKs, using tools like Postman, or in command line.

Request Payload

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

POST https://voice.bandwidth.com/api/v2/accounts/{accountId}/calls
//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": "http://example.test/callbacks/answer",
    }'

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.
    CreateCall createCall = new CreateCall(); // CreateCall | JSON object containing information to create an outbound call
    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/answer",
)

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, CallbackMethodEnum } 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 BASE_CALLBACK_URL = process.env.BASE_CALLBACK_URL;

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

const callsApi = new CallsApi(config);

const callBody = {
    applicationId: BW_VOICE_APPLICATION_ID,
    to: USER_NUMBER,
    from: BW_NUMBER,
    displayName: 'NodeJS SDK',
    answerUrl: `${BASE_CALLBACK_URL}/callbacks/answer`,
    answerMethod: CallbackMethodEnum.Post,
    disconnectUrl: `${BASE_CALLBACK_URL}/callbacks/disconnect`,
    disconnectMethod: CallbackMethodEnum.Get,
    callTimeout: 30.0,
    callbackTimeout: 15.0
};

const { status, data } = await callsApi.createCall(BW_ACCOUNT_ID, callBody);

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());
}

note

The default call timeout is set to 30 seconds. For optimal performance and to minimize the risk of unsuccessful calls, we recommend configuring a call timeout of at least 40 seconds. This adjustment helps to accommodate scenarios where a timeout of 30 seconds or less may be insufficient.

After this call is created, Bandwidth will send a webhook to the answerUrl, expecting BXML in response to continue the call with your chosen action.

What is BXML?

BXML webhooks are HTTP requests made by the Bandwidth platform to endpoints specified by you in your HTTP requests and BXML.

Their purpose is to

• Inform you of events that have happened in the call flow
• Receive instructions from your application on what to do next.

More information on BXML can be found here.

Where to next?

Now that you have made your first outbound call, some of the available BXML/API actions are available in the following guides:

• How to play media and perform text to speech
• How to record calls & transcribe
• How to gather user input (IVR)
• How to use voicemail detection
• How to create conference calls
• How to retrieve call logs