Refer

The Refer verb is used to send a SIP REFER for an inbound SIP URI call.

Text Content

There is no text content available to be set for the <Refer> verb.

Attributes

Attribute	Description
referCompleteUrl	(optional) URL to send the [Refer Complete] event to. On a successful REFER, the call is terminated and any BXML returned from this webhook is ignored - the event is informational only. On a failed REFER, the BXML returned from this webhook is executed on the still-active call, allowing your application to recover. Verbs following the <Refer> verb are ignored. May be a relative URL.
referCompleteMethod	(optional) The HTTP method to use for the request to referCompleteUrl. GET or POST. Default value is POST.
tag	(optional) A custom string that will be sent with this and all future callbacks unless overwritten by a future tag attribute or cleared. May be cleared by setting tag="" Max length 256 characters.

note

If referCompleteUrl is not specified, no event will be sent. On success the call is still terminated; on failure, execution continues with the verbs following <Refer> (or the implicit <Hangup> if there are none).

Nested Tags

Exactly one <SipUri> tag must be nested within <Refer> to define the refer destination.

Tag	Description
SipUri	A SIP URI specifying the refer destination (e.g. sip:alice@atlanta.example.com).

SipUri

Text Content

Name	Description
SIP URI	String containing the SIP URI to place in the Refer-To header field.

Attributes

The <SipUri> tag has no attributes.

Constraints

• <Refer> is only supported on inbound SIP URI calls.
• After a successful REFER, the call is terminated and your application loses access to it. The caller's endpoint will be talking directly to the refer destination.
• If the caller's endpoint does not send a final NOTIFY within 30 seconds after accepting the REFER, the operation is considered failed due to timeout.

Webhooks Received

Webhooks	Can reply with more BXML
Refer Complete	Yes (only executed on failure; ignored on success)

The Refer Complete callback is sent when the REFER flow completes (either successfully or with failure). On failure, the BXML returned from the callback is executed on the still-active call, allowing your application to recover (e.g. play an error message, retry, or hang up).

Error Scenarios

The referComplete callback reports the outcome via referCallStatus:

Scenario	referCallStatus	referSipResponseCode	notifySipResponseCode	Notes
REFER rejected by caller's endpoint	failure	Error code (e.g. 405)	Not present	The caller's endpoint rejected the REFER method. Call remains active; no billing occurs.
Destination unreachable	failure	202	Error code (e.g. 404)	The caller's endpoint accepted the REFER but could not reach the destination. Billing occurs on the 202. Call remains active.
NOTIFY timeout (30s)	failure	202	Not present	The caller's endpoint accepted the REFER but never sent a final NOTIFY. Billing occurs on the 202. Call remains active.
Successful REFER	success	202	200	The caller's endpoint successfully connected to the refer destination. Billing occurs. Call is torn down.

Examples

Send REFER to a SIP URI

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Refer referCompleteUrl="https://example.com/handleRefer" referCompleteMethod="POST">
        <SipUri>sip:alice@atlanta.example.com</SipUri>
    </Refer>
</Response>

Handle Failure in referComplete Callback

When a REFER fails, your referCompleteUrl receives the Refer Complete event and you can return BXML to continue the call:

HTTP/1.1 200
Content-Type: application/xml; charset=utf-8

<Response>
    <SpeakSentence>The transfer could not be completed. Please try again later.</SpeakSentence>
    <Hangup />
</Response>