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. Ifforce_urgentis set totruethe 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¶
{
"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¶
{
"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¶
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
textorhtml. Defaults totextif 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.
{
"subject": "Medication Reminder",
"body": "Have you taken your medication today",
"choices": [
{"choice_text": "Yes"},
{"choice_text": "No"}
],
"images": [45, 12]
}
Message Choice Options¶
The choices attribute on a message can be made up of the following attributes
choice_textThe label to be displayed on choice
tagAn optional field that can be used for a unique identifier to tie a message choice to an external system.
{
"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
https://github.com/marmelab/restful.js/archive/master.zip
or it can also be installed using bower 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
Once you have npm installed, you can install bower and restful.js as follows
$ 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.
<!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.
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.
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. Ifforce_urgentis set totruethe 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.
2014-06-30T10:04:40.938ZThis 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-ruleresource. 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.
<!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.
<!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.
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.