.. _messagesets:

Building Message Sets
=====================

Care Messenger can be used to send message sets consisting of one or more messages.  A basic message set would consist of.

`name`
    An optional name for the message set.  This can be useful to identify message sets containing multiple messages, such as a Wellbeing questionnaire or survey.  If not specified, this will be set internally to the subject of the first message in the set.

`description`
    An optional description for the message set

`tag`
    An optional field that can be used for a unique identifier to tie a message set to an external system.

`site`
    The is the id of the site at which the intended recipients reside

`messages`
    An array of the messages to be delivered.  see `Message Options`_ for details.

`recipients`
    An array of the intended recipient id's

`force_urgent`
    A boolean flag that can be used to override a recipients display preference.  Defaults to ``false``.  If ``force_urgent`` is set to ``true`` the message will be displayed immediately on screen when it is delivered, regardless of the recipents preference in their profile.  This can be useful for ensure important communications are seen and responded to in a timely fashion.

Examples
--------

Message Set Containing One Message
**********************************

.. sourcecode:: javascript

    {
        "site": 3,
        "messages": [
            {
                "subject": "Community Nurse Visit",
                "body": "Your nurse will be visiting today at 3pm"
                "choices": [
                    {"choice_text": "OK"}
                ]
            }
        ],
        "recipients": [2, 5, 7, 32],
        "force_urgent": false
    }


Message Set With Multiple Messages
**********************************

.. sourcecode:: javascript

    {
        "name": "Wellbeing Survey",
        "tag": "WELL-12"
        "site": 3,
        "messages": [
            {
                subject: "",
                body: "Have you had any pain this week? (other than usual pain such as toothache or headache)",
                "choices": [
                    {choice_text: "None"},
                    {choice_text: "Mild"},
                    {choice_text: "Moderate"},
                    {choice_text: "Severe"},
                    {choice_text: "Very Severe"}
                ]
            },
            {
                subject: "",
                body: "How much does your pain interfere with your daily activities? (including sleeping)",
                choices: [
                    {choice_text: "Not at all"},
                    {choice_text: "Slightly"},
                    {choice_text: "Moderate"},
                    {choice_text: "Severe"},
                    {choice_text: "Very Severe"}
                ]
            },
            {
                subject: "",
                body: "Over the last week, how often have you been bothered by feeling nervous or on edge?",
                choices: [
                    {choice_text: "Not at all"},
                    {choice_text: "Several days"},
                    {choice_text: "More than half the days"},
                    {choice_text: "Nearly every day"}
                ]
            }
        ],
        "recipients": [2, 5, 7, 32],
        "force_urgent": true // display immediately by overriding recipients display preference
    }


.. _message_options:

Message Options
---------------

The ``messages`` attribute with in a message set consists of an array or message objects.  Message objects can be created using the following parameters.

`subject`
    An optional subject

`body`
    The body of the message

`body_type`
    ``text`` or ``html``.  Defaults to ``text`` if not set.

`tag`
    An optional field that can be used for a unique identifier to tie a message to an external system.

`choices`
    An array of possible choices to be displayed, maximum of 5.  See `Message Choice Options`_ for details.

`images`
    An array of images to be attached to the message, unlimited per message

`videos`
    An array of videos to be attached to the message, maximum 1 per message


.. note::

    A message can currently attach images OR video, not both on the same message.


.. sourcecode:: javascript

    {
        "subject": "Medication Reminder",
        "body": "Have you taken your medication today",
        "choices": [
            {"choice_text": "Yes"},
            {"choice_text": "No"}
        ],
        "images": [45, 12]
    }



.. _message_choice_options:

Message Choice Options
----------------------

The ``choices`` attribute on a message can be made up of the following attributes

``choice_text``
    The label to be displayed on choice

``tag``
    An optional field that can be used for a unique identifier to tie a message choice to an external system.


.. sourcecode:: javascript

    {
        "choice_text": "OK",
        "tag": "choice_a"
    }



Sending a Message Set
=====================

Before constructing a message set, you will want to query the API to first obtain a list of all the sites that are currently configured for your orgainsiation.  Once you have this, you can then query the API to obtain a list of residents (potential recipients) at a given site.

Once we have a site and a list of potential recipients, we can move on to construct and send a simple message set.

Javascript Example
------------------

This example uses the restful.js library to simplify interacting with the API.  This is a simple REST client library for javascript.

You can download it directly from here

.. sourcecode:: shell

    https://github.com/marmelab/restful.js/archive/master.zip


or it can also be installed using `bower <http://bower.io>`_ if you have it installed.

.. note::

    Bower is a package manager for web dependencies.  It can be installed via npm, the nodejs package manager.
    For more information on installing node on your operating system see `installing nodejs and npm <https://github.com/joyent/node/wiki/Installation>`_

    Once you have npm installed, you can install bower and restful.js as follows

    .. sourcecode:: shell

        $ npm intall -g bower
        $ bower install restful.js --save


With the dependencies in place we could use the following code to send a message set.


.. sourcecode:: html

    <!DOCTYPE html>
    <html>
        <head>
            <script src="bower_components/restful.js/dist/restful.min.js"></script>
            <script>
                var API_TOKEN = 'YOUR_API_TOKEN_HERE';

                var api = restful('api.caremessenger.co.uk')
                    .header('Authorization', 'Bearer ' + API_TOKEN)
                    .prefixUrl('v2')
                    .protocol('https'); // resource now targets https://api.caremessenger.co.uk/v2

                    // send a HTTP GET request to retreive all available sites
                    var siteCollection = api.all('site'); // https://api.caremessenger.co.uk/v2/site
                    siteCollection.getAll().then(function(siteResponse){

                        // grab the array of sites
                        var sites = siteResponse.body().data().results;

                        // Output each site to the console
                        sites.forEach(function(site){
                            console.log('SITE: ' + site.id + ', ' + site.name);
                        });

                        /*
                        * Get an array of all the residents present at a given site.
                        * for the sake of simplicity, here we will use the first site returned.
                        */

                        // send a HTTP GET request to retreive all residents at the site
                        var residentCollection = api.all('resident?site=' + sites[0].id); // https://api.caremessenger.co.uk/v2/resident?site=1
                        residentCollection.getAll().then(function(residentResponse){

                            // grab the array of residents at this site
                            var residents = residentResponse.body().data().results;

                            /*
                            * Constuct and POST a simple message set,
                            * This represents the simplest message set we can send,
                            * 1 message, with 1 response choice, to 1 recipient
                            */

                            var messageSet = {
                                site: sites[0].id,  // the first site returned
                                recipients: [residents[0].id], // the first resident returned at the site
                                messages: [
                                    {
                                        subject: 'Wellbeing',  // Subject is not required
                                        body: 'Running late, see you at 7:30',
                                        choices: [
                                            {choice_text: 'OK'},
                                        ]
                                    }
                                ]
                            };

                            // send a HTTP POST request to create the message set.
                            var messageSetCollection = api.all('message-set'); // https://api.caremessenger.co.uk/v2/message-set
                            messageSetCollection.post(messageSet).then(function(messageSetResponse){
                                console.log('messageSetResponse: ', messageSetResponse.body());
                            }, function(messageSetResponse) {
                                // Error POSTing message set
                            });

                        }, function(){
                            // Error getting residents
                        });
                    }, function(residentResponse){
                        // Error getting sites
                    });
            </script>
        </head>
        <body>

        </body>
    </html>


Revoking a Message Set
======================

A Message Set can be revoked for an individual recipient by sending a ``PUT`` or ``PATCH`` request with an empty payload to the detail Message Recipient endpoint.

.. sourcecode:: bash

    https://api.caremessenger.co.uk/v2/message-recipient/<message_recipient_id>/revoke


If the MessageRecipient status is currently ``pending``, ``unread`` or ``delivered``, the staus will be updated to ``revoked`` and a ``HTTP_200_OK`` response will be returned.

If the recipient is online at the time of the revocation being requested, the message set will be removed from their unread message queue.
If they are offline at the time of the revocation the message set will no longer be delivered when they next come back online.

If the MessageRecipient status is currently ``read``, ``expired`` or ``revoked`` at the time of the revocation request no action will be taken and a ``HTTP_400_BAD_REQUEST`` response will be returned.


Escalating a Message Set Over IVR (Interactive Voice Response)
==============================================================

Escalation can be used in scenarios where a given recipient hasn't responded to a message set on their Set Top Box.  When a message set is escalated a telephone call will be placed to the user, wherein the message set
will be read to them, along with the associated choices.  If the recipient makes a suitable response, this will be recorded and the ``MessageRecipient`` status moved to ``READ``.  If the message set had previously been delivered to
the recipients Set Top Box, it will also be removed from the unread message queue.

.. note::

    For escalation to be successful the intended recipient must have at least one phone number registered in their contact record.


A ``MessageSet`` can be escalated for an individual recipient by sending a ``PUT`` or ``PATCH`` request with an empty payload to the detail ``MessageRecipient`` endpoint.

.. sourcecode:: bash

    https://api.caremessenger.co.uk/v2/message-recipient/<message_recipient_id>/escalate


If the ``MessageRecipient`` status is currently ``pending``, ``unread`` or ``delivered``, a successful escalation will return a  ``HTTP_200_OK`` response, no status change in currently made to indicate that the message set has been escalated.

If the ``MessageRecipient`` status is currently ``read``, ``expired`` or ``revoked`` at the time of the escalation request no action will be taken and a ``HTTP_400_BAD_REQUEST`` response will be returned.


Scheduling a Message Set
========================

A Message Set can be scheduled for delivery at a later point in time.  The schedule can be for one time delivery or recurring on a specified frequency.

A scheduled message set can be made up of

One Time Delivery
-----------------

`name`
    An optional name for the message set

`description`
    An optional description for the message set

`tag`
    An optional field that integrators can use for a unique identifier to tie a message set to an external system.

`site`
    The is of the site at which the intended recipients reside

`messages`
    A list of the messages to be delivered

`recipients`
    A list of the intended recipient id's

`force_urgent`
    A boolean flag that can be used to override a recipients display preference. Defaults to ``false``.  If ``force_urgent`` is set to ``true`` the message will be displayed immediately on screen when it is delivered, regardless of the recipents preference in their profile.  This can be useful for ensure important communications are seen and responded to in a timely fashion.

`start`
    The date and time at which the message should be delivered, in ISO8601 format. e.g.

    .. sourcecode:: shell

        2014-06-30T10:04:40.938Z


    This must be at least 3 minutes in the future from the point of scheduling.

Recurring Delivery
------------------

Optionally, if you would like to schedule the messageset for recurring delivery, two extra fields should be included.

`rule`
    The id of the rule used to specify the frequency with which the message set should be delivered.  These rules can be retreived by querying the ``scheduled-message-set-rule`` resource.  Currently available rules are DAILY, MINUTELY, HOURLY, WEEKLY, MONTHLY, YEARLY.

`end_recurring`
    The date and time at which the rcurring period should end, in ISO8601 format.



One Time Delivery Example
-------------------------

This example shows how to go about creating a scheduled message set for one time delivery.  The example consists of a message set containing 1 message to be sent to 2 reciepients, delivery would be delayed for 1 hour from the time of sending.


.. sourcecode:: html

    <!DOCTYPE html>
    <html>
        <head>
            <script src="bower_components/restful.js/dist/restful.min.js"></script>
            <script>
                var API_TOKEN = 'YOUR_API_KEY_HERE';

                var api = restful('api.caremessenger.co.uk')
                    .header('Authorization', 'Bearer ' + API_TOKEN)
                    .prefixUrl('v2')
                    .protocol('https'); // resource now targets https://api.caremessenger.co.uk/v2

                    // send a HTTP GET request to retreive all available sites
                    var siteCollection = api.all('site'); // https://api.caremessenger.co.uk/v2/site
                    siteCollection.getAll().then(function(siteResponse){

                        // grab the array of sites
                        var sites = siteResponse.body().data().results;

                        /*
                        * Get an array of all the residents present at a given site.
                        * for the sake of simplicity, here we will use the first site returned.
                        */

                        // send a HTTP GET request to retreive all residents at the site
                        var residentCollection = api.all('resident?site=' + sites[0].id); // https://api.caremessenger.co.uk/v2/resident?site=1
                        residentCollection.getAll().then(function(residentResponse){

                            // grab the array of residents at this site
                            var residents = residentResponse.body().data().results;

                            /*
                            * Constuct a one time scheduled message set,
                            * This will consist of 1 message, to 2 recipients and
                            *  will be delivered in 1 hour
                            */

                            var oneTimeStart = new Date();
                            oneTimeStart.setHours(oneTimeStart.getHours() + 1);  // Add 1 hour

                            var oneTimeMessageSet = {
                                site: sites[0].id,  // the first site returned
                                recipients: [residents[0].id, residents[1].id], // just using the first 2 residents returned
                                messages: [
                                    {
                                        subject: 'Bingo Tonight',
                                        body: 'Bingo tonight in the lounge, starting 7:30pm',
                                        choices: [
                                            {choice_text: 'Count me in'},
                                            {choice_text: 'Not tonight'}
                                        ]
                                    }
                                ],
                                start: oneTimeStart.toISOString() // one hour from now
                            };

                            // send a HTTP POST request to create the one time scheduled message set.
                            var oneTimeMessageSetCollection = api.all('scheduled-message-set'); // https://api.caremessenger.co.uk/v2/scheduled-message-set
                            oneTimeMessageSetCollection.post(oneTimeMessageSet).then(function(messageSetResponse){
                                console.log('messageSetResponse: ', messageSetResponse.body());
                            }, function(messageSetResponse) {
                                // Error POSTing one time scheduled message set
                            });

                        }, function(){
                            // Error getting residents
                        });
                    }, function(residentResponse){
                        // Error getting sites
                    });
            </script>
        </head>
        <body>

        </body>
    </html>



Recurring Delivery Example
--------------------------

This example shows how to go about scheduling a message set, where message occurences will be scheduled over time.

In this example we construct a message set containing 2 messages, to be sent to 1 recipient.  The message set is set to send it's first occurrence in 30 minutes from the time of scheduling, then repeat daily for the next 7 days.


.. sourcecode:: html

    <!DOCTYPE html>
    <html>
        <head>
            <script src="bower_components/restful.js/dist/restful.min.js"></script>
            <script>
                var API_TOKEN = 'YOUR_API_KEY_HERE';

                var api = restful('api.caremessenger.co.uk')
                    .header('Authorization', 'Bearer ' + API_TOKEN)
                    .prefixUrl('v2')
                    .protocol('https'); // resource now targets https://api.caremessenger.co.uk/v2

                    // send a HTTP GET request to retreive all available sites
                    var siteCollection = api.all('site'); // https://api.caremessenger.co.uk/v2/site
                    siteCollection.getAll().then(function(siteResponse){

                        // grab the array of sites
                        var sites = siteResponse.body().data().results;

                        /*
                        * Get an array of all the residents present at a given site.
                        * for the sake of simplicity, here we will use the first site returned.
                        */

                        // send a HTTP GET request to retreive all residents at the site
                        var residentCollection = api.all('resident?site=' + sites[0].id); // https://api.caremessenger.co.uk/v2/resident?site=1
                        residentCollection.getAll().then(function(residentResponse){

                            // grab the array of residents at this site
                            var residents = residentResponse.body().data().results;

                            // send a HTTP GET request to retreive all recursion rules
                            var ruleCollection = api.all('scheduled-message-set-rule'); // https://api.caremessenger.co.uk/v2/scheduled-message-set-rule
                            ruleCollection.getAll().then(function(ruleResponse){

                                // grab the array of rules
                                var rules = ruleResponse.body().data().results,
                                    daily;

                                // Grab the daily recursion rule
                                daily = rules.find(function(element, index){
                                    return element.frequency == 'DAILY';
                                });

                                /*
                                * Constuct a recurring scheduled message set,
                                * This will consist of 2 messages, to 1 recipient and
                                * will be delivered in 30 mins time, recurring every day for
                                * the next 7 days.
                                */

                                var start = new Date(),
                                    endRecurring;

                                start.setMinutes(start.getMinutes() + 30); // Add 30 mins
                                endRecurring = new Date(start.getTime());
                                endRecurring.setDate(endRecurring.getDate() + 7); // add 7 days

                                var recurringMessageSet = {
                                    site: sites[0].id,  // the first site returned
                                    recipients: [residents[0].id, residents[1].id], // just using the first 2 residents returned
                                    messages: [
                                        {
                                            body: 'Good Morning!',
                                            choices: [
                                                {choice_text: 'OK'}
                                            ]
                                        },
                                        {
                                            subject: 'Visit Today',
                                            body: 'Do you require a visit today?',
                                            choices: [
                                                {choice_text: 'Yes'},
                                                {choice_text: 'No'}
                                            ]
                                        }
                                    ],
                                    start: start.toISOString(),
                                    end_recurring: endRecurring.toISOString(),
                                    rule: daily.id
                                };

                                // send a HTTP POST request to create the recurring scheduled message set.
                                var recurringMessageSetCollection = api.all('scheduled-message-set'); // https://api.caremessenger.co.uk/v2/scheduled-message-set
                                recurringMessageSetCollection.post(recurringMessageSet).then(function(messageSetResponse){
                                    console.log('messageSetResponse: ', messageSetResponse.body());
                                }, function(postFailure) {
                                    // Error POSTing recurring scheduled message set
                                    console.log(postFailure.status) // the HTTP return code e.g. 400
                                    console.log(postFailure.statusText) // text status e.g. BAD_REQUEST
                                    console.log(postFailure.data) // an object detailing which field was at fault
                                });

                            }, function(ruleFailure) {
                                // Error getting recursion rules
                            });
                        }, function(){
                            // Error getting residents
                        });
                    }, function(residentResponse){
                        // Error getting sites
                    });
            </script>
        </head>
        <body>

        </body>
    </html>


Deleting a Scheduled Message Set
--------------------------------

To delete a scheduled message set we can send a ``DELETE`` request to the instance's list end point.

.. sourcecode:: bash

    https://api.caremessenger.co.uk/v2/scheduled-message-set/:id


If the start date is still in the future, the scheduled message set will be deleted and no messages will be sent.

If the start date is in the past and this is a one time scheduled message set, the scheduled message set will be deleted but messages it generated will not be deleted.

If this is a recurring scheduled message set, any message occurrences it generated to date will not be deleted, any messages that would have been created before it's recurring end date will no longer be sent.