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}
//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.BandwidthClient;
import com.bandwidth.http.response.ApiResponse;
import com.bandwidth.voice.models.CreateCallRequest;
import com.bandwidth.voice.models.CreateCallResponse;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class Sample {
    public static final String USERNAME = System.getenv("BW_USERNAME");
    public static final String PASSWORD = System.getenv("BW_PASSWORD");
    public static final String ACCOUNT_ID = System.getenv("BW_ACCOUNT_ID");

    public static void main(String[] args) {
        String voiceApplicationId = System.getenv("BW_VOICE_APPLICATION_ID");
        String to = System.getenv("USER_NUMBER");
        String from = System.getenv("BW_NUMBER");
        String baseUrl = System.getenv("BASE_CALLBACK_URL");
        String answerUrl = baseUrl.concat("/callbacks/answer");

        BandwidthClient client = new BandwidthClient.Builder()
        .voiceBasicAuthCredentials(USERNAME, PASSWORD)
        .build();

        CreateCallRequest request = new CreateCallRequest();
        request.setApplicationId(voiceApplicationId);
        request.setTo(to);
        request.setFrom(from);
        request.setAnswerUrl(answerUrl);
        //remember to add auth for your application if needed!

        try {
            CompletableFuture<ApiResponse<CreateCallResponse>> completableFuture = client.getVoiceClient().getAPIController().createCallAsync(ACCOUNT_ID, request);
            System.out.println(completableFuture.get().getResult());
        } catch (InterruptedException | ExecutionException e) {
            System.out.println(e.getMessage());
        }
    }
}

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'

include Bandwidth
include Bandwidth::Voice

bandwidth_client = Bandwidth::Client.new(
    voice_basic_auth_user_name: ENV['BW_USERNAME'],
    voice_basic_auth_password: ENV['BW_PASSWORD']
)

voice_client = bandwidth_client.voice_client.client

body = CreateCallRequest.new
body.from = ENV['BW_NUMBER']
body.to = ENV['USER_NUMBER']
body.answer_url = ENV['BASE_CALLBACK_URL'] + "/callbacks/answer"
body.application_id = ENV['BW_VOICE_APPLICATION_ID']
#remember to add auth for your application if needed!

begin
    result = voice_client.create_call(ENV['BW_ACCOUNT_ID'], body)
    puts result.data.call_id
rescue APIException => e
    puts e.response_code
end

NodeJS

import { Client, ApiController } from '@bandwidth/voice';

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 client = new Client({
  basicAuthUserName: BW_USERNAME,
  basicAuthPassword: BW_PASSWORD
});

const controller = new ApiController(client);

const accountId = BW_ACCOUNT_ID;

const makeCall = async function() {
  try {
    const response = await controller.createCall(accountId, {
        applicationId: BW_VOICE_APPLICATION_ID,
        to: USER_NUMBER,
        from: BW_NUMBER,
        answerUrl: VOICE_CALLBACK_URL,
        answerMethod: 'POST',
        callTimeout: 30
        //remember to add auth for your application if needed!
    });
    console.log(response.body);
  } catch(error) {
      console.error(error);
  }
}

makeCall();

Python

from bandwidth.bandwidth_client import BandwidthClient
from bandwidth.voice.models.create_call_request import CreateCallRequest
from bandwidth.exceptions.api_exception import APIException

import os

BW_USERNAME = os.environ["BW_USERNAME"]
BW_PASSWORD = os.environ["BW_PASSWORD"]
BW_ACCOUNT_ID = os.environ["BW_ACCOUNT_ID"]
BW_VOICE_APPLICATION_ID = os.environ["BW_VOICE_APPLICATION_ID"]
BW_NUMBER = os.environ["BW_NUMBER"]
USER_NUMBER = os.environ["USER_NUMBER"]
VOICE_CALLBACK_URL = os.environ["VOICE_CALLBACK_URL"]

bandwidth_client = BandwidthClient(
    voice_basic_auth_user_name=BW_USERNAME,
    voice_basic_auth_password=BW_PASSWORD
)
voice_client = bandwidth_client.voice_client.client

body = CreateCallRequest()
body.application_id = BW_VOICE_APPLICATION_ID
body.to = USER_NUMBER
body.mfrom = BW_NUMBER
body.answer_url = VOICE_CALLBACK_URL
#remember to add auth for your application if needed!

try:
    response = voice_client.create_call(BW_ACCOUNT_ID, body)
    print(response.body.call_id)
except APIException as e:
    print(e.response_code)

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

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