Skip to main content

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

AttributeDescription
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.

TagDescription
PhoneNumberA phone number to transfer the call to. Value must be in E.164 format (e.g. +15555555555).
SipUriA SIP URI to transfer the call to (e.g. sip:user@server.com).

PhoneNumber attributes

AttributeDescription
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

AttributeDescription
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

WebhooksCan reply with more BXML
Transfer AnswerYes
Transfer CompleteYes
Transfer DisconnectNo

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>

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>

Multi Transfer

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