sip_refer
sip_refer
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
An object that accepts the following properties.
sip_refer.to_uri
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
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
HTTP or HTTPS URL to deliver SIP REFER status events. Learn more about status callbacks.
sip_refer.username
Username to use for SIP authentication.
sip_refer.password
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, orerror. Set toerrorwhen the REFER could not be executed. Asuccessresult 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 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
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
The channel for the event, includes the SWML session ID.
timestamp
Unix timestamp (float) when the event was generated.
project_id
The project ID associated with the call.
space_id
The Space ID associated with the call.
params
An object containing SIP REFER-specific parameters.
params.call_id
The call ID.
params.node_id
The node handling the call.
params.sip_refer_to
The SIP URI the recipient is being referred to.
params.state
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
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
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
The segment ID for the call leg. Present when available.
params.tag
The tag associated with the call. Present when set.
Raw JSON example
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
The error code (for example, "409").
params.error.message
A description of the error.
Check event_type before reading the rest of the payload. Not every failure produces an error event.