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 for the configuration steps.

What the Diversion header contains#

The Diversion header is defined in RFC 5806. 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 and Diversion Inject Mode 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.

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