TwiML™ Voice: <Refer>

During a programmable SIP call, the TwiML <Refer> verb instructs Twilio to initiate a SIP Refer (i.e transfers) towards a SIP infrastructure and handles any NOTIFY messages. You can invoke the verb using REST API as well.

The <Refer> verb can be invoked on both inbound and outbound SIP calls. For example, on an inbound SIP call to a Twilio SIP Domain, you may want to transfer the caller to back to your in-house or legacy SIP infrastructure. By initiating the <Refer> verb, Twilio instructs your SIP device to initiate a new call to the external system and replace the Twilio leg with that new call.

You can initiate a <Refer> at any point in the duration of a call. For example, with an outbound SIP call created by the <Sip> noun or the Twilio REST API to a SIP Domain, can be used at any point to transfer the caller back to your in-house or legacy SIP infrastructure. By initiating the <Refer> verb, Twilio instructs your SIP device to initiate a new call to the external system and replace the Twilio leg with that new call.

(warning)

Warning

<Refer> is only supported on SIP call legs because the REFER method is a SIP-specific feature. Non-SIP leg types, such as PSTN and Twilio Voice SDK calls are not supported and will result in an error. For more information on what constitutes a SIP call leg, see Understanding Call Legs below.

The example below shows <Refer> established in an inbound call leg:

PV SIP Call Transfer - SIP REFER Example.

Node.js

Python

Java

PHP

Ruby


_10const VoiceResponse = require('twilio').twiml.VoiceResponse;
_10
_10const response = new VoiceResponse();
_10const refer = response.refer();
_10refer.sip('sip:alice@example.com');
_10
_10console.log(response.toString());

Output


_10<?xml version="1.0" encoding="UTF-8"?>
_10<Response>
_10    <Refer>
_10        <Sip>sip:alice@example.com</Sip>
_10    </Refer>
_10</Response>

<Refer> Attributes

Attribute Name	Allowed Values	Default Value
action	Relative or absolute URL	None
method	`GET`, `POST`	`POST`

action

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.

Refer with action URL

Node.js

Python

Java

PHP

Ruby


_10const VoiceResponse = require('twilio').twiml.VoiceResponse;
_10
_10const response = new VoiceResponse();
_10const refer = response.refer({
_10    action: '/handleRefer',
_10    method: 'POST'
_10});
_10refer.sip('sip:alice@example.com');
_10
_10console.log(response.toString());

Output


_10<?xml version="1.0" encoding="UTF-8"?>
_10<Response>
_10    <Refer action="/handleRefer" method="POST">
_10        <Sip>sip:alice@example.com</Sip>
_10    </Refer>
_10</Response>

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

Parameter	Description
`ReferCallStatus`	Similar to the CallStatus parameter, this provides the application with our understanding (based on SIP NOTIFY messages) of the status of the new call created in response to the REFER. If the REFER fails or the endpoint does not send any NOTIFY requests, this parameter will be omitted.
`ReferSipResponseCode`	The SIP response code received in response to the REFER request Twilio sends to the SIP endpoint.
`NotifySipResponseCode`	This is the last SIP response code received on the referred leg, as determined by examining the SIP NOTIFY messages. E.g. If the SIP endpoint initiated a new call but received a SIP 404 response due to the target not being found, this parameter would be set to "404". If the REFER fails or the endpoint does not send any NOTIFY requests, this parameter will be omitted.

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:

Twilio issues a REFER, and the SIP endpoint successfully initiates a new call to the transfer target:
- ReferCallStatus: "in-progress"
- ReferSipResponseCode: "202"
- NotifySipResponseCode: "200"
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"
Twilio issue a REFER, but the SIP endpoint responds to the REFER with an error:
- ReferCallStatus: "failed"
- ReferSipResponseCode: "405"
The caller hangs up before the <Refer> transaction has completed:
- ReferCallStatus: "canceled"
- ReferSipResponseCode: "202"
- NotifySipResponseCode: "180"

method

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.

Understanding Call Legs

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.