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.

Creating an Assistance Provider¶

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

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

{
    "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

{
    "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

{
  "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.