Inbound SIP REFER to Twilio

Ensure that referUrl is present in the initial call's <Dial> Verb attribute.

The REFER details, including the ReferTransferTarget contact information, is passed on in the resulting Webhook to the referUrl. Your application can then handle the webhook however it likes, you are allowed to use any of the Programmable Voice features like <Dial>, <Say>, <Play>, <Gather>, <Enqueue>, <Sim>, etc.

Here is an example call flow.

1. UserA called a bank and connected with Bank AgentA's SIP phone.

   • It is at this step where the <Dial> verb will need to contain the referUrl attribute.

2. They finished their initial conversation and now UserA wants to connect to AgentB in another department, so AgentA sends the SIP REFER to Twilio containing AgentB's contact information in the Refer-To header.

3. Twilio handles the REFER and sends the information in a webhook to the customer's application, which establishes a call to AgentB's SIP phone using a TwiML <Dial> verb. Twilio then bridges UserA's call with the connected SIP call to AgentB.

Expand image

1
<Response>
2
  <Dial>
3
    <Sip>sip:AGENTB@YOURDOMAIN.sip.us1.twilio.com</Sip>
4
  </Dial>
5
</Response>

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

3
const response = new VoiceResponse();
4
const dial = response.dial({
5
  referUrl: "https://example.com/handler",
6
});
7
dial.sip(
8
  "sip:AgentA@xyz.sip.us1.twilio.com?User-to-User=123456789%3Bencoding%3Dhex&X-Name=Agent%2C+A"
9
);
10

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

1
<Response>
2
    <Dial referUrl="https://example.com/handler">
3
        <Sip>sip:AgentA@xyz.sip.us1.twilio.com?User-to-User=123456789%3Bencoding%3Dhex&amp;X-Name=Agent%2C+A</Sip>
4
    </Dial>
5
</Response>

The above example does not set the answerOnBridge attribute in the <Dial> verb; i.e., that attribute uses the default value of false. Therefore, right after the Webhook is fetched Twilio will immediately sends the SIP NOTIFY, and disconnects the "Transferor" call leg (AgentA in the above call flow). If the Transfer-Target (AgentB in the above call flow) does not answer the call, or if the call or Application fetch fails, UserA's call will be disconnected unless your application is written to be able to handle the failure case.

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

3
const response = new VoiceResponse();
4
const dial = response.dial({
5
    answerOnBridge: true,
6
    referUrl: 'https://example.com/handler'
7
});
8
dial.sip('sip:AgentA@xyz.sip.us1.twilio.com?User-to-User=123456789%3Bencoding%3Dhex&X-Name=Agent%2C+A');
9

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

1
<Response>
2
    <Dial answerOnBridge="true" referUrl="https://example.com/handler">
3
        <Sip>sip:AgentA@xyz.sip.us1.twilio.com?User-to-User=123456789%3Bencoding%3Dhex&amp;X-Name=Agent%2C+A</Sip>
4
    </Dial>
5
</Response>

The above example sets the answerOnBridge attribute to true in the <Dial> verb. Therefore, Twilio will not disconnect the "Transferor" call leg (AgentA in the above call flow) until after the Transfer-Target (AgentB in the above call flow) answers the call. If the Transfer-Target (AgentB in the above call flow) does not answer the call, or if the call or Application fetch fails, UserA's call will stay connected with AgentA.

In this example, we will follow the call flow explained above.

• Initial call - UserA calls AgentA. They are connected and actively in conversation.
• Refer - UserA wants to connect to another department in the bank. AgentA presses the transfer button and passes on the contact information.
• Final call - UserA is now connected to AgentB. The initial call is torn down.