Send SIP REFER to a SIP call.

Properties

sip_refer

objectRequired

An object that accepts the following properties.

sip_refer.to_uri

stringRequired

SIP URI to REFER to.

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) Overall SIP REFER result.
• return_value: (out) Same value as sip_refer_result.
• sip_refer_response_code: (out) Recipient response to the REFER request.
• sip_refer_to_response_code: (out) INVITE response to the recipient.

StatusCallbacks

A POST request will be sent to status_url with a JSON payload like the following:

event_type

string

The type of event. Always calling.call.refer for this method.

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 overall result of the SIP REFER operation (e.g., success).

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"
  }
}

---

Examples

Send SIP REFER and post result

YAMLJSON

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'