An Introduction to the SIP Diversion Header

We all want to think that we are unique in some way and I expect that most people can find a few things about themselves that are different from the people around them. Sometimes those differences can be life defining. Take a look at most great basketball players and tell me that their height wasn’t a major factor in being able to play at the professional level. The same can be said for an NFL tackle where the average weight is above 300 pounds. You can be a tough-as-nails 180-pound badass, but you won’t get a shot at the big leagues unless you put on some pounds.

So, what makes me unique? At just shy of 6’ 2” I am too short for basketball and no one in their right mind would ever put me on a football field as anything other than a tackling dummy.

Sadly, I’m not even unique in the field of communications. There are others that know more about this stuff than I will ever dream to know.

However, there is something that makes me different from just about everyone else on this planet.

I was born in Arizona and spent my childhood and young adult years living in the Phoenix valley (Scottsdale, Mesa, and Tempe).  That in itself isn’t unique, but the fact that I now live in Minnesota makes me quite the rarity. Let’s face it, there are lots of Minnesotans in Arizona, but you will be hard pressed to find the opposite.  I never have.

Simply put, my uniqueness is based on diversion. I started out life in Arizona, was happy as a clam living there, met a Minnesota girl who became my wife, and found myself diverted to Minnesota.

Which leads me to today’s topic of discussion. The SIP Diversion header.

Okay, that’s a stretch, but cut me some slack. It’s hard coming up with new blog subjects and making them sound personal.

The SIP Diversion Header

RFC 5806 defines SIP diversion as follows:

  • A change to the ultimate destination endpoint of a request. A change in the Request-URI of a request that was not caused by a routing decision. This is also sometimes called a deflection or redirection.
  • A diversion can occur when the “user” portion of the Request-URI is changed for a reason other than expansion or translation.
  • A diversion can occur when only the “host” portion of the Request-URI has changed if the change was due to a non-routing decision.

This usually boils down to the scenario where A calls B and A is redirected (not transferred) to C.

Imagine Sarah setting call forward on her SIP telephone to send all incoming calls to Debbie. Now, when Andrew calls Sarah, his call will be automatically sent to Debbie. Debbie’s SIP telephone will know that the call was diverted by the presence of a Diversion header in the INVITE request she receives from Andrew.

Who inserted the Diversion header? It won’t be Andrew since he is unaware of the state of Sarah’s telephone. It won’t be Sarah since her telephone never saw Andrew’s call. It certainly can’t be Debbie since it’s her telephone that is ringing. This means that it must be something between Andrew and Debbie.

That something will be some form of a Back-to-Back User Agent (B2BUA) and in most cases it will be a SIP proxy that is aware of the forward conditions of the endpoints it serves. The Diversion header will be added by the proxy when it sees Andrew’s INVITE to Sarah. That altered INVITE will then be proxied to Debbie.

You can read all about  B2BUAs in my article, The Back to Back User Agent (B2BUA).

In my example, I stated that Sarah’s telephone was forwarded to Debbie. Of course, there are a number of different call forward conditions. In the SIP world, these are designated as diversion-reasons with the following permissible values:

  • unknown
  • user-busy
  • no-answer
  • unavailable
  • unconditional
  • time-of-day
  • do-not-disturb
  • deflection
  • follow-me
  • out-of-service
  • away

Additionally, a Diversion header supports three other parameters:

  • counter: This contains the total number of diversions that have occurred.
  • screened: This indicates if the diversion number is user provided (“no”) or network provided (“yes”).
  • privacy: Certain conditions require that the diversion information be encrypted.  This parameter shows how privacy has been applied.

The following is an example of a fully populated Diversion header:

Diversion: <sip:2000@>;privacy=off;reason=no-answer;counter=1;screen=no

Anyone receiving an INVITE with this header knows that 2000 was the originally called number, no privacy was applied, the call was forwarded due to a no answer condition, this is the only diversion, and the diversion number was user provided.

A single INVITE may contain multiple Diversion headers. Those headers are ordered such that the last or most recent diversion is at the top of the list and all subsequent diversions are below it.

Making SIP Trunks Happy

In the past, I have encountered situations that required a Diversion header that had nothing to do with call forwarding. The most common is when you need to call out through a carrier SIP trunk and the From header in the INVITE contains a number not provisioned by the carrier. The carrier would look at the From value, not recognize it, and subsequently reject the call. In some cases, a Diversion header can be used to provide the carrier with a number that it does recognize.

The reasons why the carrier might reject the call are varied, but the most common one I’ve encountered is that carriers need to see a number in its pool of DIDs to properly handle 9-1-1 calls. The value in the Diversion header can be used to satisfy that requirement.

Mischief Managed

This article was meant to be an introduction to the Diversion header and I hope that I accomplished that. You are more than welcome to dig through the SIP RFCs for a deeper explanation, but for most of you that won’t be necessary.

Happy diverting!



  1. I’m using a PBX called 3CX. They have a call control API. The API has a “Divert” method, but I can’t make it work — it executes but nothing happens. From your description the divert happens during the invite. That’s a little early in my scenario, so I was wondering if the API could possibly invoke a re-invite to cause the divert to happen after the phone is already “ringing”?…

    1. I am not familiar with that API, but I expect it generates a 301 or 302 response. This is appropriate if it’s a ringing call. You generally don’t use re-INVITE until the session has been established.

  2. ETSI TS 124 238 specifies the syntax for user configuration as “phone-context” parameter is to be set to the home network domain name and the “user” parameter is set to “dialstring”; however this syntax is valid for IMS case. Does it mean, based on your above written article, that Sarah needs to send beforehand an Invite request to a standard SIP-Proxy for activating the diversion feature (as is described in TS 124 238) ?

  3. Hi Andrew,

    Thank you so much for writing about SIP in your blog. You made my life ease. SIP was like a assembly language when I started to learn, but after reading your blogs , I found it very attractive and easy.

    Great work.

    thank you

  4. Narendra · · Reply

    Hi Andrew,

    Your blogs are very useful, it gives a very clear understanding of the things. It is helping lots of people. Your blogs are my first reference , then comes the rfc. Thanks a lot.


    1. Thank you! I love hearing that!

  5. Thank you Andrew…This helped me a lot when I used it for Verizon Trunking

  6. Glad to be of assistance.

  7. Jarmo Kungla · · Reply

    Do you know any SIP Phone CLients, that support Diversion param?

  8. Hi Andrew,
    Although I am very late in reading this article and responding but I think I must comment. I almost never comment on articles/blogs but I must say your article forced me to write comment. I have always looked for such detailed info but most articles miss this.
    After reading your article, I feel my desire is fulfilled and you have made this article compact and complete in every means from ground up.
    Bookmarked and started reading all your articles. Please keep up the good work with such details and dedication.

    Thanks Man.

  9. swarnim · · Reply

    Hi Andrew,
    the way you explain is so helpful indeed.


  10. cameron · · Reply

    May be worth noting somewhere that RFC 5806 is now “Historic” and that, although it may be in use by many live systems (and supported to some degree) more current references would point to RFC 3325 and RFC 4244 (as indicated in RFC 5806). There are also some call scenarios in RFC 5359 which I found quite informative.

  11. Thanks for the explanation Andrew, you made it look easy!

  12. Jimmie Andersson · · Reply

    I love the fact that you managed to include your love-life as a means to explaing Sip diversion headers 🙂

  13. Hallo Andrew,

    First, I can see that this is an old post so not sure if it is active any more? But I have enjoyed reading your many articles as they are always very informative but I feel, in this case, I must make a correction as I believe the information to be slightly ajar.

    I refer to your statement above as to what exactly is a diverted call: ‘This usually boils down to the scenario where A calls B and A is redirected (not transferred) to C.’ and I believe that the correct scenario should read ‘……. where A calls B and B is redirected (not transferred) to C.’

    See the difference, it is the B party that is diverted to C, not the A party, at least that is my understanding of a diverted call (and my background is +40 years in the telecom sector :-)).

    Am I correct?

    Again, many thanks for all of your articles.


    1. Hallo Andrew,

      I have just read this article again (and again) and I think I see where the ‘problem’ lies, as it could be in the jargon…

      ‘….Sarah setting call forward on her SIP telephone to send all incoming calls to Debbie. Now, when Andrew calls Sarah, his call will be automatically sent to Debbie…’

      As I see it, Andrew (the A-party) calls Sarah (the B-party) which is diverted to Debbie (the C-party) so A >>> B diverted to C

      But in the jargon … a ‘diverted’ call is when A calls B (which is diverted to C) but I get it that it is the A-party that is ‘re-directed’ to the C-party?

  14. Jesse Anderson · · Reply

    Dude this is great. I am also from MN (S. Mpls) but live in L.A. now. Also a voip engineer. I’d like to get back there soon. Thanks for the great posts!

    1. Thanks for reading and commenting!

  15. Hey Andrew- question: I’d like to test some Kamailio scripting which takes incoming $div header and inserts into the outbound RURI. What’s the best way to generate these test calls?


  16. Is it possible to change any value in this header using SIP profiles?

    1. For a Cisco Cube? I am not familiar enough with Cube to know that.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: