=========
Call URIs
=========

.. contents::
   :local:
   :depth: 3

Overview
~~~~~~~~
It is possible to launch Acrobits apps by a click on a link in a web browser, email client etc. The link contains a
number to call and optionally additional parameters. When the app is launched, the phone number is pre-filled into the
number field and optionally, it can be automatically dialed.

URIs
~~~~
The call URIs have the following format:

    ``scheme:number?dialAction=xxxxxx``

**scheme**
           Scheme can be either ``sip``, which is the universal scheme which is usually intercepted by most VoIP apps. There is
           a chance that tapping on a link with sip: scheme will trigger some other VoIP app, especially if the other
           VoIP app was installed after Acrobits app.

           There are also schemes which are specific for Acrobits apps. Links using this URL scheme will always open the
           referenced app:

           ===================   ==========
           The App               Scheme
           ===================   ==========
           Acrobits Softphone    asoftphone
           -------------------   ----------
           Groundwire            groundwire
           -------------------   ----------
           Cloud Softphone       cloudsip
           ===================   ==========

.. note::

           For Cloud Softphone White-Label apps, you can configure any scheme you want in Cloud Softphone portal.

**number**
           This is the number to be dialed. It must not contain any spaces.

**dialAction**
           If this optional parameter is specified, it contains the dial action to perform with this number. If it's
           omitted, the app will be launched and the number pre-filled, but the user will have to dial the number by
           tapping the "call" button.

           For the list of possible dial actions, please see the table in :ref:`dialactions` article.

Universal Links
~~~~~~~~~~~~~~~

Univeral links provide a way to launch the app on a device in case the app is installed, or show a web page instead
(typically a web page about the app, with a link to install it). Universal links have form of standard http: or https:
links, which makes them clickable in most apps like email and messaging clients and messaging app, but having the fixed
http(s) scheme means we can't directly use universal links as call uris described above.

To use the existing infrastructure with universal links, we implemented the following convention: In case the universal
link contains `scheme` parameter, we convert the link internally into the `scheme:` link using the last compoment of the
path taken from universal url and all the parameters.

An example will make it clear:

https://some.domain.com/apps/myapp/+15551231234?scheme=sip&dialAction=videoCall

is transformed internally into

sip:+15551231234?dialAction=videoCall

and it will trigger a video call to number ``+15551231234``


Examples:
~~~~~~~~~

``sip:12345``

    Will launch the app which is registered to receive sip: uris (usually the last installed VoIP app) and pass the
    number to it. If it is an Acrobits app, the number will be pre-filled and user will decide how/if the number should
    be dialed.

``cloudsip:+15551231234?dialAction=text``

    Will launch Cloud Softphone and starts a text new message to the given number.

``groundwire:+15557897890?dialAction=gsmCall``

    Will launch Groundwire, and from Groundwire, a gsm call will be originated to the given number.