XML: <Transfer>

The Transfer verb is used to bridge another party onto the current call.

Attributes

Attribute Description
transferCallerId (optional) The caller ID to use when the call is transferred, if different. Must be in E.164 format (e.g. +15555555555).

Note: Leave blank to pass along the number of the remote party
callTimeout (optional) This is the timeout (in seconds) for the callee to answer the call. Range: decimal values between 1 - 300
transferCompleteUrl (optional) URL to send the Transfer Complete event to and request new BXML.
transferCompleteMethod (optional) The HTTP method to use for the request to transferCompleteUrl. GET or POST. Default value is POST.
username (optional) The username to send in the HTTP request to transferCompleteUrl.
password (optional) The password to send in the HTTP request to transferCompleteUrl.
tag (optional) A custom string that will be sent with this and all future callbacks unless overwritten by a future tag attribute or cleared.

May be cleared by setting tag=""

Max length 256 characters.
diversionTreatment (optional) Can be any of the following:
none: 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.

Defaults to none. If diversionTreatment is not specified, no diversion header will be included for the transfer even if one came with the inbound call.
diversionReason (optional) 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. Defaults to unknown.

When the called party hangs up, if the transferCompleteUrl attribute is specified, the TransferComplete callback is sent to the transferCompleteUrl and the BXML returned by that callback are executed. Verbs following the <Transfer> will be ignored when the transferCompleteUrl attribute is specified.

If no transferCompleteUrl is specified, no event will be sent, and execution of verbs following the <Transfer> tag continues when the called party hangs up.

Nested Tags

Between 1 and 8 <PhoneNumber> tags must be nested within the <Transfer> tag to define the called parties. If more than one <PhoneNumber> is specified, called parties will ring simultaneously and the first to answer will be bridged to the original call:

Verb Description
PhoneNumber A collection of phone numbers to transfer the call to. The first to answer will be transferred.

PhoneNumber attributes

Attribute Description
transferAnswerUrl (optional) URL, if any, to send the Transfer Answer event to and request BXML to be executed for the called party before the call is bridged
transferAnswerMethod (optional) The HTTP method to use for the request to transferAnswerUrl. GET or POST. Default value is POST.
username (optional) The username to send in the HTTP request to transferAnswerUrl.
password (optional) The password to send in the HTTP request to transferAnswerUrl.
tag (optional) A custom string that will be sent with this and all future callbacks unless overwritten by a future tag attribute or cleared.

May be cleared by setting tag=""

Max length 256 characters.

When the called party answers, if the transferAnswerUrl is specified, the Transfer Answer callback is sent to the transferAnswerUrl and the BXML returned by that callback is executed. That BXML is executed only for the called party. At the conclusion of that BXML, the calls are bridged.

Callbacks Received

Callbacks Can reply with more BXML
Transfer Answer Yes
Transfer Complete Yes

Example 1 of 3: Simple Transfer

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

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence gender="male">Transferring your call, please wait.</SpeakSentence>
    <Transfer transferCallerId="+15554567891">
        <PhoneNumber>+15554567892</PhoneNumber>
    </Transfer>
</Response>
Response response = new Response();

PhoneNumber phoneNumber1 = new PhoneNumber();
phoneNumber1.Number = "+11234567892";

Transfer transfer = new Transfer();
transfer.PhoneNumbers = new PhoneNumber[] { phoneNumber1 };
transfer.TransferCallerId = "+11234567891";

response.Add(transfer);

Console.WriteLine(response.ToBXML());
response = Bandwidth::Voice::Response.new()
phone_number = Bandwidth::Voice::PhoneNumber.new({
    :number => "+11234567892"
})
transfer = Bandwidth::Voice::Transfer.new({
    :transfer_caller_id => "+11234567891",
    :phone_numbers => [phone_number]
})

response.push(transfer)
puts response.to_bxml()
phone_number = PhoneNumber(
    number="+11234567892"
)
transfer = Transfer(
    transfer_caller_id="+11234567891",
    phone_numbers=[phone_number]
)

response.add_verb(transfer)
print(response.to_bxml())

Example 2 of 3: Single Transfer with Announcement

This shows how to use Bandwidth XML to transfer a phone call with a pre-bridge announcement.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence voice="paul">Transferring your call, please wait.</SpeakSentence>
    <Transfer transferCallerId="+15554567891">
        <PhoneNumber transferAnswerUrl="http://myapp.com/announcement">+15554567892</PhoneNumber>
    </Transfer>
</Response>
Response response = new Response();

SpeakSentence speakSentence = new SpeakSentence();
speakSentence.Sentence = "Transferring your call, please wait.";

PhoneNumber phoneNumber1 = new PhoneNumber();
phoneNumber1.Number = "+11234567892";
phoneNumber1.TransferAnswerUrl = "http://myapp.com/announcement";

Transfer transfer = new Transfer();
transfer.PhoneNumbers = new PhoneNumber[] { phoneNumber1 };
transfer.TransferCallerId = "+11234567891";

response.Add(speakSentence);
response.Add(transfer);

Console.WriteLine(response.ToBXML());
response = Bandwidth::Voice::Response.new()
speak_sentence = Bandwidth::Voice::SpeakSentence.new({
    :sentence => "Transferring your call, please wait.",
    :voice => "paul"
})
phone_number = Bandwidth::Voice::PhoneNumber.new({
    :number => "+11234567892",
    :transfer_answer_url => "http://myapp.com/announcement"
})
transfer = Bandwidth::Voice::Transfer.new({
    :transfer_caller_id => "+11234567891",
    :phone_numbers => [phone_number]
})

response.push(speak_sentence)
response.push(transfer)
puts response.to_bxml()
response = Response()
speak_sentence = SpeakSentence(
    sentence="Transferring your call, please wait.",
    voice="paul"
)
phone_number = PhoneNumber(
    number="+11234567892",
    transfer_answer_url="http://myapp.com/announcement"
)
transfer = Transfer(
    transfer_caller_id="+11234567891",
    phone_numbers=[phone_number]
)

response.add_verb(speak_sentence)
response.add_verb(transfer)
print(response.to_bxml())

The announcement BXML at http://myapp.com/announcement is:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence voice="paul">A customer would like to speak to you.</SpeakSentence>
</Response>
Response response = new Response();

SpeakSentence speakSentence = new SpeakSentence();
speakSentence.Sentence = "A customer would like to speak to you.";

response.Add(speakSentence);

Console.WriteLine(response.ToBXML());
speak_sentence = Bandwidth::Voice::SpeakSentence.new({
    :sentence => "Transferring your call, please wait.",
    :voice => "paul"
})
speak_sentence = SpeakSentence(
    sentence="Transferring your call, please wait.",
    voice="paul"
)

Example 3 of 3: Multi transfer

This example shows how to use Bandwidth XML in a multi transfer scenario. All numbers ring simultaneously and the first to answer is bridged to the original call.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Transfer transferCallerId="+15552221235">
        <PhoneNumber>+15552221234</PhoneNumber>
        <PhoneNumber>+15552221233</PhoneNumber>
    </Transfer>
</Response>
Response response = new Response();

PhoneNumber phoneNumber1 = new PhoneNumber();
phoneNumber1.Number = "+15552221234";

PhoneNumber phoneNumber2 = new PhoneNumber();
phoneNumber2.Number = "+15552221233";

Transfer transfer = new Transfer();
transfer.PhoneNumbers = new PhoneNumber[] { phoneNumber1, phoneNumber2 };
transfer.TransferCallerId = "+15552221235";

response.Add(transfer);

Console.WriteLine(response.ToBXML());
response = Bandwidth::Voice::Response.new()
phone_number_1 = Bandwidth::Voice::PhoneNumber.new({
    :number => "+15552221234"
})
phone_number_2 = Bandwidth::Voice::PhoneNumber.new({
    :number => "+15552221233"
})
transfer = Bandwidth::Voice::Transfer.new({
    :transfer_caller_id => "+15552221235",
    :phone_numbers => [phone_number_1, phone_number_2]
})

response.push(transfer)
puts response.to_bxml()
phone_number_1 = PhoneNumber(
    number="+15552221234"
)
phone_number_2 = PhoneNumber(
    number="+15552221233"
)
transfer = Transfer(
    transfer_caller_id="+15552221235",
    phone_numbers=[phone_number_1, phone_number_2]
)

response.add_verb(transfer)
print(response.to_bxml())

results matching ""

    No results matching ""