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.


Additional sipis server-wide options related to incoming call handling
----------------------------------------------------------------------

See the settings section for more complete description of the following fields.

``Sipis/IncomingCall[PostponeRingingResponseUntilDeviceIsMakingProgress]``
    When set to ``Yes``, sipis will not send ``180 Ringing`` response in step 2.

``Sipis/IncomingCall/DeviceNotMakingProgressMaxAge[Days, Hours, Minutes, Seconds]``
    Allows specifying custom value for timer T1.

``Sipis/IncomingCall/NotAnsweredMaxAge[Days, Hours, Minutes, Seconds]``
    Allows specifying custom value for timer T2.