SIP Diversion Header
From VoIP.ms Wiki
In SIP, the Diversion header is used to indicate that a call was redirected from its original destination to another destination.
For example:
Alice (5551000)
|
| calls
v
Bob (5552000)
|
| call forwarding
v
Carol (5553000)
The SIP INVITE arriving at Carol might contain:
From: <sip:[email protected]> To: <sip:[email protected]> Diversion: <sip:[email protected]>;reason=unconditional
These fields tell Carol's system three different things:
| Header | Meaning |
|---|---|
| From | Who originated the call: 5551000 |
| To / Request-URI | Current destination: 5553000 |
| Diversion | The call was previously destined for: 5552000 |
Why it exists
The Diversion header is especially important in call forwarding scenarios.
Suppose customer 5552000 configures:
Forward all calls → 5553000
When someone calls 5552000, the PBX/carrier sends the call toward 5553000 while preserving information that the call originally went through 5552000.
You might see:
INVITE sip:[email protected] SIP/2.0 From: <sip:[email protected]> To: <sip:[email protected]> Diversion: <sip:[email protected]>;reason=unconditional
The carrier can therefore determine:
Caller = 5551000 Forwarding/diverting number = 5552000 Final destination = 5553000
The reason parameter
A Diversion header can also explain why the call was redirected:
Diversion: <sip:[email protected]>;reason=unconditional
Other values you may encounter include:
reason=unconditional reason=user-busy reason=no-answer reason=deflection reason=unavailable
So, for example:
Diversion: <sip:[email protected]>;reason=no-answer
Means roughly:
"This call was previously intended for 5552000, but it was redirected because 5552000 did not answer."
VoIP.ms Behavior
At VoIP.ms, when you forward a call from your PBX system, if the CallerID is not verified but a Diversion header is present, then we let pass the call taking the Diversion header added by your PBX and forwarding it to the intended destination.
It is importat you correctly set the Diversion header on your PBX "Call Forwarding" settings.
On modern systems like 3CX V20 the header is automatically added on forwarded call scenarios, however, this is something you may review with your PBX provider.
