API voice call with SIP Identity and Privacy headers
Back to Articles
Tutorial VoIP SIP API Reference Howto

API voice call with SIP Identity and Privacy headers

May 23, 2018 2 min
Aivis Olsteins

Aivis Olsteins

When sending voice calls over SIP trunks, it is frequently needed to set specific SIP headers in order to comply with requirements of upstream carriers or pass additional information within call. It can be done when sending SIP calls via API.

One of the most popular case is setting SIP Privacy headers to comply with many European carriers requirements. The purpose of SIP Privacy headers are:

  1. to identify the origin of the call “out of band”. i. e. outside of parameters available to end users, and
  2. pass requested privacy setting to the upstream carrier, while preserving the information about caller for identification and subsequent rating and routing purposes.

 

The above two points are usually interconnected: most carriers now require both settings to be set in SIP message. The first header, asserting the identity of the caller is P-Asserted-Identity and has format as in this example:

 

P-Asserted-Identity tel:+3312345678

 

Note, that phone number is prefixed by tel: string and comes in full E.164 format including plus symbol. This field is usually used to determine the origin country/area of the call and therefore used to make decision how the call should be rated and routed. In countries and carriers which since last year make distinction between calls originated within or outside of EU/EEA, this is the determining field. Absence of this field might cause call to be rated most highest rate (sometimes unreasonably high – so beware) or rejected outright.

 

The other usually required attribute tells carrier whether callers wishes to display it's identity to called party or not. The SIP header name is “Privacy” and example usage is:

 

Privacy: Id

 

The example above shows that downstream carrier should use From SIP header to present as the caller ID to the called party.

 

Now, let's compose the API call with above headers:

 

POST /voice/call/play


{
"to": "123456",
"from": "112233",
"playlist":
[
{
"play": "http://server.domain.com/voices/hello.wav"
},
{
"play": "http://server.domain.com/voices/main-message.wav"
},
{
"play": "http://server.domain.com/voices/goodbye-thanks.wav"
}
]
"carrier_id" : "74445609",
"osip_P-Asserted-Identity" : "tel:+3312345678",
"osip_Privacy" : "Id"
}

So the above example tells upstream carrier that the real caller identity is +3312345678, but the caller should see on their display 112233 as the caller ID. The call is now compliant with carriers requirement and will be properly rated and routed as originated from within EU/EEA country (+33 France prefix).

Note, that custom SIP headers are prefixed by osip_ string and then follow exactly as typed.

Share this article

Aivis Olsteins

Aivis Olsteins

An experienced telecommunications professional with expertise in network architecture, cloud communications, and emerging technologies. Passionate about helping businesses leverage modern telecom solutions to drive growth and innovation.

Related Articles

Case Study: Global Communications Company

Case Study: Global Communications Company

A leading communications company used our cloud Voice platform to send 30 million OTP calls per month to their customers, resulting in cost reduction and incrased conversion

Read Article
Bridging The Delay Gap in Conversational AI: The Backpressure Analogy

Bridging The Delay Gap in Conversational AI: The Backpressure Analogy

Conversational AI struggles with the time gap between text generation and speech synthesis. A “backpressure” mechanism, akin to network data flow control, could slow text generation to match speech synthesis speed, improving user interaction.

Read Article
How Voice AI Agents Can Automate Outbound Calls and Unlock New Opportunities for Businesses: A Deeper Dive

How Voice AI Agents Can Automate Outbound Calls and Unlock New Opportunities for Businesses: A Deeper Dive

AI voice agents transform healthcare scheduling by reducing costs, administrative tasks, and no-shows. They offer 24/7 service, multilingual support, proactive reminders, and valuable insights, improving efficiency and patient experiences.

Read Article
How to Fix Your Context: Mitigating and Avoiding Context Failures in LLMs

How to Fix Your Context: Mitigating and Avoiding Context Failures in LLMs

Larger context windows in LLMs cause poisoning, distraction, confusion, and clash. Effective context management (RAG, pruning, quarantine, summarization, tool loadouts, offloading) remains essential for high-quality outputs.

Read Article

SUBSCRIBE TO OUR NEWSLETTER

Stay up to date with the latest news and updates from our telecom experts