Incoming call handling

When sipis receives incoming INVITE request, it usually takes the following steps

  1. It sends push notification to registered user’s device(s).

  2. It immediately sends a provisional 180 Ringing response to the originating SIP proxy. Sipis will also include X-Sipis-Push-Status: Alerting-Device header in this response.

  3. It starts timer T1 to fire in two minutes.

  4. It waits for some user’s device to answer the call.

  5. Push notification service notifies sipis that the push notification has been sent. Upon receiving this notification, sipis sends another provisional 180 Ringing response to the originating SIP proxy, this time with X-Sipis-Push-Status: Push-Notification-Sent header.

  6. User’s device notifies sipis via a fast channel that it is about to answer the call. Upon receiving this notification, sipis sends yet another provisional 180 Ringing response to the originating SIP proxy, this time with X-Sipis-Push-Status: Device-Making-Progress header. Also, at this point sipis cancels timer T1 and starts timer T2 to fire in two minutes from this point. (User’s device may send this notification multiple times, but sipis will perform the above steps only for the first notification and will take no action for subsequent ones.)

  7. User’s device finally establishes a connection to sipis and accepts the call.

  8. At this point sipis relays SIP messages between the SIP proxy and user’s device until the end of the call.

Special Cases

The default sequence of steps can branch into several special cases described below.

No user’s device responds until timer T1 expires

In this case sipis will reject the incoming INVITE request with 480 Temporarily Unavailable response. (Since 3.54) Sipis will also include X-Sipis-Reason: No-Response-From-Device header in this response.

(Since 3.54) The response can also be customized via Sipis/IncomingCall/OnNoResponseFromDevice option.

User’s device notifies sipis but doesn’t answer the call until timer T2 expires

In this case sipis will reject the incoming INVITE request with 480 Temporarily Unavailable response. (Since 3.54) Sipis will also include X-Sipis-Reason: No-Response-From-User header in this response.

(Since 3.54) The response can also be customized via Sipis/IncomingCall/OnNoResponseFromUser option.

Push notification service indicates that it was unable to deliver the push notification

In this case sipis will reject the incoming INVITE request with 480 Temporarily Unavailable response. (Since 3.54) Sipis will also include X-Sipis-Reason: Push-Notification-Failure header in this response.

(Since 3.54) The response can also be customized via Sipis/IncomingCall/OnPushNotificationFailure option.

Push notification service indicates that the application on user’s device has been uninstalled

In this case sipis will reject the incoming INVITE request with 480 Temporarily Unavailable (Until 3.53) / 410 Gone (Since 3.54) response. (Since 3.54) Sipis will also include X-Sipis-Reason: Device-Token-Not-Found header in this response.

(Since 3.54) The response can also be customized via Sipis/IncomingCall/OnDeviceTokenNotFound option.

Furthermore sipis will automatically stop and remove the SIP client instance, so it will no longer accept incoming calls.

Sipis receives CANCEL request from the originating SIP proxy

In this case sipis will reject the incoming INVITE request with 487 Request Terminated response. Furthermore sipis will send push notification to registered user’s device(s), notifying them that the call is no longer active.

Application is in foreground on some user’s device

In this case sipis will immediately reject the incoming INVITE request with 488 Not Acceptable Here response, assuming that the SIP proxy did fork the INVITE request to the user’s device as well.