transfer.md

{% method %}

XML: <Transfer>

The Transfer verb is used to transfer the call to another number. An attempt to transfer to an invalid destination completes the call and it is hung up. The Call leg A is hungup after the transferee hangs up. Therefore, any verbs following <Transfer> will not be executed.

Attributes

Attribute	Description
transferTo	(optional) Defines the number the call will be transferred to. Accepts phone number in E.164 format (e.g. +19195551212) or a SIP url (e.g. sip:[email protected])
transferCallerId	(optional) This is the caller id that will be used when the call is transferred. transferCallerId can be any number in the user's Bandwidth account. Note: Omitting the transferCallerId attribute will pass along the number of the original incoming call. (See example 1) Users with impersonation privledges can set the transferCallerId value to any value including private, unknown, and No Caller Id. To learn more about impersonation, contact support
callTimeout	(optional) This is the timeout (seconds) for the callee to answer the call. When the call times out, the program will continue to the next verb. Default 60 Max 300
requestUrl	(optional) Relative or absolute URL to send event and request new BXML when transferred call hangs up.
requestUrlTimeout	(optional) Timeout (milliseconds) to request new BXML.
tag	(optional) A string that will be included in the callback events of the transfer.
diversionTreatment	Can be any of the following: none: This is the default value. No diversion headers are sent on the outbound leg of the transferred call. propagate: Copy the Diversion header from the inbound leg to the outbound leg. Ignored if there is no Diversion header present on the inbound leg. stack: After propagating any Diversion header from the inbound leg to the outbound leg, stack on top another Diversion header based on the Request-URI of the inbound call. If diversionTreatment is not specified, no diversion header will be included for the transfer even if one came with the inbound call.
diversionReason	Can be any of the following values: unknown user-busy no-answer unavailable unconditional time-of-day do-not-disturb deflection follow-me out-of-service away This parameter is considered only when diversionTreatment is set to stack.

Nestable Verbs

These verbs might also be nested inside <Transfer>:

Verb	Description
PhoneNumber	(optional) A collection of phone numbers to transfer the call to. The first to answer will be transferred. This is in addition to the number specified in the transferTo attribute.
SpeakSentence	(optional) Using the SpeakSentence inside the Transfer verb will speak the text to the callee before transferring it.
PlayAudio	(optional) Using the PlayAudio inside the Transfer verb will play the media to the callee before transferring it.
Record	(optional) Using Record inside Transfer verb will record the transferred call.

The transfer will bridge the calls when all verbs inside Transfer were executed.

There can be a maximum of 7 phone numbers (including transferTo attribute) to try and transfer to .

Callbacks Recevied

Callbacks	Can reply with more BXML
Hangup	No
transferComplete	No

{% common %}

Example 1 of 4: Simple Transfer

This shows how to use Bandwidth XML to transfer a phone call.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Transfer transferTo="+11234567892">
   </Transfer>
</Response>

Example 2 of 4: Multi transfer

This example shows how to use Bandwidth XML in a multi transfer scenario.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Transfer transferCallerId="+15552221235">
        <PhoneNumber>+15552221234</PhoneNumber>
        <PhoneNumber>+15552221233</PhoneNumber>
        <SpeakSentence gender="male" locale="en_US" voice="paul">This call has been forwarded.</SpeakSentence>
    </Transfer>
</Response>

Example 3 of 4: New Caller Id and Transfer

This shows how to use Bandwidth XML to transfer a phone call.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence gender="male" locale="en_US" voice="paul">Transferring your call, please wait.</SpeakSentence>
    <Transfer transferCallerId="+11234567891" transferTo="+11234567892">
                <SpeakSentence gender="male" locale="en_US" voice="paul">Your call has been transfered.</SpeakSentence>
    </Transfer>
</Response>

Example 4 of 4: Transfer with outbound Diversion header information

This shows how to set variables for an outbound Diversion header

<?xml version="1.0" encoding="UTF-8"?>
    <Response>
    <Transfer diversionTreatment="stack" diversionReason="do-not-disturb">
        <PhoneNumber>+19195554444</PhoneNumber>
    </Transfer>
</Response>

{% endmethod %}