.. _dialactions:

============
Dial Actions
============

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

Overview
========

Dial Actions are "commands" which tell Acrobits client what to do with the particular number. In Cloud Softphone, it's
possible to configure which dialAction will be performed when dialing the number by single-tap, long-press and 3D-touch
on iOS devices which support it.

For example, you can configure the "call" button in keypad screen to do a SIP call for single-tap and cellular call on
long-press, or show all available dial actions as a menu on single tap.

There are two kinds of Dial Actions. The Basic Dial Actions are hard-coded into the app and provide the elementary
operations on the dialed number. Programmable Dial Actions can be defined by the user or provisioned by provider and
may be used to control advanced PBX features or provide any other advanced functionality.

.. _basic-dialactions:

Basic Dial Actions
==================
The table below lists the supported dial actions.

+-------------------+--------------------------------------------------------------------------------------------------+
|dialAction         |Description                                                                                       |
+===================+==================================================================================================+
|autoCall           || start a VoIP call. The video will be enabled based on the value in                              |
|                   || **autoSendVideo** preference key.                                                               |
+-------------------+--------------------------------------------------------------------------------------------------+
|voiceCall          || start a voice-only VoIP call                                                                    |
+-------------------+--------------------------------------------------------------------------------------------------+
|videoCall          || start a VoIP call with video                                                                    |
+-------------------+--------------------------------------------------------------------------------------------------+
|gsmCall            || dial the number via cellular network                                                            |
+-------------------+--------------------------------------------------------------------------------------------------+
|webCallback        || triggers webCallback. Web service will be called with the given number and                      |
|                   || an incoming call will be expected.                                                              |
+-------------------+--------------------------------------------------------------------------------------------------+
|callThrough        || triggers call-through. In case a web service is defined, it will be asked for                   |
|                   || access number and dial string, otherwise the preconfigured access number will                   |
|                   || be used.                                                                                        |
+-------------------+--------------------------------------------------------------------------------------------------+
|text               || compose a new text message to the given number.                                                 |
+-------------------+--------------------------------------------------------------------------------------------------+
|openUrl            || Opens an external browser with an URL defined in Account XML and passes the                     |
|                   || number as a parameter.                                                                          |
+-------------------+--------------------------------------------------------------------------------------------------+
|options            || shows a menu with all applicable dial actions for the given number.                             |
+-------------------+--------------------------------------------------------------------------------------------------+
|customOptions      || this dialAction supports an additional argument with the list of dial actions                   |
|                   || to be offered to the user. In case this list is empty or missing, the app shows                 |
|                   || a menu with all programmable dial actions configured for the app. See Programmable              |
|                   || Dial Actions and the example XML below.                                                         |
+-------------------+--------------------------------------------------------------------------------------------------+
|forceOffnet        || For "smart" contacts, Acrobits apps always prefer to make on-net call. This dial                |
|                   || action will force an off-net call to the PSTN number.                                           |
+-------------------+--------------------------------------------------------------------------------------------------+

Programmable Dial Actions
=========================

Programmable Dial Actions use :ref:`number-rewriting` rules and conditions to define how is the given number or SIP uri going
to be dialed. When the action is triggered, the rules may modify the number by adding special codes before or after,
replace parts of the number, set flags like whether the call should be recorded by the app or not and which of the
Basic Dial Actions should be used to actually do something with the number.

Programmable Dial Action should always resolve to some Basic Dial Action on a number which may be a modified version of
the original number. The most simple Programmable Dial Action would only have one ``overrideDialAction`` rule (without
any condition) which sets the action to one of the Basic Dial Actions defined above.

Dial Actions may be provisioned by including a node ``<dialActions>`` in provisioning XML. They can also be configured
at Cloud Softphone portal and set via :ref:`global-external-provisioning`.

XML Format
==========

The format of the XML is given below:

 .. code-block:: xml

    <dialActions>
      <dialAction id="recordCall">
        <displayName>
          <value lang="cs">Nahrávaný hovor</value>
          <value lang="jp">記録されたコール</value>
          <value>Recorded Call</value>
        </displayName>

        <rewriting>

          <rule>
            <conditions/>
            <actions>
              <action type="overrideDialAction" param="autoCall"/>
              <action type="recordCall"/>
            </actions>
          </rule>

        </rewriting>
      </dialAction>

      <dialAction id="monitorCall">
        <displayName>Monitor</displayName>

        <rewriting>

          <rule>
            <actions>
              <action type="overrideDialAction" param="autoCall"/>
              <action type="continue"/>
            </actions>
          </rule>

          <rule>
            <conditions>
              <condition type="doesntStartWith" param="#"/>
            </conditions>
            <actions>
              <action type="prepend" param="#11#"/>
            </actions>
          </rule>

        </rewriting>
      </dialAction>
    </dialActions>

    <dialAction id="custom1">
      <displayName>custom1</displayName>
      <rewriting>

          <rule>
            <actions>
              <action type="overrideDialAction" param="customOptions">
                <options>autoCall,recordCall,monitorCall</options>
                <message>Please choose how to complete the call</message>
              </action>
            </actions>
          </rule>

      </rewriting>

      </dialAction>
    </dialActions>

The dial action "custom1" can be assigned to a "dial action for long press" and when the user does a long press on a
number, the app will offer a menu with three options - a simple `autoCall` plus the two custom action defined above.
It is possible to specify the text for the title of the menu in a ``message`` node.

The nodes which define Dial Actions must be named ``dialAction`` and may have the following attributes:

``id``
~~~~~~

    Unique identifier of this dial action. When merging, the app will try to find a dialAction with the same id which
    is already stored in the app. If not found, the incoming dialAction is simply saved, otherwise it's merged with
    the existing one.

``action``
~~~~~~~~~~

    The default action is ``merge``, which merges this dialAction with those already stored in the app. In case you
    specify ``action=remove``, the app will try to find stored dialAction with the same ``id`` and if found, this
    dialAction will be deleted.

Inside ``dialAction`` nodes are :ref:`mergeable-xml` key nodes, which have the usual attributes ``source`` and
``priority``. The following key nodes are supported:

``displayName``
~~~~~~~~~~~~~~~

This key node contains the name of dial action, as it will be shown to user. The content of this node is localizable;
it is possible to provide multiple translations.

``condition``
~~~~~~~~~~~~~

Some dial actions will need network connection, otherwise it doesn't make sense to offer them to the user. Others will
only work on a device with cellular call capability (like call-through based dial actions).

Possible values: <empty>, ``net``, ``gsm``. If left empty, the condition will always show; otherwise it will show only
if network or cellular capability is detected.

``rewriting``
~~~~~~~~~~~~~

The ``rewriting`` node defines number rewriting rules as specified in :ref:`number-rewriting` section.