.. _assistance:

Assistance Requests
===================

The assistance feature allows a resident to make an assistance request via the set top box using their remote control.  When the request is placed to a registered assistance provider, a notification will be sent via whatever notification methods have been registered.

Assistance Providers
--------------------

An assistance provider can be registered against a customer, site or resident.  This is to control visibility of the provider in the following way.

`customer`
    When registered with a ``customer`` object, visibility will be to all residents across all sites within your organisation.  This can be used to have assistance requests from all of yours users sent to one location.  This is often used for sending notifications to a company wide call centre for example.

`site`
    When registered with a ``site`` object, visibility will be to all residents within a given site.  This is often used to have notiifcations send to an individual site/scheme manager.

`resident`
    When registered with a ``resident`` object, visibility will be to just the given resident.  This is designed for use with supporter accounts.  e.g. a resident can have their friends or family listed as an assistance provider, where they will receive push notifications to their registered mobile devices.

    .. warning::

        Not yet implemented

Notification Methods
********************

When registering an assistance provider, the following notification methods can be specified.

`email`
    Requests will be sent to a registered email address

`webhook`
    Requests will be sent to a registered URL via a HTTP POST request.

`push_notification`
    Push notification to a mobile device

    .. warning::

        Not yet implemented


The image below shows an example of the assistance provider dialog that would be displayed on the set top box when 3 assistance providers have been configured.


.. image:: ./_static/request_assistance.jpg


Creating an Assistance Provider
-------------------------------


To create an assistance provider we can send a ``POST`` request to the following resource

.. sourcecode:: bash

    https://api.caremessenger.co.uk/v2/assistance-provider

with the following attributes

`name`
    A name to describe the provider

`label`
    The label that that will be displayed on the set top box to describe the provider

`content_type`
    The type of the obect you wish to assiciate this provider with, can be one of either ``customer``, ``site`` or ``resident``.

`object_id`
    The id of the object to associate the provider with

`email_notifiers`
    An array of email notifiers to be called when an assistance request is received.

`webhook_notifiers`
    An array of webhook notifiers to be called then an assitance request is received.

For example

.. sourcecode:: javascript

    {
        "name": "Acme Remote Montitoring Centre",
        "label": "Acme Support" // The label as would appear on the set top box
        "content_type": "customer",
        "object_id": 2,  // id of the customer
        "email_notifiers": [
            {
                "name": "Acme Support",
                "email": "support@acme.com"
            }
        ],
        "webhook_notifiers": [
            {
                "name": "Acme Support Assistance Requests",
                "url": "https://acme.com/webhooks/assistance-requests"
            }
        ]
    }


This would register an assitance provider at the ``customer`` level and as such, would be visible to all residents across all sites

.. sourcecode:: javascript

    {
        "name": "Acacia Avenue Site Assistance Provider",
        "label": "Duty Manager" // The label as would appear on the set top box
        "content_type": "site",
        "object_id": 5,  // id of the site
        "email_notifiers": [
            {
                "name": "Acacia Duty Manager",
                "email": "acaciamanager@acme.com"
            }
        ]
    }


This would register an assitance provider at the ``site`` level and as such, would be visible to all residents just at the Acacia Avenue site.


Response Format
---------------

After creating or updating an assitance provider, the response format will look similar to the following

.. sourcecode:: javascript

    {
      "id": 10,
      "name": "Acacia Avenue Site Assistance Provider",
      "label": "Duty Manager",
      "type": "site",
      "content_object": { // the JSON representation of the object associated with e.g. site
        "id": 5,
        "name": "Acacia Avenue",
        "slug": "acacia-avenue",
        "customer": 2,
        "created": "2013-11-08T17:00:04.734597Z",
        "modified": "2013-11-08T17:00:04.737940Z",
        "lat": null,
        "lon": null,
        "is_active": true,
        "calendar": 1
      },
      "email_notifiers": [
        {
          "id": 7,
          "name": "Acacia Duty Manager",
          "email": "acaciamanager@acme.com"
        }
      ]
    }


Email Notifier Attributes
-------------------------

`name`
    The display name for this notifier

`email`
    The email address where assitance requests will be sent to


Webhook Notifier Attributes
---------------------------

`name`
    The display name for this notifier

`url`
    The url where you would like to receive notifications via HTTP POST.


Once a webhook is in place, when a notification request is received, a HTTP POST will be made to the URL specified.  If your server successfully receives this POST, it should respond with a ``200`` or ``201`` response code.  If you do not respond the webhook will be retried with exponential backoff for the next 5 minutes.  If no respone has been received within that period, retries will be stopped.  Currently no further escalation will occur.