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

# Set & parse custom SIP headers

> Use custom SIP headers in Retell AI to pass metadata on inbound calls, outbound calls, transfers, and agent hangups, with dynamic values from the conversation.

Use custom SIP headers to pass metadata between your systems and Retell on a call — for example, forwarding an account ID or a caller reference from your [custom telephony](/deploy/custom-telephony) platform so the agent can use it during the conversation.

<Note>SIP headers are available for phone calls only. Retell receives SIP headers on inbound calls, and sets them on outbound calls, transfers, and agent hangups.</Note>

Many SIP parsers and middleboxes assume 1024 bytes is a reasonable maximum for a header line, and may reject or truncate longer headers unless configured to allow more.

## Parse custom SIP headers for inbound calls

For inbound calls, custom SIP headers (those starting with `X-` or `x-`) are received and extracted automatically into `call.custom_sip_headers`. They are also added to your [dynamic variables](/build/dynamic-variables), where you access them by stripping the `X-` or `x-` prefix. No configuration is needed.

For example, if this is the SIP header received for an inbound call:

```json theme={"dark"}
{
  "X-test-header": "something",
  "X-another-header": "something else",
  "from": "1234567890",
  "to": "0987654321"
}
```

Then here's your `call.custom_sip_headers` field, and they will be added to your dynamic variables.

```json theme={"dark"}
{
  "test-header": "something",
  "another-header": "something else"
}
```

If you have already specified dynamic variables with the same name for this inbound call, it will override the value received from the SIP header.

## Set custom SIP headers for outbound calls

<img src="https://mintcdn.com/retellai/rxvYffEkEJPRL1KD/images/deploy/phone-call/outbound-call.png?fit=max&auto=format&n=rxvYffEkEJPRL1KD&q=85&s=a19d395e5d5d2005d6f3937c6aa35055" alt="Outbound call dialog with a custom SIP header key and value being added." width="1032" height="1378" data-path="images/deploy/phone-call/outbound-call.png" />

For outbound calls, you can add custom SIP headers as needed. Each must start with `X-`.

## Set custom SIP headers for call transfers

For call transfers, header names must start with `X-` or `x-`, or be `User-to-User` or `Diversion` (case-insensitive). You can use a dynamic variable for the header value to pass information extracted from the call to the receiving party.

<Warning>For cold transfer with transferee number, it will use SIP REFER to transfer the call. Different telephony providers may or may NOT honor the custom SIP headers in the REFER request. Twilio, for example, does not honor the custom SIP headers in the REFER request, so the SIP headers you set in the transfer call tool will not work for cold transfer with transferee number when using Twilio.</Warning>

If you are using:

* Conversation flow agents, check out [call transfer node](/build/conversation-flow/call-transfer-node#configure-transfer) for more details.
* Single / multi agent, check out [call transfer function](/build/single-multi-prompt/transfer-call) for more details.

## Set custom SIP headers when ending a call

Use end-call headers to pass a call outcome or reference ID to your SIP system when the agent hangs up through an [End Call tool](/build/single-multi-prompt/end-call) or [end node](/build/conversation-flow/end-node). These headers are optional; none are configured by default.

For example, after booking an appointment, send `X-Call-Outcome` with the value `booked` and `X-Appointment-ID` with the value `{{appointment_id}}`. Set the `appointment_id` [dynamic variable](/build/dynamic-variables) during the conversation before ending the call. Retell resolves the value when the tool or node executes.

<Steps>
  <Step title="Open the end-call settings">
    For a single- or multi-prompt agent, add or edit the **End Call** tool. In a conversation flow, select an end node and open its settings. You can also configure headers on an End Call tool attached to a [subagent node](/build/conversation-flow/subagent-node).
  </Step>

  <Step title="Add header names and values">
    Under **Custom SIP Headers**, click **Add** for each key/value pair. Use a literal header name beginning with `X-` or `x-`, and a static string or dynamic variable for its value.
  </Step>

  <Step title="Save the headers">
    Save the End Call tool. End-node headers save when you leave the edited field. To stop sending a header, remove its row; remove all rows to clear the configuration.
  </Step>
</Steps>

<Frame caption="Use a dynamic variable to send the ticket ID when the agent ends the call.">
  <img src="https://mintcdn.com/retellai/xnGtpZfvieBKNmwD/images/end-call-sip-headers.png?fit=max&auto=format&n=xnGtpZfvieBKNmwD&q=85&s=999cc5b92ffb208e9c65b70e01573504" alt="End Call dialog with Custom SIP Headers outlined in blue, showing the X-Ticket-ID header with the ticket_id dynamic variable as its value." style={{ maxHeight: 560 }} width="710" height="660" data-path="images/end-call-sip-headers.png" />
</Frame>

### Which header names are allowed?

End-call header names must start with `X-` or `x-`. Unlike transfer headers, `User-to-User` and `Diversion` are not allowed. Standard headers such as `Reason` are also rejected.

The dashboard blocks saving a row with a value but no name, an unsupported name, or a duplicate name. Names are compared without case, so `X-Ticket` and `x-ticket` count as duplicates. Correct the name or remove the duplicate row, then save again.

These settings apply when the configured tool or node ends a phone call. They do not apply to chat or to a caller hanging up first.