============
Command URIs
============

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

Overview
~~~~~~~~
Cloud Softphone allows showing contents loaded from the web (one typical example is a custom tab which shows an embedded
browser open with URL which you can specify). It is sometimes useful to pass some information from this embedded browser
back to the app. This can be achieved by command URIs described below.

These URIs can be invoked from javascript as a reaction to some events, or simple links or buttons with these URLs can
be created and the action will be performed when the user clicks on them.

The links can be functional only from within the embedded browser (this is the ``app`` scheme).
They can be functional from system browser (this is via the ``cloudsip`` or similar scheme).
They can be also functional as deep links (iOS) which prompt for app installation if app is not yet installed.

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

    ``app:command[?params]``

If the URIs needs to be functional from outside of the application, the whole app URL needs to be urlencoded and passed via
a registered scheme (like ``cloudsip`` or white-label specific scheme). If follows the followinf format:

    ``scheme:?_cmd=urlencoded_app_url``

**scheme**
           The default scheme for Cloud Softphone is ``cloudsip``.

.. note::

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

**command**
           The encoded URL of the command including possible parameters.

**parameters**
           These are command-specific and will be described below for each command.

Commands:
~~~~~~~~~

``balance-update``
------------------

    Will generate an immediate balance check. This is useful when the user tops up inside the web browser and the
    balance should be updated as soon as possible.

    The balance checking web service is documented in :ref:`balance_checker` article.

**Parameters**
    none

**Example**:
  ::

    app:balance-update
    cloudsip:?_cmd=app%3Abalance-update    

``provisioning-update``
-----------------------

    Will trigger immediate re-provisioning. This is useful when user does some changes in his account settings and the
    new settings should be synced with the app as soon as possible.

**Parameters**
    none

**Example**:
  ::

    app:provisioning-update
    cloudsip:?_cmd=app%3Aprovisioninig-update

``extprov-update``
------------------

    Will trigger immediate re-provisioning only from the external provisioning URL (not trying to reprovision from the portal).
    This is useful when user does some changes in his account settings and the new settings should be synced with the app as soon as possible.

**Parameters**
    none

**Example**:
  ::

    app:extprov-update
    cloudsip:?_cmd=app%3Aextprov-update

``settings``
-------------

  Opens the settings screen on the main page.

**Parameters**
    none

**Example**:
  ::

    app:settings
    cloudsip:?_cmd=app%3Asettings


``settings/prefs``
------------------

  Opens the settings screen on the preferences page.

**Parameters**
    none

**Example**:
  ::

    app:settings/prefs
    cloudsip:?_cmd=app%3Asettings%2Fprefs


``settings/topup``
------------------

  Opens the settings screen on the topup page. If the parameters are present, it will try to initiate the in-app purchase of the specified product.
  If the product ID starts with the application ID, you are allowed to omit the application ID prefix. If ``product_id`` is specified the app opens the detail page of the requested topup amount. If ``action=buy`` is specified it initiates the purchase automatically.

**Parameters**
    ::
      
      action=buy
      product_id=in-app-purchase_product_id

**Example**:
    :: 

     app:settings/topup
     cloudsip:?_cmd=app%3Asettings%2Ftopup     

    :: 

     app:settings/topup?action=buy&product_id=com.myapp.credit1
     cloudsip:?_cmd=app%3Asettings%2Ftopup%3Faction%3Dbuy%26product_id%3Dcom.myapp.credit1


``settings/addons``
-------------------

  Opens the settings screen on the addons page. If the parameters are present, it will try to initiate the in-app purchase of the specified product.
  If the product ID starts with the application ID, you are allowed to omit the application ID prefix. If ``product_id`` is specified the app opens the detail page of the requested addon. If ``action=buy`` is specified it initiates the purchase automatically.

**Parameters**
  ::

    action=buy
    product_id=in-app-purchase_product_id

**Example**:
  ::

    app:settings/topup
    cloudsip:?_cmd=app%3Asettings%2Ftopup

  ::

    app:settings/topup?action=buy&product_id=com.myapp.credit1
    cloudsip:?_cmd=app%3Asettings%2Ftopup%3Faction%3Dbuy%26product_id%3Dcom.myapp.credit1

``qd``
------

  Opens the quick dial tab.

**Parameters**
    none

**Example**:
  ::

    app:qd
    cloudsip:?_cmd=app%3Aqd


``history``
-----------

  Opens the history tab.

**Parameters**
    none

**Example**:
  ::

    app:history
    cloudsip:?_cmd=app%3Ahistory

``keypad``
----------

  Opens the keypad tab.

**Parameters**
    none

**Example**:
  ::

    app:keypad
    cloudsip:?_cmd=app%3Akeypad

``messages``
------------

  Opens the messages tab.

**Parameters**
    none

**Example**:
  ::

    app:messages
    cloudsip:?_cmd=app%3Amessages

``contacts``
------------

  Opens the contacts tab.

**Parameters**
    none

**Example**:
  ::

    app:contacts
    cloudsip:?_cmd=app%3Acontacts

``browser``
-----------

  Opens the browser tab.

**Parameters**
    none

**Example**:
  ::
  
    app:browser
    cloudsip:?_cmd=app%3Abrowser