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:
-
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
-
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 your setup above.
The maximum size of a BXML document is 64 KB.
Note: Improperly formed or invalid BXML will cause the call to fail and generate a detailed error including the invalid BXML that is available to Bandwidth Customer Service. Please contact Bandwidth Customer Service with any questions.
Understanding BXML Webhook Events
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 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 webhooks 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 webhook is made when the call is created with POST /calls as
the answerUrl field. Subsequent webhooks 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 webhook, there is an implicit <Hangup> at the end of the document.
Verbs
| Verb | Description |
|---|---|
<Conference> | The Conference verb is used to add a call to a conference. |
<Bridge> | The Bridge verb is used to bridge two calls. |
<Pause> | The Pause verb is used to delay verb execution for a period of time. |
<Forward> | The Forward verb is used to forward an unanswered incoming call to another number. |
<Transfer> | The Transfer verb is used to transfer the call to another number. |
<Ring> | The Ring verb is used to play ringing audio on a call. |
<Hangup> | The Hangup verb is used to hang up or reject a call. |
<Redirect> | The Redirect verb is used to redirect the current XML execution to another URL. |
<PlayAudio> | The PlayAudio verb is used to play an audio file in the call. |
<SpeakSentence> | The SpeakSentence verb converts text into audible speech. |
<Record> | The Record verb allows a segment of audio to be recorded during a call. |
<StartRecording> | The StartRecording verb allows a segment of a call to be recorded while other verbs are executing. |
<PauseRecording> | The PauseRecording verb is used to pause a recording previously started by a <StartRecording> verb. |
<ResumeRecording> | The ResumeRecording verb is used to resume a recording previously paused by a <PauseRecording> verb. |
<StopRecording> | The StopRecording verb stops a recording that was previously started by a <StartRecording>. |
<Gather> | The Gather verb is used to collect DTMF digits. |
<StartGather> | The StartGather verb is used to collect DTMF digits during the execution of other verbs. |
<StopGather> | The StopGather verb stops the DTMF collection initiated by <StartGather>. |
<StartStream> | The StartStream verb allows a segment of a call to be streamed to an external destination. |
<StopStream> | The StopStream verb is used to stop a stream previously started by a <StartStream> verb. |
<StartTranscription> | The StartTranscription verb allows a segment of a call to be transcribed during the execution of other verbs. |
<StopTranscription> | The StopTranscription verb is used to stop a transcription previously started by a <StartTranscription> verb. |
<SendDtmf> | The SendDtmf verb is used to play DTMF digits in the call. |
<Tag> | The Tag verb is used to set a new tag value without executing a webhook. |
BXML Webhooks
BXML webhooks are HTTP messages that are sent to your application server to notify you of activity related to your Bandwidth resources during a BXML usage.
| Webhook | Description |
|---|---|
| Answer | Bandwidth API sends this when the call is answered. |
| Bridge Complete | Bandwidth API sends this to the application when a <Bridge> is complete and the original call needs to continue. |
| Bridge Target Complete | Bandwidth API sends this to the application when a <Bridge> is complete and the target call needs to continue. |
| 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 the <Transfer> is answered. |
| Transfer Complete | Bandwidth API sends this when the <Transfer> is complete and the original call needs to continue. |
| Conference Created | Bandwidth API sends this when a new conference is created. |
| Conference Member Join | Bandwidth API sends this when a new member joins a conference. |
| Conference Member Exit | Bandwidth API sends this when a member leaves a conference. |
| Conference Redirect | Bandwidth API sends this to the application when a POST request is made to the /conferences/{conferenceId} endpoint requesting to modify a conference. |
Asynchronous Webhooks
| Webhook | Description |
|---|---|
| Conference Completed | Bandwidth API sends this after the last member leaves the conference. |
| Conference Recording Available | Bandwidth API sends this when a recording started by a <StartRecording>in a conference is available for download. |
| Disconnect | Bandwidth API sends this when a call ends. |
| DTMF | Bandwidth API sends this for every digit detected after a <StartGather> is executed. |
| MediaStreamStarted | Bandwidth API sends this after the stream requested in a <StartStream> is started. |
| MediaStreamRejected | Bandwidth API sends this if a stream requested in a <StartStream> can not be started. |
| MediaStreamStopped | Bandwidth API sends this when a stream requested in a <StartStream> ends. |
| Recording Available | Bandwidth API sends this when a recording started by either a <StartRecording> or a <Record> verb in a call 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. |