Bandwidth XML (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.

Before we begin creating a new BXML application you’ll need two things initially setup:

  1. A phone number that is allocated to your Bandwidth Application Platform account and is configured to an application. For instructions on setting up your application, read the applications page

  2. A public Web site that you can create content on and will handle the requests for BXML. Note that the endpoint for this site should be used to create the application in you setup above.

The maximum size of a BXML document is 64 KB.

Understanding BXML Callback Events

BXML callbacks are HTTP requests made by the Bandwidth platform to endpoints specified by you in your HTTP requests and BXML. Their purpose is to 1) inform you of events that have happened in the call flow and 2) receive instructions from your application on what to do next.

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.

The first BXML callback is made when the call is created with POST /calls as the answerUrl field. Subsequent callbacks are made by specifying event-specific *Url attributes on the appropriate verbs. If a relative URL is provided in BXML, it is resolved relative to the request that retrieved that BXML.

If BXML execution ends without performing a callback, there is an implicit <Hangup> at the end of the document.


Verb Description
<Forward> The Forward verb is used to forward an unanswered incoming call to another number.
<Gather> The Gather verb is used to collect DTMF digits.
<Hangup> The Hangup verb is used to hang up or reject a call.
<Pause> The Pause verb is used to delay verb execution for a period of time.
<PauseRecording> The PauseRecording verb is used to pause a recording previously started by a <StartRecording> verb.
<PlayAudio> The PlayAudio verb is used to play an audio file in the call.
<Record> The Record verb allows a segment of audio to be recorded during a call.
<Redirect> The Redirect verb is used to redirect the current XML execution to another URL.
<ResumeRecording> The ResumeRecording verb is used to resume a recording previously paused by a <PauseRecording> verb.
<SendDtmf> The SendDtmf verb is used to play DTMF digits in the call.
<SpeakSentence> The SpeakSentence verb converts text into audible speech.
<StartRecording> The StartRecording verb allows a segment of a call to be recorded while other verbs are executing.
<StopRecording> The StopRecording verb stops a recording that was previously started by a <StartRecording>.
<Transfer> The Transfer verb is used to transfer the call to another number.

BXML Callbacks

BXML callbacks are HTTP messages that are sent to your application server to notify you of activity related to your Bandwidth resources during a BXML usage.

Callback Description
Answer Bandwidth API sends this when the call is answered.
Gather Bandwidth API sends this when a <Gather> is completed.
Initiate Bandwidth API sends this when an inbound call arrives.
Record Complete Bandwidth API sends this when a <Record> is completed. The recording is not available to download until the Recording Available event is received.
Redirect Bandwidth API sends this when a <Redirect> is requested or when a POST request is made to the /calls/{callId} endpoint requesting a redirect.
Transfer Answer Bandwidth API sends this when a <Transfer> is answered.
Transfer Complete Bandwidth API sends this when the <Transfer> is complete and the original call needs to continue.

Asynchronous Callbacks

Callback Description
Disconnect Bandwidth API sends this when a call ends.
Recording Available Bandwidth API sends this when a recording started by either a <StartRecording> or a <Record> verb is available for download.
Transfer Disconnect Bandwidth API sends this when any leg of a <Transfer> ends.
Transcription Available Bandwidth API sends this when the transcription of a recording is available for download.

results matching ""

    No results matching ""