How to Transfer a Call

In this guide we will show you how to transfer an incoming call.

Transferring calls allows you to transfer the caller to the right person rather than them hanging up and calling a different number, providing an excellent tool for customer service.

Transfer an incoming call

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

XML

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

Java

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

C#

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

Transfer transfer = new Transfer
{
    PhoneNumbers = new PhoneNumber[] { phoneNumber }
};

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

Console.WriteLine(response.ToBXML());

Ruby

phone_number = Bandwidth::Bxml::PhoneNumber.new('+11234567892')
transfer = Bandwidth::Bxml::Transfer.new([phone_number])
response = Bandwidth::Bxml::Response.new([transfer])

p response.to_bxml

NodeJS

const phoneNumber = new Bxml.PhoneNumber('+11234567892');
const transfer = new Bxml.Transfer(undefined, [phoneNumber]);
const response = new Bxml.Response(transfer);

console.log(response.toBxml());

Python

phone_number = PhoneNumber(
    number="+11234567892"
)

transfer = Transfer(
    phone_numbers=[phone_number]
)

response = Response()
response.add_verb(transfer)

print(response.to_bxml())

PHP

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

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

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

echo $response->toBxml();

Above is a basic transfer scenario where an inbound call is transferred to a different phone number (+11234567892) instead of the number called.

Transfer a Call with an Announcement and Different Caller Id

While transferring a call you can also combine this with an announcement using our text-to-speech service with the transferAnswerUrl verb.

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.

XML

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence>Thank you for calling Scrooge and Marley! Please hold while we connect you to an associate.</SpeakSentence>
    <Transfer transferCallerId="+15555555555">
        <PhoneNumber transferAnswerUrl="/announcement">+15555555554</PhoneNumber>
    </Transfer>
</Response>

> The announcement endpoint response from `/announcement` is:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence>Hey! There's a customer on the line.</SpeakSentence>
</Response>

Java

@Post /incoming_calls endpoint
public String transfer_to_bob() {

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);


    SpeakSentence speakSentence = new SpeakSentence("Thank you for calling Scrooge and Marley! Please hold while we connect you to an associate.");

    PhoneNumber phoneNumber = new PhoneNumber("+15555555554").builder()
            .transferAnswerUrl("/announcement")
            .build();

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

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

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

@POST /announcement endpoint
public byte[] alert() {
    SpeakSentence speakSentence = new SpeakSentence("Hey! There's a customer on the line.");

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

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

C#

@Post [/incoming_calls]
public ActionResult transfer_to_bob() {
    SpeakSentence speakSentence = new SpeakSentence
    {
        Sentence = "Thank you for calling Scrooge and Marley! Please hold while we connect you to an associate.",
    };

    PhoneNumber phoneNumber = new PhoneNumber
    {
        Number = "+15555555554",
        TransferAnswerUrl = "/announcement"
    };


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

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

    Console.WriteLine(response.ToBXML());
    return new OkObjectResult(response.ToBXML());
}

@Post [/announcement]
public ActionResult alert() {
    SpeakSentence speakSentence = new SpeakSentence
    {
        Sentence = "Hey! There's a customer on the line.",
    };

    Response response = new Response();
    response.Add(speakSentence);
    Console.WriteLine(response.ToBXML());
    return new OkObjectResult(response.ToBXML());
}

Ruby

post '/incoming_calls' do
  speak_sentence = Bandwidth::Bxml::SpeakSentence.new('Thank you for calling Scrooge and Marley! Please hold while we connect you to an associate.')
  phone_number = Bandwidth::Bxml::PhoneNumber.new('+15555555554', { transfer_answer_url: '/announcement' })
  transfer = Bandwidth::Bxml::Transfer.new([phone_number], { transfer_caller_id: '+15555555555' })
  response = Bandwidth::Bxml::Response.new([speak_sentence, transfer])

  return response.to_bxml
end

post '/announcement' do
  speak_sentence = Bandwidth::Bxml::SpeakSentence.new("Hey! There's a customer on the line.")
  response = Bandwidth::Bxml::Response.new([speak_sentence])

  return response.to_bxml
end

NodeJS

@POST ['/incoming_calls'] (req, res) => {
    const speakSentence = new Bxml.SpeakSentence(
        'Thank you for calling Scrooge and Marley! Please hold while we connect you to an associate.'
    );
    const phoneNumber = new Bxml.PhoneNumber('+15555555554', {
        transferAnswerUrl: '/announcement'
    });
    const transfer = new Bxml.Transfer(
        {
            transferCallerId: '+15555555555'
        },
        [phoneNumber]
    );
    const response = new Bxml.Response([speakSentence, transfer]);

    console.log(response.toBxml());
    res.status(200).send(response.toBxml());
}

@POST ['/announcement'] (req, res) => {
    const speakSentence = new Bxml.SpeakSentence("Hey! There's a customer on the line.");
    const response = new Bxml.Response(speakSentence);

    console.log(response.toBxml());
    res.status(200).send(response.toBxml());
}

Python

@POST '/incoming_calls'
def transfer_to_bob():
    speak_sentence = SpeakSentence(
        text="Thank you for calling Scrooge and Marley! Please hold while we connect you to an associate."
    )

    phone_number = PhoneNumber(
        number="+15555555554",
        transfer_answer_url="/announcement"
    )

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

    response = Response()
    response.add_verb(speak_sentence)
    response.add_verb(transfer)

    print(response.to_bxml())
    return response.to_bxml()

@POST '/announcement'
def alert():
    speak_sentence = SpeakSentence(
        text="Hey! There's a customer on the line."
    )
    response = Response()
    response.add_verb(speak_sentence)
    print(response.to_bxml())
    return response.to_bxml()

PHP

@POST('/incoming_calls)
function transfer_to_bob(Request $request, Response $response) {
    $speakSentence = new BandwidthLib\Voice\Bxml\SpeakSentence("Thank you for calling Scrooge and Marley! Please hold while we connect you to an associate.");

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

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

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

    echo $response->toBxml();
    $bxml = $bxmlResponse->toBxml();
    $response = $response->withStatus(200)->withHeader('Content-Type', 'application/xml');
    $response->getBody()->write($bxml);
    return $response;
}

@POST('/announcement)
function alert(Request $request, Response $response) {
    $speakSentence = new BandwidthLib\Voice\Bxml\SpeakSentence("Hey! There's a customer on the line.");
    $response = new BandwidthLib\Voice\Bxml\Response();

    $response->addVerb($speakSentence);
    $response = $response->withStatus(200)->withHeader('Content-Type', 'application/xml');
    $response->getBody()->write($response->toBxml());
    return $response;
}

This announcement will be played on the call for the called party before it is bridged.

Where to next?

Now that you have learnt how to transfer an inbound call, check out some of the available actions in the following guides:

• How to retrieve call info