V1 → V2 Voice API Migration Guide

Follow

David Preo

Updated

Table of Contents

Key Differentiators

Credentials

Retrieving Call Data in V2

Migrating from V1 BXML

Migrating from V1 REST

Resources

 

To help prepare you to make the switch for your applications, our product experts have created this guide as an overview of the main significant changes from V1 to V2 in terms of the API functionality. If you find that you need additional support, you can reference the developer docs for Bandwidth’s V2 Voice API or contact support for further assistance.

 

Key Differentiators

First, let’s review the significant changes between the V1 Accounts API and V2 Accounts API and what this difference will look like in the API. 

DIFFERENCE

V1 V2
Types of APIs REST and BXML-oriented Primary BXML. Rest APIs are used to place an outbound call, modify an existing call, change recording state, and access recordings. All media actions are specified as BXML verbs.
Credentials Separate credentials for voice APIs and Bandwidth dashboard Unified credentials managed through Bandwidth dashboard
Georedundant No Yes
Callback URL Single callback URL for all actions Callback URL follows application flow
Number Management Performed in Application Platform portal or API  
Billing Performed in Application Platform portal. Uses credit card or postpaid  

 

Credentials

V1 and V2 both use Basic Auth.

In V1, the credentials were managed using the Voice & Messaging API Dashboard (sometimes called Catapult). These were distinct from the Bandwidth Dashboard credentials you may have used to manage your numbers.

In V2, you'll use a Bandwidth Dashboard username and password for both the voice and number management APIs. You may want to create a dedicated user for your application to use for placing calls. That user needs to have the “HttpVoice” role in order to call the voice APIs.

 

Retrieving Call Data in V2

In V2, you can't do a GET request on an endpoint to retrieve call data. It's up to you to store the data in the callbacks if you need that data later.

 

Migrating from V1 BXML

Verbs:

Gather

DIFFERENCE V1 V2
URL to send Gather events to and request new BXML requestUrl gatherUrl
gatherMethod A GET HTTP method will be used to make the request to the requestURL. Optional attribute to specify the HTTP method used to make the request to the gatherURL. Options are GET or POST. Default is POST, regardless of the method set in the Application.
terminatingDigits Default value is “#”. If changed from the default, can't be set to empty Default value is none.
maxDigits maxDigits Default value is 50. Range: integer values between 1-50
interDigitTimeout (optional) Integer time indicating the timeout between digits (Default value is 5 seconds). (optional) Time (in seconds) allowed between digit presses before automatically terminating the Gather. Default value is 5. Range: decimal values between 1 - 60.
firstDigitTimeout N/A (optional) Time (in seconds) to pause after any audio from nested <SpeakSentence> or <PlayAudio> verb is played (in seconds) before terminating the Gather. Default value is 5. Range: decimal values between 0 - 60.
repeatCount Could only be set within a PlayAudio verb

(optional) The number of times the audio prompt should be repeated if no digits are pressed. For example, if this value is 3, the nested audio clip will be played a maximum of three times. The delay between repetitions will be equal to firstDigitTimeout. Default value is 1. Range: 1-25.

SpeakSentence, in addition to PlayAudio, can now be repeated.

Nesting multiple audio verbs (ie. both PlayAudio and SpeakSentence) No Yes

 

Hangup

DIFFERENCE V1 V2
Can be used to reject incoming calls either explicitly or implicitly No Yes

 

Pause

DIFFERENCE V1 V2
Attribute Name length duration
Range 1-3600 seconds Decimal values between 0.1 - 86400

 

PlayAudio

DIFFERENCE V1 V2
Supported Files wav and .mp3 wav files encoded as PCM or G711
Volume Yes No
repeatCount, delayBeforeRepeat Yes Use repeatCount on the Gather verb

 

Redirect

DIFFERENCE V1 V2
URL to request new BXML from requestUrl redirectUrl
requestUrlTimeout Required Set to 5 second by default and is not configurable
redirectMethod A GET HTTP method will be used to make the request to the requestURL. Optional attribute to specify the HTTP method used to make the request to the redirectUrl. Options are GET or POST. Default is POST, regardless of the method set in the Application.
Username/Password protected HTTP request for sending Redirect events No Optional

 

SendDtmf

DIFFERENCE V1 V2
Maximum Characters 92 50

 

SpeakSentence

DIFFERENCE V1 V2
Volume Attribute Yes No
SSML Support No Yes
Support for es_mx locale Yes No

 

Transfer

DIFFERENCE V1 V2
transferTo (Simple Transfer) Supported All phone numbers must be listed as <PhoneNumber> tags nested in the <Transfer> tag.
Username/Password protected HTTP request for sending Redirect events No Optional
Audio Message to Callee Prior to Transferring SpeakSentence and PlayAudio are nestable verbs within Transfer. The transfer will bridge the calls when all verbs inside Transfer were executed. A transferAnswerUrl can be provided to send the Transfer Answer event to and request BXML to be executed for the called party before the call is bridged.
Max Amount of Phone Numbers to Transfer to 7 8
requestUrl attribute renamed to transferCompleteUrl

An optional attribute of requestUrl can be specified to send the Transfer Complete event to and request new BXML.

If the requestUrl event isn't needed, you may omit the requestUrl and continue placing BXML verbs after the Transfer verb and those verbs will be executed when the B leg hangs up.

Same, but the attribute is named transferCompleteUrl instead of requestUrl.
Callbacks Received Hangup and transferComplete Transfer Answer and Transfer Complete
Transferring to SIP URLs Supported Not supported. Only E.164 numbers are allowed.

 

Callbacks

V1

BXML callbacks perform HTTP GET requests to the requestUrl when the notification intends to retrieve a new BXML document. BXML applications only supported GET requests on the callback url for the answer event.

 

V2

BXML callbacks are HTTP POST requests by default. The request will have a JSON body that describes the event. It expects an XML response consisting of BXML verbs.

 

Other

HTTP GET requests may be used for callbacks by setting the appropriate Method attribute when specifying each callback's URL. If the GET method is used, the properties are passed as query parameters. This can cause very long URLs, which some web servers don't support, so POST is the preferred method.

 

Migrating from V1 REST

Voice V2 APIs utilize BXML because it provides advantages over REST in an event driven real-time communications environment. As such you should refactor your application to utilize the BXML capabilities of V2 as described in the previous sections. More information regarding BXML is available here.

 

Resources

Check out our Developer Docs for additional documentation.

Still have questions? Open a ticket with our support team. We're here to help!

Article is closed for comments.