Skip to navigation
Calling

sip_refer

View as MarkdownOpen in Claude

Send SIP REFER to a SIP call. The SIP REFER guide explains what the far-end device must support and when to use a bridged transfer instead.

Properties

sip_refer
objectRequired

An object that accepts the following properties.

sip_refer.to_uri
string

SIP URI to REFER to. At least one of to_uri or to is required. When both are set, to_uri takes precedence unless it is empty after variable expansion.

sip_refer.to
string

Alias for to_uri. Used as the SIP URI to REFER to when to_uri is not set or is empty after variable expansion.

sip_refer.status_url
string

HTTP or HTTPS URL to deliver SIP REFER status events. Learn more about status callbacks.

sip_refer.username
string

Username to use for SIP authentication.

sip_refer.password
string

Password to use for SIP authentication.

Variables

Set by the method:

  • sip_refer_to: (out) The SIP URI the recipient is to INVITE.
  • sip_refer_result: (out) Final SIP REFER result: success, cancel, noAnswer, busy, or error. Set to error when the REFER could not be executed. A success result doesn’t by itself confirm that the refer target answered.
  • sip_refer_response_code: (out) Recipient response to the REFER request.
  • sip_refer_to_response_code: (out) INVITE response to the recipient.

StatusCallbacks

Status callbacks are advisory

Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.

A POST request will be sent to status_url with a JSON payload like the following, for a calling.call.refer event:

event_type
string

The type of event. calling.call.refer for the SIP REFER status events described here. When the REFER can’t be executed, an error event with event type calling.error may be sent instead; see error events.

event_channel
string

The channel for the event, includes the SWML session ID.

timestamp
number

Unix timestamp (float) when the event was generated.

project_id
string

The project ID associated with the call.

space_id
string

The Space ID associated with the call.

params
object

An object containing SIP REFER-specific parameters.

params.call_id
string

The call ID.

params.node_id
string

The node handling the call.

params.sip_refer_to
string

The SIP URI the recipient is being referred to.

params.state
string

The state of the SIP REFER operation. When the recipient accepts the REFER request, an intermediate event with state inProgress may be sent. The final event carries one of success, cancel, noAnswer, busy, or error. A success state doesn’t by itself confirm that the refer target answered.

params.sip_refer_response_code
string

The SIP response code for the REFER request itself (e.g., "202"). Only present when a response has been received.

params.sip_notify_response_code
string

The SIP response code for the INVITE sent by the recipient to the refer target (e.g., "200"). Only present when a response has been received.

params.segment_id
string

The segment ID for the call leg. Present when available.

params.tag
string

The tag associated with the call. Present when set.

Raw JSON example

{
"event_type": "calling.call.refer",
"event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timestamp": 1640000000.123,
"project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"params": {
"call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"sip_refer_to": "sip:alice@example.com",
"state": "success",
"sip_refer_response_code": "202",
"sip_notify_response_code": "200"
}
}

Error events

When the REFER can’t be executed, for example because the call isn’t a SIP call, SignalWire may send an event with event_type set to calling.error to status_url instead of a calling.call.refer event. Its params object doesn’t contain the SIP REFER fields above. It carries the call identifiers and an error object:

params.error.code
string

The error code (for example, "409").

params.error.message
string

A description of the error.

Check event_type before reading the rest of the payload. Not every failure produces an error event.


Examples

Send SIP REFER and post result

version: 1.0.0
sections:
main:
- sip_refer:
to_uri: 'sip:alice@example.com'
- play:
url: 'say: Connected. The SIP refer result is ${sip_refer_result}'
- execute:
dest: 'https://example.com/handle_sip_refer_result'