============
XMPP Service
============

.. toctree::
   :maxdepth: 1


.. contents:: List of available services
   :local:
   :depth: 1


.. _dynamic-buddies:

Dynamic Buddies
===============

Xmpp Service VCard returns dynamic buddies configuration. You can find it on **DESC** field.

**VCard Fields:**

+------------------+-------------------------------------------------+
| **Field**        | **Description**                                 |
+==================+=================================================+
| payload          | Json payload with dynamic buddies configuration |
+------------------+-------------------------------------------------+
| url              | Doesn't manage on xmpp_service                  |
+------------------+-------------------------------------------------+
| thumb            | Doesn't manage on xmpp_service                  |
+------------------+-------------------------------------------------+
| status           | Doesn't manage on xmpp_service                  |
+------------------+-------------------------------------------------+

**Json Parameters:**

+-----------------------------+--------------------------------------------------------------------------------------------------------+
| **Param**                   | **Description**                                                                                        |
+=============================+========================================================================================================+
| DESC                        | Payload param inside vcard with all info about buddy                                                   |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| DESC:**items**              | Items array that represent channels                                                                    |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| items:**mobileIsPublished** | Flag to determine if item on mobile application are published                                          |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| items:**webIsPublished**    | Flag to determine if item on webchat application are published                                         |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| items:**address**           | Channel address set server side, if *serverAddress* exists it will be *thread* on xmpp message         |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| items:**serverAddress**     | Channel server address set server side, it's not mandatory and if set it will be *to* on xmpp message  |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| items:**type**              | Channel type: **group** or **channel**                                                                 |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| info:**name**               | Channel name to show                                                                                   |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| info:**status**             | Channel status to show                                                                                 |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| info:**imageUrl**           | Avatar Image Url to show                                                                               |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| info:**thumbUrl**           | Avatar Thumb Url to show                                                                               |
+-----------------------------+--------------------------------------------------------------------------------------------------------+
| items:**items**             | Items array that represent channels on channel parent container                                        |
+-----------------------------+--------------------------------------------------------------------------------------------------------+


**Example:**

.. code-block:: xml

  <iq xmlns="jabber:client" id="2e46de1f-0438-48b8-a861-d7f1b657f436" type="set">
    <vCard xmlns="vcard-temp">
     <DESC>
      {
        "items": [
          {
            "address": "ae72f789-8edc-413e-870a-ec5d23877813",
            "serverAddress": "bot-management",
            "type": "channel",
            "mobileIsPublished": true,
            "webIsPublished": true,
            "info": {
              "name": "bot-for-test-all-possibilities-facebook",
              "status": "",
              "imageUrl": "",
              "thumbUrl": "",
              "defaultMessage": ""
            }
          },
          {
            "address": "29ed6653-29db-47ff-ba44-344853fcbc61",
            "serverAddress": "bot-management",
            "type": "channel",
            "mobileIsPublished": false,
            "webIsPublished": true,
            "info": {
              "name": "Bot for Test: All possibilities",
              "status": "",
              "imageUrl": "",
              "thumbUrl": "",
              "defaultMessage": ""
            }
          },
          {
            "address": "ffc2b639-bbc0-47c1-acd3-e9a4e74f865c",
            "serverAddress": "bot-management",
            "type": "channel",
            "mobileIsPublished": true,
            "webIsPublished": false,
            "info": {
              "name": "Fibra Fastweb",
              "status": "Fibra FW Demo",
              "imageUrl": "",
              "thumbUrl": "",
              "defaultMessage": "Ottimo! Hai scelto l'offerta Fibra FW per la tua abitazione!\\n\\n\\n\n\nSe completiamo la raccolta di informazioni necessarie, possiamo procedere ad attivare il contratto e la linea al pi&#xF9; presto\\n\\n\\n\n\nSappi che puoi riprendere quando vuoi la conversazione e completare gli step con comodo."
            }
          }
        ]
      }
      </DESC>
    </vCard>
  </iq>

**Example with Mobile Ticketing:**

.. code-block:: json

  {
    "items": [
      {
        "address": "mobile_ticketing_group",
        "type": "group",
        "mobileIsPublished": true,
        "webIsPublished": false,
        "info": {
          "name": "Mobile Ticketing",
          "status": "Acquista qui i tuoi biglietti",
          "imageUrl": "http://....",
          "thumbUrl": "http://...."
        },
        "items": [
          {
            "address": "atm_milano",
            "type": "channel",
            "serverAddress": "myticket",
            "mobileIsPublished": true,
            "webIsPublished": false,
            "info": {
              "name": "ATM Milano",
              "status": "Qui i biglietti di Milano",
              "imageUrl": "http://....",
              "thumbUrl": "http://....",
              "defaultMessage": "Ciao qui puoi acquistare i fantastici biglietti di ATM Milano"
            }
          },
          {
            "address": "atm_firenze",
            "type": "channel",
            "serverAddress": "myticket",
            "mobileIsPublished": true,
            "webIsPublished": false,
            "info": {
              "name": "ATAF Firenze",
              "status": "Qui i biglietti di Firenze",
              "imageUrl": "http://....",
              "thumbUrl": "http://....",
              "defaultMessage": "Ciao qui puoi acquistare i fantastici biglietti di ATAF Firenze"
            }
          }
        ]
      }
    ]
  }


Below an example with a simple channel without group:

.. code-block:: json

  {
    "items": [
      {
        "address": "liam",
        "type": "channel",
        "serverAddress": "liam",
        "mobileIsPublished": true,
        "webIsPublished": false,
        "info": {
          "name": "Liam",
          "status": "Life in a monk house",
          "imageUrl": "http://....",
          "thumbUrl": "http://....",
          "defaultMessage": "Ciao qui puoi accedere a tutte le funzionalità della Monk House"
        }
      }
    ]
  }


.. _add-to-roster:

Add To Roster
=============

Backend application adds to Roster all channels received that are:

- without a group
- without a name
- with a different name found on the Roster
- on the AddressBook but don't exist on the Roster
- with OTHERS group and a subscription diffent of none


**Request message:**

+---------------------------+-----------------------------------+-------------------------------------------------------------+
| **Tag**                   | **Value**                         |                                                             |
+===========================+===================================+=============================================================+
| x:type                    | cmd_add_to_roster                 |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:action                  | cmd_add_to_roster                 |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:payload                 | Json object named channelUsers    |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:channelUsers      | Array of ChannelUser              |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:status            | int                               | 0 => OK; other => ERROR                                     |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorCode         | string                            | SQL_ERROR|NO_USER_FOUND|NO_CHANNEL_FOUND                    |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorMessage      | array of objects                  | Each object has one element, with message key               |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| errorMessage:message      | string                            | Text of message                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+

**Example:**

.. code-block:: xml

    <message to="xmpp_service@monksoftware.it" id="1486028547270039399072925" type="chat">
        <body />
        <x xmlns="jabber:x:oob">
            <type>cmd_add_to_roster</type>
            <action>cmd_add_to_roster</action>
            <payload>{
                "channelUsers":[
                {
                  "name": "Mario Rossi",
                  "address": "00393471111111"
                },
                {
                  "name": "Luca Rossi",
                  "address": "00393472222222"
                }
              ]
            }</payload>
        </x>
    </message>

.. _search-users:

Search Users
============

This command is used to update the local roster with contacts fetched from mobile contact list.

**Request message:**


+---------------------------+-----------------------------------+-------------------------------------------------------------+
| **Tag**                   | **Type**                          | **Description**                                             |
+===========================+===================================+=============================================================+
| x:type                    | cmd_search_users                  |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:action                  | cmd_search_users                  |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:payload                 | object                            |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:userList          | array of msisdn                   | List of MSISDN (International format) to search for         |
+---------------------------+-----------------------------------+-------------------------------------------------------------+

**Example:**

.. code-block:: xml

 <message to="xmpp_service@monksoftware.it" id="1486028547270039399072925" type="chat">
        <body />
        <x xmlns="jabber:x:oob">
            <type>cmd_search_users</type>
            <payload>
            {
               userList: ["00393296260815","00393333333333","00393490899289","00393494371802","00393497588825"]
            }
           </payload>
        </x>
        <body/>
    </message>



**Response message:**


+---------------------------+-----------------------------------+-------------------------------------------------------------+
| **Tag**                   | **Type**                          | **Description**                                             |
+===========================+===================================+=============================================================+
| x:type                    | same as sent                      |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:action                  | same as sent                      |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:payload                 | object                            |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:status            | int                               | 0 => OK; other => ERROR                                     |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorCode         | string                            | SQL_ERROR                                                   |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorMessage      | array of objects                  | Each object has one element, with message key               |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| errorMessage:message      | string                            | Text of message                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:userList          | array of msisdn                   | List of contacts found in XMPP from given list              |
+---------------------------+-----------------------------------+-------------------------------------------------------------+

**Example:**

.. code-block:: xml

    <message to="00393331486253@ciaoamici" id="456a1800-7e38-11e9-924c-f1e38c1cb56b" type="chat">
        <x xmlns="jabber:x:oob">
           <type>cmd_search_users</type>
           <action>cmd_search_users</action>
           <payload>
            {
               status: 0,
               errorCode: null,
               errorMessage: [],
               userList: ["00393296260815","00393333333333","00393490899289","00393494371802","00393497588825"]
            }
           </payload>
        </x>
        <body/>
    </message>


.. _check-version:

Check version
=============

This command used for check if client needs to upgrade itself.

**Request message:**

+-------------------------+-----------------------------------+---------------------------------------------+
| **Tag**                 | **Type**                          | **Description**                             |
+=========================+===================================+=============================================+
| x:type                  | cmd_check_client_version          |                                             |
+-------------------------+-----------------------------------+---------------------------------------------+
| x:action                | cmd_check_client_version          |                                             |
+-------------------------+-----------------------------------+---------------------------------------------+
| x:payload               | object                            |                                             |
+-------------------------+-----------------------------------+---------------------------------------------+
| payload:osCode          | string                            | Code name of operating system of the client |
+-------------------------+-----------------------------------+---------------------------------------------+
| payload:buildNumber     | int                               | Build number                                |
+-------------------------+-----------------------------------+---------------------------------------------+
| payload:apiVersion      | int                               | Server API version                          |
+-------------------------+-----------------------------------+---------------------------------------------+
| payload:packageName     | string                            | App Client package name                     |
+-------------------------+-----------------------------------+---------------------------------------------+

**Example:**

.. code-block:: xml

    <message to="xmpp_service@monksoftware.it" id="1486028547270039399072925" type="chat">
        <body />
        <x xmlns="jabber:x:oob">
            <type>cmd_check_client_version</type>
            <action>cmd_check_client_version</action>
            <payload>
            {
               status: 0,
               errorCode: null,
               errorMessage: [],
               osCode: "ANDROID",
               packageName: "it.monksoftware.eime",
               buildNumber: 141,
               apiVersion: 2
            }
            </payload>
        </x>
    </message>


**Response message:**

+---------------------------+-----------------------------------+-------------------------------------------------------------+
| **Tag**                   | **Type**                          | **Description**                                             |
+===========================+===================================+=============================================================+
| x:type                    | same as sent                      |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:action                  | same as sent                      |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:payload                 | object                            |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:status            | int                               | 0 => OK; -1 => need to upgrade; 1 => recommended to upgrade |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorCode         | string                            | Response error code or null                                 |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorMessage      | array of object                   | Each object has two elements, keys below                    |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| errorMessage:message      | string                            | Text of message                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| errorMessage:downloadLink | string                            | Link for get application updated                            |
+---------------------------+-----------------------------------+-------------------------------------------------------------+

**Example:**

.. code-block:: xml

    <message from=liam#webmonks.it@monksoftware.it' to='brischetto#webmonks.it' id='148577261002200393929210907da30f' type='chat'>
        <body />
        <x xmlns='jabber:x:oob'>
          <type>cmd_check_client_version</type>
          <action>cmd_check_client_version</action>
         
          <payload>
            {
              "status": -1,
              "errorCode": null,
              "errorMessage": [
                {
                  "message": "Unaccepted version of client",
                  "downloadLink": "http://liam.monksoftware.it/current.apk"
                }
              ]
            }
          </payload>
        </x>
    </message>


Channels
========

Following, the commands that can be used to manage subscription to channels.

**Fetch Channel List**

Using this command you can fetch the channel list for your domain.

+-------------------------+-----------------------------------+---------------------------------------------+
| **Tag**                 | **Type**                          | **Description**                             |
+=========================+===================================+=============================================+
| x:type                  | cmd_get_channels                  |                                             |
+-------------------------+-----------------------------------+---------------------------------------------+
| x:action                | cmd_get_channels                  |                                             |
+-------------------------+-----------------------------------+---------------------------------------------+
| x:payload               | object                            | Send empty {} to fetch available channels,  |
|                         |                                   | or add "onlySubscribed: true" to fetch      |
|                         |                                   | just channels you're subscribed to          |  
+-------------------------+-----------------------------------+---------------------------------------------+

**Example:**

.. code-block:: xml

    <message to="xmpp_service@ciaoamici" id="1486028547270039399072925" type="chat">
        <body />
        <x xmlns="jabber:x:oob">
            <type>cmd_get_channels</type>
            <action>cmd_get_channels</action>
            <payload>{
                onlySubscribed: true
            }</payload>
        </x>
    </message>


**Response message:**

+---------------------------+-----------------------------------+-------------------------------------------------------------+
| **Tag**                   | **Type**                          | **Description**                                             |
+===========================+===================================+=============================================================+
| x:type                    | same as sent                      |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:action                  | same as sent                      |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:payload                 | object                            |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:status            | int                               | 0 => OK; other => ERROR                                     |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorCode         | string                            | SQL_ERROR|NO_USER_FOUND|NO_CHANNEL_FOUND                    |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorMessage      | array of objects                  | Each object has one element, with message key               |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| errorMessage:message      | string                            | Text of message                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload: channelList      | list of string                    | list of channel name                                        |
+---------------------------+-----------------------------------+-------------------------------------------------------------+




**Example:**

.. code-block:: xml

    <message to='jabberId@DOMAIN' id='987654321' type='chat'>
        <x xmlns='jabber:x:oob'>
            <type>cmd_get_channels</type>
            <action>cmd_get_channels</action>
            <payload>{
                status: 0,
                errorCode: null,
                errorMessage: [],
                channelList: [
                        "channel1",
                        "channel2"
               ]
          }</payload>
        </x>
        <request xmlns='urn:xmpp:receipts'/>
    </message>






**Subscribe to channel**

Use this command to subscribe to a channel

+-------------------------+-----------------------------------+---------------------------------------------+
| **Tag**                 | **Type**                          | **Description**                             |
+=========================+===================================+=============================================+
| x:type                  | cmd_subscribe_to_channel          |                                             |
+-------------------------+-----------------------------------+---------------------------------------------+
| x:action                | cmd_subscribe_to_channel          |                                             |
+-------------------------+-----------------------------------+---------------------------------------------+
| x:payload               | object                            |                                             |
+-------------------------+-----------------------------------+---------------------------------------------+
| payload:channel         | string                            | value: name fetched from above request      |
+-------------------------+-----------------------------------+---------------------------------------------+


**Example:**

.. code-block:: xml

    <message to='xmpp_service@DOMAIN' id='123456789' type='chat'>
        <x xmlns='jabber:x:oob'>
            <type>cmd_subscribe_to_channel</type>
            <action>cmd_subscribe_to_channel</action>
            <payload>{
                "channel": "channel1"
            }</payload>
        </x>
        <request xmlns='urn:xmpp:receipts'/>
    </message>


**Response message:**

+---------------------------+-----------------------------------+-------------------------------------------------------------+
| **Tag**                   | **Type**                          | **Description**                                             |
+===========================+===================================+=============================================================+
| x:type                    | same as sent                      |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:action                  | same as sent                      |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:payload                 | object                            |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:status            | int                               | 0 => OK; other => ERROR                                     |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorCode         | string                            | SQL_ERROR|NO_USER_FOUND|NO_CHANNEL_FOUND                    |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorMessage      | array of objects                  | Each object has one element, with message key               |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| errorMessage:message      | string                            | Text of message                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+




*Example:*

.. code-block :: xml

    <message to='jabberId@DOMAIN' id='987654321' type='chat'>
        <x xmlns='jabber:x:oob'>
            <type>cmd_subscribe_to_channel</type>
            <action>cmd_subscribe_to_channel</action>
            <payload>{
                status: 0,
                errorCode: null,
                errorMessage: []
            }</payload>
        </x>
        <request xmlns='urn:xmpp:receipts'/>
    </message>


**Unsubscribe to channel**

Use this command to unsubscribe from a given channel id.

+-------------------------+-----------------------------------+----------------------------------------------+
| **Tag**                 | **Type**                          | **Description**                              |
+=========================+===================================+==============================================+
| x:type                  | cmd_unsubscribe_to_channel        |                                              |
+-------------------------+-----------------------------------+----------------------------------------------+
| x:action                | cmd_unsubscribe_to_channel        |                                              |
+-------------------------+-----------------------------------+----------------------------------------------+
| x:payload               | object                            |                                              |
+-------------------------+-----------------------------------+----------------------------------------------+
| payload:channel         | string                            | value: name fetched from subscribed channels |
+-------------------------+-----------------------------------+----------------------------------------------+


**Example:**

.. code-block:: xml

    <message to='xmpp_service@DOMAIN' id='123456789' type='chat'>
        <x xmlns='jabber:x:oob'>
            <type>cmd_unsubscribe_to_channel</type>
            <action>cmd_unsubscribe_to_channel</action>
            <payload>{
                "channel": "channel1"
            }</payload>
        </x>
        <request xmlns='urn:xmpp:receipts'/>
    </message>


**Response message:**

+---------------------------+-----------------------------------+-------------------------------------------------------------+
| **Tag**                   | **Type**                          | **Description**                                             |
+===========================+===================================+=============================================================+
| x:type                    | same as sent                      |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:action                  | same as sent                      |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| x:payload                 | object                            |                                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:status            | int                               | 0 => OK; other => ERROR                                     |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorCode         | string                            | SQL_ERROR|NO_USER_FOUND|NO_CHANNEL_FOUND                    |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| payload:errorMessage      | array of objects                  | Each object has one element, with message key               |
+---------------------------+-----------------------------------+-------------------------------------------------------------+
| errorMessage:message      | string                            | Text of message                                             |
+---------------------------+-----------------------------------+-------------------------------------------------------------+




**Example:**

.. code-block:: xml

    <message to='jabberId@DOMAIN' id='987654321' type='chat'>
        <x xmlns='jabber:x:oob'>
            <type>cmd_unsubscribe_to_channel/type>
            <action>cmd_unsubscribe_to_channel</action>
            <payload>{
                status: 0,
                errorCode: null,
                errorMessage: []
            }</payload>
        </x>
        <request xmlns='urn:xmpp:receipts'/>
    </message>