> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# sip_refer

> Send a SIP REFER to a SIP call.

[statuscallbacks]: #statuscallbacks

Send SIP REFER to a SIP call.

## **Properties**

**`sip_refer`** `object` — required

An object that accepts the following properties.

---

**`sip_refer.to_uri`** `string` — required

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][statuscallbacks].

---

**`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**

> **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](/docs/platform/webhooks#status-callback-reliability).

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

```json
{
  "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

#### YAML

```yaml
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'
```

#### JSON

```json
{
  "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"
        }
      }
    ]
  }
}
```

> Send a SIP REFER to a SIP call.