Refer

Refer

During a programmable SIP call, the RCML <Refer> verb instructs Restcomm to initiate a SIP Refer (i.e transfers) towards a SIP infrastructure and handles any NOTIFY messages.

The <Refer> feature can also be invoked via REST API.

Refer Attributes

Name Allowed Values Default Value

action

relative or absolute URL

none

method

GET, POST

POST

Action Attribute

The 'action' attribute takes a URL as an argument. When the refer call ends, Restcomm will make a GET or POST request to this URL including the parameters below.

If you provide an 'action' URL, Restcomm will continue the current call after the refer finished, using the RCML received in your response to the 'action' URL request.

Any RCML verbs occuring after a <Refer> which specifies an 'action' attribute are unreachable.

If no 'action' is provided, <Refer> will finish and Restcomm will move on to the next RCML verb in the document.

If there is no next verb, Restcomm will end the phone call.

Method Attribute

The 'method' attribute takes the value 'GET' or 'POST'.

This tells Restcomm whether to request the URL via HTTP GET or POST.

Refer Action Request HTTP Parameters

The Restcomm parameters passed to your application in its asynchronous request to the Refer action URL. The list of basic parameters can be found in the RCML Voice Request documentation.

The <Refer> request also passes these additional parameters:

Parameter Description

ReferCallStatus

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 Restcomm 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.

Nesting

You may nest the following nouns within <Refer>: SIP

As specified by SIP spec, the sip URL may contain header parameters. These headers will be used by Transferee to compose the INVITE message.

If reserved headers (Call-ID, Route…​) are attempted to be used, the Refer verb will fail with ReferSipResponseCode 400.

Examples

For examples of how to use the <Refer> verb see below.

Refer to a phone number.

<Response>
    <Refer>
        <Sip>sip:phone_number@domain.com</Sip>
    </Refer>
</Response>

Refer to a phone number with request follow actions.

<Response>
    <Refer action="/handleRefer" method="GET">
        <Sip>sip:phone_number@domain.com</Sip>
    </Refer>
</Response>

Refer two active calls during parallel Dial.

<Response>
    <Refer>
        <Sip>sip:phone_number@domain.com?</Sip>
    </Refer>
</Response>

Refer to with custom headers.

<Response>
    <Refer>
        <Sip>sip:phone_number@domain.com?myCustomHeader=value</Sip>
    </Refer>
</Response>

Refer Call Flows

The following flow diagrams illustrate the possible call flow scenarios for the RCML <Refer> verb.

Successful Unattended Transfer

The diagram below outlines dialing to a Restcomm IVR. After the subscriber press a digit, call transferred to the destination subscriber.

Successful Unattended Transfer Call Flow

Successful Attended Transfer

The diagram below outlines dialing to a Restcomm IVR. The RCML application will instruct a Dial with call screening feature to query the target destination whether to accept transfer or not.

Via LCM request, the refer/transfer operation will be invoked in the inbound leg.

Successful Attended Transfer Call Flow