.. _smart_contacts:

==============
Smart Contacts
==============

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

Introduction
============

Smart Contacts feature resolves address book of the user on the server and finds contacts which are using the same
service. When the app knows this information, it can offer additional communication options to these users and show
them with a special badge or color.

Requirements
============

Verified phone number
~~~~~~~~~~~~~~~~~~~~~
In order to make Smart Contacts work and be accurate, it's necessary to know the correct phone number of the user which
is using the app. Ideally it will be the number under which he/she is known in address books of other people.

:ref:`phone_number_verifier` web service is used to verify phone numbers during provisioning, typically via SMS
confirmation.

.. note::
   :ref:`phone_number_verifier` web service is only available for Cloud Softphone White Label apps. Smart Contacts
   functionality is not possible with generic Cloud Softphone app.

Contacts server
~~~~~~~~~~~~~~~
Address book resolution is done on the server, where address books of all other users using the same phone service are
also stored. :ref:`contact_sync` is therefore required for Smart Contacts to work.

SSO Server
~~~~~~~~~~
SSO server is required by Contacts server.

Example workflows
=================

.. note::

   The workflows below are provided in an effort of making understanding of this functionality easier. The processes
   described here are implemented by Acrobits software and no additional work is needed to make them work.

Initial situation
~~~~~~~~~~~~~~~~~
Mobile Cloud Softphone White Label app is freshly installed on a mobile device. Smart Contacts are enabled and properly
configured for this app on Cloud Softphone portal.

A. Phone number verification and provisioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. The app is launched and asks users for his phone number. The phone number will be provided in full international
   format, the app will help user to enter the number correctly.
#. User submits the number and :ref:`phone_number_verifier` web service is called. This web service should send an
   SMS to the provided number with a verification code.
#. The user receives SMS and submits the correct verification code. External provisioning web service will be called.
#. External provisioning will receive the following data: ``phone number``, ``verification code``, ``cloud id``. It
   should check whether there already is a SIP account attached to this phone number and create a new one if it isn't.
   Account credentials are then sent as a response back to mobile client, which uses them to register to SIP server.

.. note::

   After this step is complete, the provider should have a record in its database which links user's SIP account with
   user's verified phone number. On the other hand, the client knows its SIP username and SIP password.

B. Obtain Access token from SSO server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The process is exactly the same as described in :ref:`contact_sync` workflow

C. Create Smart Entry
~~~~~~~~~~~~~~~~~~~~~
#. The app sends a request to Contacts server to become a "smart" contact. It will authenticate itself with access token
   and passes SIP uri where it can be reached( sip-username@sip-domain)
#. Contacts server will validate the access token and get the list of verified phone numbers related to it.
#. Contacts server will create records in its smart contacts database, which say: **Verified phone number XYZ may also be
   contacted via SIP uri abc@domain.com**. The phone number is verified by :ref:`phone_number_verifier`, the SIP uri by
   :ref:`ext_auth`

.. warning::

   It's very important to always return consistent results from external provisioning and external authentication web
   services.

   **External Authentication** should always respond with numbers which  have been used to register SIP
   account whose credentials were sent as input.

   **External Provisioning** should always check whether a SIP account for given number already exist and return the same
   one if it does.

   Inconsistent web service responses will lead to inconsistent contacts database and Smart Contacts feature will most
   likely not work correctly.

D. Find which contacts are "smart" in mobile device address book
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. The app sends a query to Contacts server to get all smart contacts from local address book
#. Contacts server scans the server-side copy of mobile device address book. For each number for which Smart Entry
   exists, include it in the response together with its SIP uri
#. Response is sent to mobile app, which will use it to highlight contacts with smart numbers and offer additional
   features for them.