There are multiple ways about how SIP gateway providers (also known as SIP proxies) handle caller ID passing. Some of them are modern and refined, some are archaic and broken but accepted by convention.

The following text assumes that you are properly passing the desired caller-ID, i.e using the variable origination_caller_id_number. Also, your use case is to programmatically originate a call from freeswitch on behalf of your users, as we do in DandyDialer.

Using From header

Some SIP providers extract the caller-ID directly from the From header sent during the INVITE stage. It’s not the official way doing things, but a lot of gateway providers do it anyway.

In Freeswitch, there is a boolean gateway parameter named caller-id-in-from which turns on this behavior.

<include>
  <gateway name="foo-gateway">
  ...
  <param name="caller-id-in-from" value="true" />
  ...
  </gateway>
</include>

Using Remote-Party-ID header

This is an obsolete header defined in an unaccepted RFC which probably gained some traction before P-Asserted-Identity and P-Preferred-Identity were invented. Some SIP providers still swear by the simplicity of it. Also, by default Freeswitch tries to send caller identity using this header.

To send this header, you need to set caller ID type to - rpid. There are different ways to do that:

  • Passing a call origination variable: 
    originate {origination_caller_id_number=9005554321,sip_cip_type=rpid}sofia/default/whatever@whatever 190005551234 XML default
  • Setting gateway configuration parameter: 
    <include>
  <gateway name="foo-gateway">
  ...
  <param name="cid-type" value="rpid" />
  ...
  </gateway>
</include>
  • Setting sofia profile configuration parameter: 
    <include>
  <profile name="foo-sip-profile">
  ...
  <param name="caller-id-type" value="rpid" />
  ...
  </profile>
</include>

Using P-Asserted-Identity header

As of time of writing of this document, using freeswitch 1.10.5-release-17, I found Freeswitch’s behavior related to P-Preferred-Identity and P-Asserted-Identity to be completely opposite of what the wiki1 says.

This is the modern and accepted equivalent of Remote-Party-ID header. Most modern SIP proxies support this.

To send this header, you need to do two things:

  • Set caller ID type to - pid. You can achieve this in different ways:
    • Passing a call origination variable: 
      originate {origination_caller_id_number=9005554321,sip_cip_type=pid}sofia/default/whatever@whatever 190005551234 XML default
    • Setting gateway configuration parameter: 
      <include>
  <gateway name="foo-gateway">
  ...
  <param name="cid-type" value="pid" />
  ...
  </gateway>
</include>
    • Setting sofia profile configuration parameter: 
      <include>
  <profile name="foo-sip-profile">
  ...
  <param name="caller-id-type" value="pid" />
  ...
  </profile>
</include>
  • Must not set origination_privacy variable to anything, not even to none. Note that this is opposite of what the freeswitch wiki1 says.

Send P-Preferred-Identity header

P-Preferred-Identity header is the privacy aware cousin of P-Asserted-Identity. If you send this, you are also supposed to send some privacy controlling headers.

To send P-Preferred-Identity, you need to do two things:

  • Set caller ID type to - pid.
  • Must set origination_privacy variable to something. In general use, where there is no concern for privacy, you can set it to none.

Just like P-Asserted-Identity, you are free to set caller-ID type using whatever is preferable to your setup, be it gateway configuration, sip profile configuration or origination variable. Here’s an example of using the originate command directly:

originate {origination_caller_id_number=9005554321,sip_cip_type=pid,origination_privacy=none}sofia/default/whatever@whatever 190005551234 XML default

Additional notes

caller-id-in-from can be set independently to other caller-ID related headers you might send. So, it’s probably a good idea set it to true by default.

I just want to make automated calls. Give me an easy solution!

OK! You asked for it. Go sign-up for DandyDialer. We took care of all the caller-ID related header management and they are exposed as easy to use drop-downs. You can find them in advanced gateway configuration.

References

Footnotes

  1. Freeswitch Wiki - sip_cid_type variable ↩ ↩2

Titon Barua

Author

Titon Barua

Co-founder and Lead Developer

Titon is a software developer and architect with decades of experience in various web technologies, both in front-end and back-end. He prides himself in making robust and user-friendly software. An avid pythonista for a long time, these days, Titon mostly writes Clojure and Clojurescript.