> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom SIP

> Access SIP headers for dynamic routing, personalization, and custom handoffs.

Access SIP headers and attributes to extract caller metadata, route calls dynamically, and implement custom SIP-based handoffs.

## Key attributes

The `conv` object provides access to SIP-related attributes that you can use in your agent logic:

#### **sip\_headers**

* **Description**: A dictionary containing SIP headers and their corresponding values.
* **Use case**: Extract caller-specific metadata or route calls dynamically.
* **Example**:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
caller_id = conv.sip_headers.get("From", "Unknown Caller")
print(f"Caller ID: {caller_id}")
```

#### **caller\_number**

* **Description**: The phone number of the caller.
* **Use case**: Personalize responses based on the caller's number.
* **Example**:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
if conv.caller_number == "+15551234567":
    conv.goto_flow("vip_support_flow")
else:
    conv.goto_flow("general_support_flow")
```

#### **callee\_number**

* **Description**: The phone number the caller dialed.
* **Use case**: Determine routing based on the number dialed.
* **Example**:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
dialed_number = conv.callee_number
if dialed_number == "+15557654321":
    conv.state.branch = "North Branch"
else:
    conv.state.branch = "South Branch"
```

### How to Use Custom SIP

1. **Access SIP headers**:
   * Use `conv.sip_headers` to retrieve metadata from the SIP protocol.
   * This is particularly useful for identifying caller attributes or custom routing.

2. **Dynamic routing**:
   * Use `caller_number` and `callee_number` to configure routing flows based on incoming and dialed numbers.

3. **Store data for contextual responses**:
   * Save SIP-related information into `conv.state` to persist data across the conversation.
   * Example:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
conv.state.metadata = {
    "caller_id": conv.sip_headers.get("From", "Unknown"),
    "dialed_number": conv.callee_number,
}
```

### Use cases

* **VIP routing**: Automatically direct high-priority callers to specific support flows.
* **Branch-specific handling**: Route calls to the appropriate branch or location based on the number dialed.
* **Dynamic personalization**: Use SIP headers to provide tailored greetings or responses.

For more details on the `Conversation` object, visit the **[`conv` object](/tools/classes/conv-object)** page.

## Initiating SIP transfers programmatically

In addition to configuring call handoffs in the UI, you can initiate SIP transfers directly from a function using `return` values. This is useful when routing logic depends on in-conversation data or SIP header values.

You can use two methods: **INVITE** and **REFER**. These are mutually exclusive with UI-based `Call Handoffs` and require manual setup.

### When to use INVITE vs REFER

**Use SIP INVITE when:**

* You want PolyAI to remain in the call as a bridge between the caller and the target
* You need to monitor or record the transferred call
* You want to inject custom SIP headers for the outbound leg
* You're transferring to a PSTN number or external SIP URI

**Use SIP REFER when:**

* You want the Session Border Controller (SBC) to handle the transfer directly
* You want to remove PolyAI from the call path after transfer (reduces latency and infrastructure load)
* Your SBC supports REFER and has "Take Back and Transfer" enabled
* You're performing an attended or blind transfer in the same SIP domain

### SIP INVITE

This creates a new call and bridges the user with the target. Use this when you want PolyAI to act as a bridge.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
return {
  "handoff": {
    "invite": {
      "phone_number": "2222222",  // SIP URI or PSTN number
      "outbound_caller_id": conv.caller_number,
      "outbound_endpoint": "YOUR_OUTBOUND_ENDPOINT_NAME",  // Provided by PolyAI during setup
      "sip_headers": {
        "X-Customer-ID": conv.state.customer_id,
        "X-Call-Type": "Support"
      }
    }
  }
}
```

<Info>
  The `outbound_endpoint` value is provided by PolyAI during your SIP integration setup. Contact your PolyAI account manager or representative if you need this value.
</Info>

### SIP REFER

This instructs the Session Border Controller to take over and transfer the call.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
return {
  "handoff": {
    "refer": {
      "phone_number": conv.caller_number,  // Number PolyAI used
      "refer_to": "sip:support@example.com",  // SIP URI or number
      "sip_headers": {
        "X-Caller-ID": conv.caller_number
      }
    }
  }
}
```

<Note>
  To avoid 405 errors, make sure the "Take Back and Transfer" setting is enabled when using SIP REFER on any platform with that setting.
</Note>

These code patterns are especially useful when dynamic call routing or SIP metadata injection is needed mid-conversation.