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 includeunconditional,user-busy, andno-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 |
|
|
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 header in TEL URI format |
|
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>
The first header is added by DIDWW and contains the called DID number.
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.