===================================
Legacy Push Notifications over HTTP
===================================

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

.. warning::

    This document describes the legacy HTTP push gateway.  It will be available for the forseeable future but we recommend you use the new :doc:`HTTP Push Gateway<http_push>`

Overview
========

The HTTP gateway for pushes allows you to send Push Notifications directly. It accepts POST requests and formats a
message that is then transferred to Acrobits's Push Notification Mediator Service and then to the device.

Accessing
=========

The address of the gateway is ``https://pnm.cloudsoftphone.com/pnm2``. It accepts only HTTP POST requests and
expects ``application/x-www-form-urlencoded`` body type. In the POST requests it accepts the following parameters.

Parameters Description
======================

Required parameters
-------------------

Required parameters are ``verb``, ``AppId``, ``DeviceToken``. Leaving any of these parameters out will produce a
HTTP 400 error.

``verb``
    Type of the message. The most important one is ``NotifyTextMessage`` and ``NotifyGenericTextMessage``.
    See `Message Types and additional parameters`_ for more information.

``AppId``
    Application ID. This parameter is required

``DeviceToken``
    Identifies the device that will receive the Push. This parameter is required.

You can find DeviceToken in your SIPIS :doc:`database<../../sipis/database>` or you can get it
from :doc:`Push Token Reporter<../client/push_token_reporter>`.

.. note::

    You need to properly urlencode the values.  For example if your DeviceToken contains plus (``+``) you need to replace it with ``%2B``.

Message Types and additional parameters
=======================================

``NotifyTextMessage``

    This message type is used to notify user about incoming messages. It notifies the app that there are new
    messages available for fetching using the :ref:`fetch_messages_webservice`. When the app receives this type of push
    message, it runs the fetch web service in the background and when the new messages are fetched, the notification
    about them is presented to user.

    .. note::

        This verb needs additional parameter ``Selector`` which identifies the user's account. It is reported in the same way as ``DeviceToken``.

``NotifyGenericTextMessage``

    The simplest message type which is used to show a text notification to user. The app doesn't process this message in
    other way other than displaying the text on screen. This can be used for various marketing messages, reminders etc.

    The additional parameter ``Message`` contains the text to be displayed. See the example below.

``NotifyReprovision``

    This push causes the application to reprovision – reload its configuration from the portal and from external provisioning URL – immediately. No notification to the user is presented.

Examples
========

Send a simple text notification:

.. code-block:: bash

    wget https://pnm.cloudsoftphone.com/pnm2 --post-data="verb=NotifyGenericTextMessage&Message=Hello%20World&DeviceToken=QVBBOTFiSEQ0KX05PclRXZXlRdTVaNUJXT3BZVmpBMmxR&AppId=cz.acrobits.softphone.cloudphone" -O -

Send ``NotifyTextMessage`` notification to let the app know about new incoming messages:

.. code-block:: bash

    wget https://pnm.cloudsoftphone.com/pnm2 --post-data="verb=NotifyTextMessage&DeviceToken=LA7U4xm7MqZCVqFPhf4Dz2sILOJ9iVGh0eeTBOyKDRs=&Selector=C203056764290202B7DA6F61B98671616469AEDB:1DA7349B&AppId=com.cloudsoftphone.app" -O -