Blog Page

Voice API call with SIP UPDATE message

Some carriers may request that the callers update their SIP sessions at specific intervals

Earlier we discussed about setting specific SIP headers in calls generated by API.

Some voice carriers set specific requirements of how SIP sessions should be set and maintained. For example, there might be requirement to update call state information every given number of minutes during active call to indicate that the call is still alive. If the caller party does not issue call update every at predetermined time frames, the session is considered closed, and call is disconnected.

To update call status, SIP method UPDATE is used. Here is an example of SIP INVITE with subsequent UPDATE sent later within call:

INVITE sip:1234567890@10.1.1.1:5060;user=phone SIP/2.0  
To: "1234567890"<sip:1234567890@10.1.1.1:5060;user=phone>
From: "987654321" <sip:987654321@10.1.1.2;user=phone>
Session-Expires: 1800;refresher=uac 
Call-ID: 123456789abcdef@10.1.1.1:5060
Contact: <sip:987654321@10.1.1.2:5060>
Allow: ACK, INVITE, BYE, CANCEL, REGISTER, REFER, OPTIONS, PRACK, INFO, UPDATE 
Content-Type: application/sdp 
Content-Length: 280 

And later, in the call:

UPDATE sip:1234567890@10.1.1.1:5060;user=phone SIP/2.0
Call-ID: 123456789abcdef@10.1.1.1:5060
To: "1234567890"<sip:1234567890@10.1.1.1:5060;user=phone>
From: "987654321" <sip:987654321@10.1.1.2;user=phone>
CSeq: 26 UPDATE 
Allow: ACK, INVITE, BYE, CANCEL, REGISTER, REFER, OPTIONS, PRACK, INFO, UPDATE 
Content-Length: 0 

To which the other party replies with:

SIP/2.0 200 OK 
From: "1234567890"<sip:1234567890@10.1.1.1:5060;user=phone>
To: "987654321" <sip:987654321@10.1.1.2;user=phone>
Call-ID: 123456789abcdef@10.1.1.1:5060 
CSeq: 26 UPDATE 
Content-Length: 0

Important to note, that in order for other party to properly identify the call which is being updated, it is essential to send proper request URI and Call-ID header value.

Now, in the context of API, the call request send a voice call callback request with update every 15 minutes on both call legs, the request will look like this:

POST /voice/call/callback 

{
  "leg_A":
    {
      "to": "1000123",
      "from": "1000125",
      "sip_update": 900
    },
  "leg_B": 
    {
      "to": "1000125",
      "from": "1000123",
      "sip_update": 900
   }
}

The attribute sip_update takes integer value in seconds and asks to send SIP UPDATE every 900 seconds to the both parties.

Finally, let's look at slightly more complex example: SIP UPDATE and Privacy headers request:

POST /voice/call/callback 

{
  "leg_A":
    {
      "to": "1000123",
      "from": "1000125",
      "osip_P-Asserted-Identity": "tel:+3312345678",
      "osip_Privacy": "Id"
      "sip_update": 900
    },
  "leg_B": 
    {
      "to": "1000125",
      "from": "1000123",
      "osip_P-Asserted-Identity": "tel:+4412345678",
      "osip_Privacy": "Id"
      "sip_update": 900
   }
}

The above example will set privacy headers to their proper, E.164 formatted values for call routing and rating purposes, while keeping their shorter, informal IDs in “from” fields, as well as send SIP UPDATE every 15 minutes to both call legs.