TwiML™ Voice: <Refer>

The action attribute accepts a URL as its argument. This URL tells Twilio where to make a POST or GET request after the <Refer> verb finishes executing.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const refer = response.refer({
5
    action: '/handleRefer',
6
    method: 'POST'
7
});
8
refer.sip('sip:alice@example.com');
9

10
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Refer action="/handleRefer" method="POST">
4
        <Sip>sip:alice@example.com</Sip>
5
    </Refer>
6
</Response>

Twilio's request to this URL may include the following additional parameters:

Note that only <Refer>-specific parameters are listed here. Twilio will also send the standard TwiML Voice parameters in the request.

To further illustrate how the <Refer> parameters work, we have provided a few example scenarios:

1. Twilio issues a REFER, and the SIP endpoint successfully initiates a new call to the transfer target:

   • ReferCallStatus: "in-progress"
   • ReferSipResponseCode: "202"
   • NotifySipResponseCode: "200"

2. Twilio issues a REFER, and the SIP endpoint initiates a new call to the transfer target. However, the new call fails with an error:

   • ReferCallStatus: "busy" (or "failed" depending on the value of NotifySipResponseCode)
   • ReferSipResponseCode: "202"
   • NotifySipResponseCode: "486"

3. Twilio issue a REFER, but the SIP endpoint responds to the REFER with an error:

   • ReferCallStatus: "failed"
   • ReferSipResponseCode: "405"

4. The caller hangs up before the <Refer> transaction has completed:

   • ReferCallStatus: "canceled"
   • ReferSipResponseCode: "202"
   • NotifySipResponseCode: "180"

The method attribute accepts either GET or POST. This tells Twilio whether to request the action URL via HTTP GET or POST, with POST as its default value.

Because <Refer> is a SIP-specific feature, it can only be used on SIP call legs. In the typical IVR scenario, there will be only a single call leg to/from Twilio—such as an inbound call to a Twilio phone number or SIP domain, or an outbound call initiated by the Twilio REST API. In these cases, as long as the call is between Twilio and a SIP device, <Refer> can be used. Therefore, calls with Sids CAaaaa and CAbbbb are SIP call legs where the <Refer> verb is allowed.

Expand image

In a bridged call scenario, such as when using the <Dial> verb, there may be two legs with Twilio as demonstrated in the scenario below:

Expand image

In the above call flow, the call with Sid CAdddd is SIP call leg where the <Refer> verb is allowed. Invoking <Refer> on CAcccc would result in an error.

When using <Refer> to transfer a caller between independent internal systems, there may be a desire to pass contextual information about the call. For example, if you are building an IVR on Twilio that collects a customer's account number and reason for calling before transferring the call to a call center, you likely want to pass the account information captured by the IVR to the call center system. This contextual information is often passed in SIP Headers.

Twilio allows you to specify any valid SIP URI within the <Sip> noun to be used as the REFER target. The standard SIP mechanism for specifying headers in a SIP URI can be used, assuming your endpoint or device respects the headers in the target URI when following the REFER.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const refer = response.refer();
5
refer.sip('sip:alice@example.com?X-AcctNumber=123456&X-ReasonForCalling=billing-question');
6

7
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Refer>
4
        <Sip>sip:alice@example.com?X-AcctNumber=123456&amp;X-ReasonForCalling=billing-question</Sip>
5
    </Refer>
6
</Response>

Any allowable SIP header can be passed in the URI, so long as your endpoint or device supports stamping the header.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const refer = response.refer();
5
refer.sip('sip:alice@example.com?User-to-User=123456789%3Bencoding%3Dhex');
6

7
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Refer>
4
        <Sip>sip:alice@example.com?User-to-User=123456789%3Bencoding%3Dhex</Sip>
5
    </Refer>
6
</Response>

When SIP endpoints receive a REFER request, they initiate a new call to the target SIP URI specified in the request. The transfer is typically not complete until the new call is fully established. Most SIP endpoints provide feedback on the progress of the new call to the transferor through the SIP NOTIFY mechanism. If the transfer fails, the SIP endpoint will typically resume the original call with your Twilio app.

The <Refer> verb will automatically subscribe to and listen for SIP NOTIFY messages from your endpoint. The verb will wait for a final NOTIFY message indicating either call success or failure, and then continue the call by invoking the specified action URL. If the action parameter is omitted, Twilio will invoke the next verb in your TwiML document. If there are no further verbs to process, the Twilio call will be ended.

Based on the parameters passed to the action URL, you can resume handling the call accordingly if the transfer fails (e.g. ReferCallStatus is not "in-progress").

The <Refer> verb will return once one of the following circumstances occurs:

1. Twilio receives a SIP NOTIFY message indicating that the new call has received a 200 OK or error response
2. The SIP endpoint terminates or times out the NOTIFY subscription
3. The call to Twilio is hung up