# Transfer

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

## Text Content[​](#text-content "Direct link to Text Content")

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

## Attributes[​](#attributes "Direct link to 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.<br /><br />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](/docs/voice/programmable-voice/webhooks/transferComplete.md) event to and request new BXML. Optional but recommended. [See below](#transfercompleteurl) 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](/docs/voice/programmable-voice/webhooks/transferComplete.md) callback delivery in case `transferCompleteUrl` fails to respond.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| transferCompleteFallbackMethod | (optional) The HTTP method to use to deliver the [Transfer Complete](/docs/voice/programmable-voice/webhooks/transferComplete.md) 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.<br /><br />May be cleared by setting `tag=""`<br /><br />Max length 256 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| diversionTreatment             | (optional) Can be any of the following:<br />`none`: No diversion headers are sent on the outbound leg of the transferred call.<br />`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.<br />`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.<br /><br />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.<br /><br />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:<br />`unknown`<br />`user-busy`<br />`no-answer`<br />`unavailable`<br />`unconditional`<br />`time-of-day`<br />`do-not-disturb`<br />`deflection`<br />`follow-me`<br />`out-of-service`<br />`away`<br /><br />This parameter is considered only when `diversionTreatment` is set to `stack`. Defaults to `unknown`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

### transferCompleteUrl[​](#transfercompleteurl "Direct link to transferCompleteUrl")

When the called party hangs up, if the `transferCompleteUrl` attribute is specified, the [TransferComplete](/docs/voice/programmable-voice/webhooks/transferComplete.md) 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](/docs/voice/programmable-voice/rateLimits.md). 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](/docs/voice/programmable-voice/webhooks/transferComplete.md) 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](/docs/voice/programmable-voice/webhooks/transferDisconnect.md).

### Nested Tags[​](#nested-tags "Direct link to 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[​](#phonenumber-attributes "Direct link to PhoneNumber 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`](https://tools.ietf.org/html/rfc7433). Only `base64`, `jwt` and `hex` 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](/docs/voice/programmable-voice/webhooks/transferAnswer.md) 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](/docs/voice/programmable-voice/webhooks/transferAnswer.md) callback delivery in case `transferAnswerUrl` fails to respond.                                                                                                                        |
| transferAnswerFallbackMethod | (optional) The HTTP method to use to deliver the [Transfer Answer](/docs/voice/programmable-voice/webhooks/transferAnswer.md) callback to `transferAnswerFallbackUrl`. GET or POST. Default value is POST.                                                                                                                                  |
| transferDisconnectUrl        | (optional) URL, if any, to send the [Transfer Disconnect](/docs/voice/programmable-voice/webhooks/transferDisconnect.md) 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.<br /><br />May be cleared by setting `tag=""`<br /><br />Max length 256 characters.                                                                                                             |

### SipUri attributes[​](#sipuri-attributes "Direct link to 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`](https://tools.ietf.org/html/rfc7433). Only `base64`, `jwt` and `hex` 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](/docs/voice/programmable-voice/webhooks/transferAnswer.md) 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](/docs/voice/programmable-voice/webhooks/transferAnswer.md) callback delivery in case `transferAnswerUrl` fails to respond.                                                                                                                        |
| transferAnswerFallbackMethod | (optional) The HTTP method to use to deliver the [Transfer Answer](/docs/voice/programmable-voice/webhooks/transferAnswer.md) callback to `transferAnswerFallbackUrl`. GET or POST. Default value is POST.                                                                                                                                  |
| transferDisconnectUrl        | (optional) URL, if any, to send the [Transfer Disconnect](/docs/voice/programmable-voice/webhooks/transferDisconnect.md) 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.<br /><br />May be cleared by setting `tag=""`<br /><br />Max length 256 characters.                                                                                                             |

When the called party answers, if the `transferAnswerUrl` is specified, the [Transfer Answer](/docs/voice/programmable-voice/webhooks/transferAnswer.md) 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](/docs/voice/programmable-voice/webhooks/transferDisconnect.md) 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-received "Direct link to Webhooks Received")

| Webhooks                                                                             | Can reply with more BXML |
| ------------------------------------------------------------------------------------ | ------------------------ |
| [Transfer Answer](/docs/voice/programmable-voice/webhooks/transferAnswer.md)         | Yes                      |
| [Transfer Complete](/docs/voice/programmable-voice/webhooks/transferComplete.md)     | Yes                      |
| [Transfer Disconnect](/docs/voice/programmable-voice/webhooks/transferDisconnect.md) | No                       |

## Examples[​](#examples "Direct link to Examples")

### Simple Transfer[​](#simple-transfer "Direct link to Simple Transfer")

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

* XML
* Java
* C#
* Ruby
* NodeJS
* Python
* PHP

```
<?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[​](#transfer-with-announcement "Direct link to Transfer With Announcement")

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

* XML
* Java
* C#
* Ruby
* NodeJS
* Python
* PHP

```
<?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[​](#multi-transfer "Direct link to Multi Transfer")

* XML
* Java
* C#
* Ruby
* NodeJS
* Python
* PHP

```
<?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();
```
