# Diversion header for inbound calls

The SIP `Diversion` header tells the receiving system that a call was
diverted on its way to the destination, for example because it was forwarded.
It carries the number the call was originally diverted from and, optionally,
the reason for the diversion. On inbound SIP trunks, DIDWW can relay the
Diversion information it receives with a call, add its own Diversion header
that contains the called DID number, or both. See [Configure Diversion
headers](../how-to-guides/manage-sip-trunks.html#inbound-sip-trunks-configure-diversion) for the configuration steps.

## What the Diversion header contains

The `Diversion` header is defined in [RFC 5806](https://www.rfc-editor.org/rfc/rfc5806). Each header identifies one
diversion of the call and can contain:

- The number or SIP address from which the call was diverted, often called the
  original called number.
- Optional parameters, such as `reason`, that describe why the call was
  diverted. Common values include `unconditional`, `user-busy`, and
  `no-answer`.

A call that was diverted more than once can carry several Diversion headers.
The most recent diversion is listed first.

Diversion information is typically present when a call to another number is
forwarded to your DIDWW DID number. For example, a business forwards calls
from its existing landline or mobile number to a DIDWW number. In this case,
the Diversion header shows the forwarded number, while the called DID is the
DIDWW number.

## Relay and inject behavior

The two settings control different Diversion information and can be used
separately or together.

|  | Diversion Relay Policy | Diversion Inject Mode |
| --- | --- | --- |
| Source | Diversion information that DIDWW receives with the call from the upstream network. | Generated by DIDWW for each call. |
| Number in the header | The number the call was diverted from before it reached DIDWW. | The DIDWW DID number that received the call, in E.164 format with a leading `+`. |
| Available values | - **Disabled** - **Diversion header in SIP URI format** - **Diversion header in TEL URI format** | - **Disabled** - **Add Diversion header with DID number** |
| Typical use | Show which number the caller originally dialed when the call was forwarded to your DID. | Identify which DIDWW number was called when the destination SIP address does not contain the DID, or keep the DID available for forwarding the call onward. |

For the setting definitions, see [Diversion Relay Policy
values](../sip-trunk-settings-reference.html#inbound-sip-diversion-relay-values) and [Diversion Inject Mode
values](../sip-trunk-settings-reference.html#inbound-sip-diversion-inject-values).

### Relay Diversion information

**Diversion Relay Policy** controls whether DIDWW delivers the Diversion
information it receives with a call from the PSTN or an upstream carrier.
When the policy is enabled, DIDWW relays all received Diversion headers in the
selected URI format:

| Value | Example of a delivered header |
| --- | --- |
| Diversion header in SIP URI format | `Diversion: <sip:+12025550100@sip.didww.com>` |
| Diversion header in TEL URI format | `Diversion: <tel:+12025550100>` |

With **Disabled**, DIDWW does not relay received Diversion headers.

DIDWW can relay only the Diversion information it receives. If the upstream
network does not send Diversion information for a call, there is nothing to
relay, and no relayed Diversion header is delivered.

### Add a Diversion header with the DID number

**Diversion Inject Mode** controls whether DIDWW adds its own Diversion header
that contains the DID number that received the call. The number is in E.164
format with a leading `+`. For example:

```
Diversion: <sip:+12135550150@sip.didww.com>;reason=unconditional
```

The added header is useful when your receiving system needs to know which
DIDWW number was called, but the trunk destination does not contain the DID.
This is common for platforms that receive calls on a fixed SIP address, such
as some AI voice platforms. It also keeps the DID available if your system
[forwards the call through a DIDWW outbound trunk](../../../outbound-trunks/routing-dialing/call-forwarding.html).

### When both settings are enabled

When both settings are enabled and the call arrives with Diversion
information, the delivered SIP `INVITE` contains more than one Diversion
header. DIDWW adds its own header with the DID number at the top of the list,
followed by the relayed headers.

Warning

Some PBXs and session border controllers (SBCs) read only the first
Diversion header, and some may not accept several Diversion headers. Before
you enable both settings, confirm how your receiving system handles
multiple Diversion headers, and test with a forwarded call.

## Call flow example

In this example, a business forwards calls from its main number
`+12025550100` to the DIDWW DID number `+12135550150`. The SIP trunk
assigned to the DID has **Diversion Relay Policy** set to **Diversion header
in TEL URI format** and **Diversion Inject Mode** set to **Add Diversion header
with DID number**.

```
        sequenceDiagram
    autonumber
    participant C as Caller
    participant N as Carrier of +12025550100
    participant D as DIDWW
    participant P as Your PBX or SBC

    C->>N: Call to +12025550100
    N->>D: Call forwarded to DID +12135550150 with Diversion for +12025550100
    D->>P: INVITE with Diversion for the DID and the relayed Diversion
```

The SIP `INVITE` delivered to your PBX contains the following Diversion
headers:

```
Diversion: <sip:+12135550150@sip.didww.com>;reason=unconditional
Diversion: <tel:+12025550100>
```

1. The first header is added by DIDWW and contains the called DID number.
2. The second header is relayed from the forwarding carrier and contains the
   number the caller originally dialed.

With only **Diversion Relay Policy** enabled, the `INVITE` contains only the
second header. With only **Diversion Inject Mode** enabled, it contains only
the first header.

## Limitations and expected behavior

- Diversion information from the upstream network is not available for every
  call. It depends on whether the call was diverted and on whether the
  originating and transit carriers send Diversion information.
- The relayed number is provided by the upstream network. DIDWW does not add a
  relayed header when none was received.
- The Diversion settings apply per inbound SIP trunk. Configure them on each
  trunk that delivers calls to a system that uses Diversion information.
- Diversion headers are separate from [inbound call redirection](../call-handling-and-delivery/inbound-call-redirection.html). Redirection
  describes how your SIP platform sends a call from DIDWW to another
  destination. Diversion headers describe how a call was diverted before
  DIDWW delivered it to you.

## Related resources

- [Configure Diversion headers](../how-to-guides/manage-sip-trunks.html#inbound-sip-trunks-configure-diversion)
  - Edit a SIP trunk and select the Diversion settings.
- [Additional Services settings](../sip-trunk-settings-reference.html#inbound-sip-trunks-settings-additional-services) - Review the Diversion
  Relay Policy and Diversion Inject Mode values.
- [Call forwarding](../../../outbound-trunks/routing-dialing/call-forwarding.html)
  - Forward inbound calls through a DIDWW outbound trunk using the Diversion
  header.
- [STIR/SHAKEN for inbound calls](stir-shaken-headers.html) - Understand the
  other caller information that DIDWW can add to inbound SIP calls.
