Skip to main content

Voice


The Bandwidth Voice API allows you to handle incoming and outgoing PSTN phone calls using HTTP and JSON webhooks, giving you complete control over any call flow.

Base URL

https://voice.bandwidth.com/api/v2/accounts/{accountId}

Note HTTP requests to our API use HTTP Basic authentication, which refers to your account's username and password.

Calls

For help on how to make the proper requests to the API, check out the API Reference section of the docs. To quickly start making and receiving calls, check out the guide.

Creation/Acceptance

A POST to /calls creates a call object in Bandwidth's network and returns a unique callId corresponding to the new call. When creating a call you provide an answerUrl in the request body, and upon the call being answered, Bandwidth will send a webhook to the provided URL to inform your application and retrieve BXML from it in order to continue with the call.

To handle inbound calls to your Bandwidth numbers - you associate a voice application to a group of numbers, known as a Location or Sip-Peer. When incoming calls are received to any of those numbers, Bandwidth sends an initiate event webhook to the URL defined in your application and expects BXML in the HTTP response to continue with the call.

Call Directions

The direction of which the call is coming from may determine how/where callbacks are sent and whether they may submit more BXML. The direction of a call is either inbound or outbound. Inbound calls refer to calls received by your application, and outbound calls are calls that originate from your application (via API requests or BXML verbs).

BXML

Bandwidth XML allows you to create a voice application as easily as you create a web application. Using Bandwidth XML (or BXML) your application handles incoming call events using standard action verbs that are described in XML.

When calls or call events occur - Bandwidth will send a request (webhook) to your service, expecting BXML in the HTTP response body to continue the call.

Webhooks

The Voice API uses a number of different webhooks to facilitate call control. Certain webhooks expect BXML in the HTTP response to keep the call alive, while others are simply informative. These are also referred to as "callbacks".

STIR/SHAKEN

The Bandwidth API uses STIR/SHAKEN to help combat fraudulent calls and phone number spoofing. This info can be seen in the initiate webhook. For more information, look here for Bandwidth's explanation of what it is and why it's important.

Features and Services of Note

Text-to-Speech

Use our SpeakSentence verb to convert typed words to audible speech on the call. Powered by Amazon Polly, which allows us to support seventeen voices and twenty-six languages. Use SSML to customize your audio to include pauses, emphasis, and much more.

Recording

With the Record verb, you can save calls to play back or analyze later.

Transcription

Convert your calls to text using the Record verb's transcribe function.

Conferencing

The Conference BXML Verb allows you to create conference calls—including with the coach feature that allows for a call to be selectively bridged with certain calls within a conference.

Answering Machine Detection

Answering Machine Detection allows you to determine whether a human or a machine has answered a call.

Caller Name Service (CNAM)

Bandwidth's Caller Name service provides the business name on VoIP calls in the US and Canada using our CNAM database. This feature is not enabled by default.

Storage

Media

The Voice API allows you to playback audio files to end users on phone calls. Only .wav and .mp3 files are supported at this time and Bandwidth recommends limiting audio files to less than 1 hour in length or 250 MB in size.

Recordings

Bandwidth will keep recordings for up to 30 days. After 30 days, recordings will be deleted from Bandwidth controlled servers.

Transcriptions

Bandwidth will keep transcriptions for up to 30 days. After 30 days, transcriptions will be deleted from Bandwidth controlled servers.

Supported Languages and Environments

SDKs are provided for Java, C#, Ruby, NodeJs, Python, and PHP. Examples of the Bandwidth library in these languages are provided throughout the docs.