***

id: b8d72f79-1ddc-4a88-bc3d-379b19041372
title: sip\_refer
slug: /reference/sip-refer
description: Send a SIP REFER to a SIP call.
max-toc-depth: 3
----------------

[statuscallbacks]: #statuscallbacks

Send SIP REFER to a SIP call.

## **Properties**

<ParamField path="sip_refer" type="object" required={true} toc={true}>
  An object that accepts the following properties.
</ParamField>

<Indent>
  <ParamField path="sip_refer.to_uri" type="string" required={true} toc={true}>
    SIP URI to REFER to.
  </ParamField>

  <ParamField path="sip_refer.status_url" type="string" toc={true}>
    HTTP or HTTPS URL to deliver SIP REFER status events. Learn more about [status callbacks][statuscallbacks].
  </ParamField>

  <ParamField path="sip_refer.username" type="string" toc={true}>
    Username to use for SIP authentication.
  </ParamField>

  <ParamField path="sip_refer.password" type="string" toc={true}>
    Password to use for SIP authentication.
  </ParamField>
</Indent>

## **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:

<ParamField path="event_type" type="string" toc={true}>
  The type of event. Always `calling.call.refer` for this method.
</ParamField>

<ParamField path="event_channel" type="string" toc={true}>
  The channel for the event, includes the SWML session ID.
</ParamField>

<ParamField path="timestamp" type="number" toc={true}>
  Unix timestamp (float) when the event was generated.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  The project ID associated with the call.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  The Space ID associated with the call.
</ParamField>

<ParamField path="params" type="object" toc={true}>
  An object containing SIP REFER-specific parameters.
</ParamField>

<Indent>
  <ParamField path="params.call_id" type="string" toc={true}>
    The call ID.
  </ParamField>

  <ParamField path="params.node_id" type="string" toc={true}>
    The node handling the call.
  </ParamField>

  <ParamField path="params.sip_refer_to" type="string" toc={true}>
    The SIP URI the recipient is being referred to.
  </ParamField>

  <ParamField path="params.state" type="string" toc={true}>
    The overall result of the SIP REFER operation (e.g., `success`).
  </ParamField>

  <ParamField path="params.sip_refer_response_code" type="string" toc={true}>
    The SIP response code for the REFER request itself (e.g., `"202"`). Only present when a response has been received.
  </ParamField>

  <ParamField path="params.sip_notify_response_code" type="string" toc={true}>
    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.
  </ParamField>

  <ParamField path="params.segment_id" type="string" toc={true}>
    The segment ID for the call leg. Present when available.
  </ParamField>

  <ParamField path="params.tag" type="string" toc={true}>
    The tag associated with the call. Present when set.
  </ParamField>
</Indent>

### 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

<CodeBlocks>
  <CodeBlock title="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'
    ```
  </CodeBlock>

  <CodeBlock title="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"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>