Transfer

The Transfer verb is used to transfer a party onto an existing call.

Text Content

There is no text content available to be set for the <Transfer> verb.

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) even if `privacy` is set to true. Note: Leave blank to pass along the number of the remote party.
privacy	(optional) Hide the calling number. The `transferCallerDisplayName` field can be used to customize the displayed name.
transferCallerDisplayName	(optional) The caller display name to use when the call is transferred. May not exceed 256 characters nor contain control characters such as new lines. If `privacy` is true, only the following values are valid: `Restricted`, `Anonymous`, `Private`, or `Unavailable`.
callTimeout	(optional) The timeout (in seconds) for the callee to answer the call after it starts ringing. If the call does not start ringing within 30s, the call will be cancelled regardless of this value. Range: decimal values between 1 - 300. Default value is 30 seconds.
transferCompleteUrl	(optional) URL to send the Transfer Complete event to and request new BXML. Optional but recommended. See below for further details. May be a relative URL.
transferCompleteMethod	(optional) The HTTP method to use for the request to `transferCompleteUrl`. GET or POST. Default value is POST.
transferCompleteFallbackUrl	(optional) A fallback url which, if provided, will be used to retry the Transfer Complete callback delivery in case `transferCompleteUrl` fails to respond.
transferCompleteFallbackMethod	(optional) The HTTP method to use to deliver the Transfer Complete callback to `transferCompleteFallbackUrl`. 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`.
fallbackUsername	(optional) The username to send in the HTTP request to `transferCompleteFallbackUrl`.
fallbackPassword	(optional) The password to send in the HTTP request to `transferCompleteFallbackUrl`.
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. NOTE: Diversion treatment must not be used when transferring an outbound call made from the Programmable Voice application. It is to be used only when transferring an inbound call received by the Programmable Voice application.
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`.

transferCompleteUrl

When the called party hangs up, if the transferCompleteUrl attribute is specified, the TransferComplete callback is sent to the transferCompleteUrl, this callback is also sent if any problem occurs with the transfer, such as the callee is busy, doesn't answer, or the call gets rate limited. The BXML returned by that callback is executed on the original call. 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.

Note that the TransferComplete callback is only sent if the call is still active after the <Transfer> completes. If you need an event delivered for every <Transfer> regardless of how it ends, see the Transfer Disconnect.

Nested Tags

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

Tag	Description
PhoneNumber	A phone number to transfer the call to. Value must be in E.164 format (e.g. `+15555555555`).
SipUri	A SIP URI to transfer the call to (e.g. `sip:user@server.com`).

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. May be a relative URL.
transferAnswerMethod	(optional) The HTTP method to use for the request to `transferAnswerUrl`. GET or POST. Default value is POST.
transferAnswerFallbackUrl	(optional) A fallback url which, if provided, will be used to retry the Transfer Answer callback delivery in case `transferAnswerUrl` fails to respond.
transferAnswerFallbackMethod	(optional) The HTTP method to use to deliver the Transfer Answer callback to `transferAnswerFallbackUrl`. GET or POST. Default value is POST.
transferDisconnectUrl	(optional) URL, if any, to send the Transfer Disconnect event to. This event will be sent regardless of how the transfer ends and may not be responded to with BXML. May be a relative URL.
transferDisconnectMethod	(optional) The HTTP method to use for the request to `transferDisconnectUrl`. GET or POST. Default value is POST.
username	(optional) The username to send in the HTTP request to `transferAnswerUrl` and `transferDisconnectUrl`.
password	(optional) The password to send in the HTTP request to `transferAnswerUrl` and `transferDisconnectUrl`.
fallbackUsername	(optional) The username to send in the HTTP request to `transferAnswerFallbackUrl`.
fallbackPassword	(optional) The password to send in the HTTP request to `transferAnswerFallbackUrl`.
tag	(optional) A custom string that will be sent with these and all future callbacks unless overwritten by a future `tag` attribute or cleared. May be cleared by setting `tag=""` Max length 256 characters.

SipUri attributes

Attribute	Description
uui	(optional) The value of the `User-To-User` header to send within the initial `INVITE`. Must include the `encoding` parameter as specified in `RFC 7433`. Only `base64` and `jwt` encoding are currently allowed. This value, including the encoding specifier, may not exceed 256 characters.
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. May be a relative URL.
transferAnswerMethod	(optional) The HTTP method to use for the request to `transferAnswerUrl`. GET or POST. Default value is POST.
transferAnswerFallbackUrl	(optional) A fallback url which, if provided, will be used to retry the Transfer Answer callback delivery in case `transferAnswerUrl` fails to respond.
transferAnswerFallbackMethod	(optional) The HTTP method to use to deliver the Transfer Answer callback to `transferAnswerFallbackUrl`. GET or POST. Default value is POST.
transferDisconnectUrl	(optional) URL, if any, to send the Transfer Disconnect event to. This event will be sent regardless of how the transfer ends and may not be responded to with BXML. May be a relative URL.
transferDisconnectMethod	(optional) The HTTP method to use for the request to `transferDisconnectUrl`. GET or POST. Default value is POST.
username	(optional) The username to send in the HTTP request to `transferAnswerUrl` and `transferDisconnectUrl`.
password	(optional) The password to send in the HTTP request to `transferAnswerUrl` and `transferDisconnectUrl`.
fallbackUsername	(optional) The username to send in the HTTP request to `transferAnswerFallbackUrl`.
fallbackPassword	(optional) The password to send in the HTTP request to `transferAnswerFallbackUrl`.
tag	(optional) A custom string that will be sent with these 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.

When each leg of the transfer ends for any reason, if transferDisconnectUrl was set for that phone number, the Transfer Disconnect event will be sent to that URL. This event may not be responded to with BXML.

caution

There can be a maximum of 8 phone numbers to transfer to.

Webhooks Received

Webhooks	Can reply with more BXML
Transfer Answer	Yes
Transfer Complete	Yes
Transfer Disconnect	No

Examples

Simple Transfer

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

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

PhoneNumber phoneNumber = new PhoneNumber("+11234567892")

Transfer transfer = new Transfer().builder()
        .transferCallerId("+11234567891")
        .destinations(List.Of(phoneNumber))
        .build();

Response response = new Response()
        .with(transfer);

System.out.println(response.toBXML());

PhoneNumber phoneNumber = new PhoneNumber
{
    Number = "+11234567892"
};

Transfer transfer = new Transfer
{
    TransferCallerId = "+11234567891",
    PhoneNumbers = new PhoneNumber[] { phoneNumber }
};

Response response = new Response();
response.Add(transfer);

Console.WriteLine(response.ToBXML());

phone_number = Bandwidth::Bxml::PhoneNumber.new('+11234567892')
transfer = Bandwidth::Bxml::Transfer.new([phone_number], {
  transfer_caller_id: '+11234567891'
})
response = Bandwidth::Bxml::Response.new([transfer])

p response.to_bxml

const number = new Bxml.PhoneNumber('+11234567892');
const transfer = new Bxml.Transfer(
    {
        transferCallerId: '+11234567891'
    },
    [number]
);
const response = new Bxml.Response(transfer);

console.log(response.toBxml());

phone_number = PhoneNumber(
    number="+11234567892"
)

transfer = Transfer(
    transfer_caller_id="+11234567891",
    phone_numbers=[phone_number]
)

response = Response()
response.add_verb(transfer)

print(response.to_bxml())

$number = new BandwidthLib\Voice\Bxml\PhoneNumber("+11234567892");

$transfer = new BandwidthLib\Voice\Bxml\Transfer();
$transfer->transferCallerId("+11234567891");
$transfer->phoneNumbers(array($number));

$response = new BandwidthLib\Voice\Bxml\Response();
$response->addVerb($transfer);

echo $response->toBxml();

Transfer With Announcement

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

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence voice="paul">Transferring your call, please wait.</SpeakSentence>
    <Transfer transferCallerId="+11234567891">
        <PhoneNumber transferAnswerUrl="http://myapp.com/announcement">+11234567892</PhoneNumber>
    </Transfer>
</Response>

The announcement BXML response from 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>

SpeakSentence speakSentence = new SpeakSentence("Transferring your call, please wait.").builder()
        .voice(TtsVoice.PAUL)
        .build();

PhoneNumber phoneNumber = new PhoneNumber("+11234567892").builder()
        .transferAnswerUrl("http://myapp.com/announcement")
        .build();

Transfer transfer = new Transfer().builder()
        .transferCallerId("+11234567891")
        .destinations(List.Of(phoneNumber))
        .build();

Response response = new Response()
        .withVerbs(speakSentence, transfer);

System.out.println(response.toBXML());

The announcement BXML response from http://myapp.com/announcement is:

SpeakSentence speakSentence = new SpeakSentence("A customer would like to speak to you.").builder()
        .voice(TtsVoice.PAUL)
        .build();

SpeakSentence speakSentence = new SpeakSentence
{
    Sentence = "Transferring your call, please wait.",
    Voice = "paul"
};

PhoneNumber phoneNumber = new PhoneNumber
{
    Number = "+11234567892",
    TransferAnswerUrl = "http://myapp.com/announcement"
};


Transfer transfer = new Transfer
{
    TransferCallerId = "+11234567891",
    PhoneNumbers = new PhoneNumber[] { phoneNumber }
};

Response response = new Response();
response.Add(speakSentence);
response.Add(transfer);

Console.WriteLine(response.ToBXML());

The announcement BXML response from http://myapp.com/announcement is:

SpeakSentence speakSentence = new SpeakSentence
{
    Sentence = "A customer would like to speak to you.",
    Voice = "paul"
};

Response response = new Response();
response.Add(speakSentence);

Console.WriteLine(response.ToBXML());

speak_sentence = Bandwidth::Bxml::SpeakSentence.new('Transferring your call, please wait.', { voice: 'paul' })
phone_number = Bandwidth::Bxml::PhoneNumber.new('+11234567892', {
  transfer_answer_url: 'http://myapp.com/announcement'
})
transfer = Bandwidth::Bxml::Transfer.new([phone_number], {
  transfer_caller_id: '+11234567891'
})
response = Bandwidth::Bxml::Response.new([speak_sentence, transfer])

p response.to_bxml

The announcement BXML response from http://myapp.com/announcement is:

speak_sentence = Bandwidth::Bxml::SpeakSentence.new('A customer would like to speak to you.', {
  voice: 'paul'
})

const speakSentence = new Bxml.SpeakSentence(
    'Transferring your call, please wait.',
    {
        voice: 'paul'
    }
);
const number = new Bxml.PhoneNumber('+11234567892', {
    transferAnswerUrl: 'http://myapp.com/announcement'
});
const transfer = new Bxml.Transfer(
    {
        transferCallerId: '+11234567891'
    },
    [number]
);
const response = new Bxml.Response([speakSentence, transfer]);

console.log(response.toBxml());

The announcement BXML response from http://myapp.com/announcement is:

const speakSentence = new Bxml.SpeakSentence({
    sentence: 'A customer would like to speak to you.',
    voice: 'paul'
});

const response = new Bxml.Response(speakSentence);

console.log(response.toBxml());

speak_sentence = SpeakSentence(
    text="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 = Response()
response.add_verb(speak_sentence)
response.add_verb(transfer)

print(response.to_bxml())

The announcement BXML response from http://myapp.com/announcement is:

speak_sentence = SpeakSentence(
    text="A customer would like to speak to you.",
    voice="paul"
)

$speakSentence = new BandwidthLib\Voice\Bxml\SpeakSentence("Transferring your call, please wait.");
$speakSentence->voice("paul");

$number = new BandwidthLib\Voice\Bxml\PhoneNumber("+11234567892");

$transfer = new BandwidthLib\Voice\Bxml\Transfer();
$transfer->transferCallerId("+11234567891");
$transfer->phoneNumbers(array($number));

$response = new BandwidthLib\Voice\Bxml\Response();
$response->addVerb($speakSentence);
$response->addVerb($transfer);

echo $response->toBxml();

The announcement BXML response from http://myapp.com/announcement is:

$speakSentence = new BandwidthLib\Voice\Bxml\SpeakSentence("A customer would like to speak to you.");
$speakSentence->voice("paul");

Multi Transfer

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

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

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

Transfer transfer = new Transfer().builder()
        .transferCallerId("+15552221235")
        .destinations(List.Of(phoneNumber1, phoneNumber2))
        .build();

Response response = new Response()
        .with(transfer);

System.out.println(response.toBXML());

PhoneNumber phoneNumber1 = new PhoneNumber
{
    Number = "+15552221234"
};

PhoneNumber phoneNumber2 = new PhoneNumber
{
    Number = "+15552221233"
};

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

Response response = new Response();
response.Add(transfer);

Console.WriteLine(response.ToBXML());

phone_number_1 = Bandwidth::Bxml::PhoneNumber.new('+15552221234')
phone_number_2 = Bandwidth::Bxml::PhoneNumber.new('+15552221233')
transfer = Bandwidth::Bxml::Transfer.new([phone_number_1, phone_number_2], {
  transfer_caller_id: '+15552221235'
})
response = Bandwidth::Bxml::Response.new([transfer])

p response.to_bxml

const number1 = new Bxml.PhoneNumber('+15552221234');
const number2 = new Bxml.PhoneNumber('++15552221233');
const transfer = new Bxml.Transfer(
    {
        transferCallerId: '15552221235'
    },
    [number1, number2]
);
const response = new Bxml.Response(transfer);

console.log(response.toBxml());

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 = Response()
response.add_verb(transfer)

print(response.to_bxml())

$number1 = new BandwidthLib\Voice\Bxml\PhoneNumber("+15552221234");
$number2 = new BandwidthLib\Voice\Bxml\PhoneNumber("+15552221233");

$transfer = new BandwidthLib\Voice\Bxml\Transfer();
$transfer->transferCallerId("+15552221235");
$transfer->phoneNumbers(array($number1, $number2));

$response = new BandwidthLib\Voice\Bxml\Response();
$response->addVerb($transfer);

echo $response->toBxml();

Text Content​

Attributes​

transferCompleteUrl​

Nested Tags​

PhoneNumber attributes​

SipUri attributes​

Webhooks Received​

Examples​

Simple Transfer​

Transfer With Announcement​

Multi Transfer​

Text Content

Attributes

transferCompleteUrl

Nested Tags

PhoneNumber attributes

SipUri attributes

Webhooks Received

Examples

Simple Transfer

Transfer With Announcement

Multi Transfer