Skip to main content

DevStack, Voice

Much ado about transferring… a call

Austin Bello Austin Bello
Austin Bello
Share

To transfer, or not to transfer, that is the question. Well, that’s just one of the questions. You may also be wondering what a transfer is or how to implement it yourself. If you have any of these questions, you’ve come to the right place! We’ll discuss the many variations within transferring, including when and how to use each of them.

Let’s start by first defining what a transfer is. A transfer takes place when a call is routed to a different phone number than what was originally dialed. You’ll also hear the term forward or call forwarding, which is similar enough to transferring to discuss them side by side, but there is a slight and meaningful difference. In a transfer, the call is answered, whether by an agent or an Interactive Voice Response (IVR). Whereas in a forward, the call is diverted prior to being answered. This slight difference will come into play later. We’ll start with transfer methods that can done via the Bandwidth Dashboard and API, and then pivot to those that can only be done via API.

Call forwarding as a line feature

We’ll start with the simplest option—the blind call forward. This feature can be set up either using the Bandwidth Dashboard or using our Numbers API. Bandwidth offers a variety of features that can be updated at an individual phone number level. One of these features is Call Forwarding, which allows you to set an alternate phone number to redirect incoming calls to. We’ll call this a “blind” call forward because the number that a call will be forwarded to is determined prior to the call and you don’t have any visibility at call time.

Call Forwarding is often used for SEO or Ad Tracking use cases, where there are several virtual phone numbers distributed among different locations or mediums that each have the same final destination. Metrics like number of calls and average length of call can be used to determine the effectiveness of the ad. This method is also great for messaging customers that want a quick and easy way to direct incoming phone calls to a certain number rather than returning a busy tone.
Setting a call forwarding number can be done within the Bandwidth Dashboard or via our Numbers API.

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/tns/{tn}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SipPeerTelephoneNumber>
    <CallForward>7042661720</CallForward>
</SipPeerTelephoneNumber>

One difference between call forwarding as a line feature and the methods to come is that it does not use Bandwidth’s Voice API. This means that there is no need to stand up a server to handle call control, but there also won’t be the real time statistics that come with the Voice API. Call data can be retrieved via Billing Detail Records (BDRs), but it is important to note that it typically takes 24-48 hours for a phone call to be accessed in a BDR.

<Forward>

The rest of the sections will discuss methods utilizing Bandwith’s Voice API. The Voice API leverages Bandwidth XML (or BXML), which is a call control language that provides instructions for how to handle call events using action verbs. One of these action verbs is <Forward>, which works very similarly to the call forwarding line feature. The major difference being that <Forward> provides visibility into the call in real time, which will enhance and expand the use cases that can be supported.

By having access to call information in real time, we can now add real time analytics to the call forwarding use cases discussed previously. Rather than relying on BDRs, the information needed to create meaningful insights will be delivered via callbacks. The <Forward> verb also allows you to support use cases where the call forwarding number is set at call time. A common application for this would be time of day routing, where you may, as an example, route the call to an agent’s business line during work hours and to their mobile phone otherwise.

Looking at the documentation for the <Forward> verb, it is pretty straightforward (pun intended). The only field that is required is the “to” number. The other fields can be used as needed, with the ability to set the “from” number probably being the most valuable. This provides the ability to set the caller id of the outgoing leg, which is typically used to mask the identity of the original caller.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <Forward from="+15554567890" to="+15557654321"/>
</Response>

<Transfer>

Let’s first recall that the difference between forwarding and transferring is whether or not the call is answered prior to routing. With the call being answered in a transfer, the supported use cases and functionality are expanded from that of forwarding.

The <Transfer> verb can be used to replicate any of the previously discussed use cases, but we now have the ability to route a call in the middle of an IVR. The classic example of when this would be used would be a call tree, where pressing 1 routes you to phone number A, pressing 2 routes you to phone number B, and so on. The <Transfer> verb also supports sim ring (simultaneous ringing) use cases, where multiple phone numbers receive a call and the first to answer is bridged in. Further, the <Transfer> verb allows for BXML to be executed for the called party prior to being bridged in. The most common use of this functionality would be to play an audio message to the called party informing them of who is calling them. This is traditionally referred to as call whisper.

There’s a lot more to digest with the <Transfer> documentation than what we just walked through with <Forward>. We are now introduced to three callback events: Transfer Complete, Transfer Answer, and Transfer Disconnect. The Transfer Complete and Transfer Answer events can both reply with new BXML, with Transfer Complete occurring when the transferred party disconnects and the Transfer Answer taking place when the transferred party answers. You could use Transfer Complete to make a new transfer attempt if the original transfer did not answer or provide the calling party with a survey or audio message after the call. Transfer Answer is primarily used to support the call whisper functionality discussed previously. Transfer Disconnect cannot respond with new BXML, and can be used for tracking when and why a transfer ended.

<?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>

<Bridge>

The <Transfer> verb gives us the ability to control the calling experience for the initial caller, but what if we need to control the experience for the transferred party as well? That’s where the <Bridge> verb comes in handy. The <Bridge> verb is used to bridge another party (target call) onto the current call.

By having the ability to control both legs of a call, any of the prior use cases can be supported as well as use cases where a survey or other action is needed to be taken by the transferred party when the calling party disconnects. Also, bridging adds the ability to provide sim ring functionality that does not necessarily award the call to the first to answer. You could choose to add an audio message informing the agents of who is calling and ask them to press a digit if they’d like to accept the call. In this example, the first agent to press a digit would be bridged with the caller.

The concept of two unique calls and the order of which they are bridged is important to understand when reading through the documentation for <Bridge>. We now have access to the Bridge Complete and Bridge Target Complete events, which allows new BXML to be executed in the event one of the parties leaves the call. If the transferred party leaves the call, the Bridge Complete event will be sent. If the originating party leaves the call, the Bridge Target Complete event will be sent.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence>The bridge will start now</SpeakSentence>
    <Bridge bridgeCompleteUrl="https://bridge.url/nextBXMLForSecondCall" bridgeTargetCompleteUrl="https://bridge.url/nextBXMLForFirstCall">
        c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d
    </Bridge>
</Response>

<Conference>

Last, but not least, we’ll touch on conferencing. Up until now, we’ve been limited to calls with two legs. <Conference> provides us the ability to have more than two legs on a call, and thus the ability to implement a warm transfer.

What is a warm transfer? There are several definitions out there, but for the purposes of this blog, we’ll define a warm transfer as a three-legged phone call where the called party connects and introduces the calling party with another agent before ultimately leaving the two to conduct their own call. A common example of this would be when a Sales Development Representative connects with a prospect and wants to introduce them to an Account Representative that will ultimately be able to conduct the sale. In addition to a warm transfer, all of the use cases we’ve discussed could be supported with <Conference>; however, there is an additional per leg charge associated with conferencing, so it should really only be used when 3 or more call legs are needed.

The <Conference> verb works similarly to <Bridge> in that you specify where to connect each call leg. While <Bridge> uses the call id, <Conference> uses a conference name that your application sets. Bandwidth will create a unique ID for the conference in the background, so your conference names can be whatever you want. Conferences are implicitly created the first time your application uses a conference name, and they are implicitly deleted when the last member leaves the conference. So, for the warm transfer example, you would make an outbound call to the third leg and place each of the three legs into the conference. The order in which you take these steps is less important due to that implicit creation of conferences.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence gender="male">You will be added to call now.</SpeakSentence>
    <Conference>warm-transfer</Conference>
</Response>
Developer console illustration

Learn more

Now that you are an expert in all things Transferring, go off and build your application! All of the documentation referenced can be found at the link below. Have questions about how Bandwidth's APIs can help you solve specific business needs? Get in touch and talk to our experts about what problems you're trying to solve and find out how we can help.

Talk to an expert Bandwidth Developer Resources