API voice call with SIP Identity and Privacy headers
Most carriers now required properly set SIP Identity and Privacy headers. Here is how to set them in the API call.
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:
- to identify the origin of the call “out of band”. i. e. outside of parameters available to end users, and
- 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.
