Voice

Refer

View as Markdown

The <Refer> verb transfers a SIP call in SignalWire to a transfer target using the SIP REFER method. This verb returns upon completion of transfer, on failure of transfer, on hangup, or on time out while waiting for NOTIFY. SignalWire will not hang up after <Refer> until all verbs have been processed.

Verb attributes

action
string

The action attribute takes an absolute or relative URL. On completion of the transfer, a request to this URL is made. If action is not provided, SignalWire will continue reading the next verb in the document. See below for specified request parameters.

method
stringDefaults to POST

Specifies whether the action is a GET or a POST.

Request parameters for the action URL

The action request contains the Standard Request Parameters as well as:

NotifySipResponseCode
string

The last response code reported by the SIP NOTIFY events. This is the code sent by the transfer target in response to the SIP INVITE method. This parameter will not reported if no SIP NOTIFY events are received.

ReferCallStatus
string

The result of the transfer based on the reply to the SIP REFER method and the SIP NOTIFY events received afterwards. This parameter will not be reported if no SIP NOTIFY events are received. See below for all possible values.

ReferSipResponseCode
string

The code received in response to the SIP REFER method. 202 when accepted.

Values for the ReferCallStatus parameter

The parameter ReferCallStatus has the following values:

ValueDescription
in-progressSIP REFER accepted and SignalWire received 200 via SIP NOTIFY.
busySIP REFER accepted and SignalWire received 486 or 600 via SIP NOTIFY.
no-answerSIP REFER accepted and SignalWire received 487 via SIP NOTIFY.
canceledSIP REFER accepted, however the call ended before the transfer completed.
failedAn error occurred through the <Refer> verb, an error received in response to SIP REFER, or a 4xx/5xx/6xx error was received via SIP NOTIFY.

Nouns

The noun of a cXML verb is nested within the verb upon which the verb acts. <Refer> has the following nouns:

NounDescription
<Sip>The SIP URI to which to transfer this call.

Nesting

No other verbs can be nested within <Refer> and you cannot nest <Refer> within any other verbs.

Examples

Transfer to SIP URI

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Refer action="https://example.com/refer-completed.xml" method="GET"><Sip>sip:transfer-target@example.com</Sip></Refer>
4</Response>