Automated alert escalation
You may wish to call someone if they’ve not responded to an SMS or email within a certain number of days, hours or minutes or you may wish to send them an SMS if they’ve not responded to an email within a week. Such scenarios are known as escalation and Alerting Hub can assist with this using the concept of ‘linked alerts’. Escalation and linked alerts allow you to filter who receives future alerts based on their responses to previous alerts.
As escalation needs to be able to match different methods of contacting a person (e.g. their telephone number and email address) linked alerts can only be used in conjunction with contact-groups. The 1st alert in a set of linked alerts must contain a contact-group (either an inline one or a stored one) all subsequent linked-alerts use the contact-group from the 1st alert.
Links between alerts are specified using a linkedAlerts JSON object within each /sendalert, such as:
"linkedAlerts": {
"linkRef": "a-unique-reference",
"lifetime": "300d",
"linkOnlyIfRefAlreadyExists": false
}
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| linkRef | Mandatory | None | A unique reference to use between linked alerts. All alerts with the same reference will be considered linked together. Can consist of a-z, A-Z, 0-9, -, + and _ characters. |
| lifetime | Optional | System default | Lifetime of the linking between alerts. Only relevant if 1st alert. Lifetime is specified as {n}{M|w|d|h|m|s} where M = months, w = weeks, d = days, h = hours and s = seconds. |
| linkOnlyIfRefAlreadyExists | Optional | false | If this is set to true then the linkRef must already be on the system otherwise the sending of this alert will fail. If false then if the linkRef isn't already on the system this alert will become the 1st (master) alert in the linked set; this is the usual method for starting a set of linked alerts. |
| cancelCancellation | Optional | false | If this is set to true then if a previous set of linked alerts had been cancelled, this will ensure the cancellation was then removed so the new set of linked alerts could use the same linkRef. |
Once you’ve created linked alerts using a common linkRef value, you must then, for each linked alert you wish to use escalation on, tell each alert element what to do based on what has happened in previous alerts. Currently, escalation uses responses (email replies, SMS replies, shortlink clicks and voice call digit pressing) to ascertain what to do on the next alert.
To enable escalation on a linked alert you must specify a ‘linkedAlertModifiers” JSON object. This is at the level of each alert item (sms, email or call) so escalation can be fine-grained across numerous alert items within a single alert. An example of this is:
"linkedAlertModifiers": {
"except": {
"previouslySeen": "sms,email,shortlink"
}
}
| Parameter | Requirement | Default | Description | |
|---|---|---|---|---|
| except | Optional | None | JSON object describing possible exception conditions. | |
| previouslySeen | Optional | None | Specifies a list of types of alert. If a contact has previously responded to any of the types listed then they will not be contacted during this alert. The list should be comma delimited from the following available types: sms, email, call and shortlink. |
Please note that specifying other forms of receivers (such as recipient lists) is still allowed within a linked alert but the escalation process will not apply to them; they will be contacted regardless of what has happened in previous linked alerts.
Escalation example
SMS/Email to voice
This example shows two linked-alerts, the 1st uses a stored contact group to send to a number of SMS and emails (in fact using a contact-set), the 2nd, scheduled for 1 hour later then calls any of the original contact-set who did not respond to the SMS or email (either via a direct reply or by the clicking on the embedded shortlink). Note that this example would be a perfect fit for using the /sendalerts API wherein both the 1st and 2nd alert could be specified in a single API call.
First alert
{
"version" : "latest",
"apiKey" : "abcdefghijklmnopqrstuvwxyz",
"clientRef" : "my-reference",
"contactGroup" : {
"storedContactGroup" : "e42b1fd0-70fc-4697-b646-9f0fab7306d0"
},
"linkedAlerts": {
"linkRef": "sms-then-call"
},
"alert" : [
{
"alertType" : "sms",
"tag" : "tag1",
"contactSets" : [ "all" ],
"content" : "A message for {firstname} {lastname}. Click {shortlink} to let us know you've seen this.",
"contentEncoding" : "utf8",
"sender" : "My Company",
"lookups": {
"performLookups": true,
"shortlink": {
"reference": "a-reference",
"url": "https://my-companies-url.com/alertinghub-click-through"
}
}
},
{
"alertType": "email",
"tag": "t2",
"to": "All staff",
"sender": "ACME Trading",
"replyTo": "ACME Trading",
"subject": "Important message",
"contactSets" : [ "all" ],
"content": "An email for {firstname} {lastname}. Click {shortlink} to let us know you've seen this.\n",
"contentEncoding": "utf8",
"lookups": {
"performLookups": true,
"shortlink": {
"reference": "a-reference",
"url": "https://my-companies-url.com/alertinghub-click-through"
}
}
}
]
}
Second alert
{
"version" : "latest",
"apiKey" : "abcdefghijklmnopqrstuvwxyz",
"clientRef" : "my-reference",
"linkedAlerts": {
"linkRef": "sms-then-call"
},
"alert" : [
{
"alertType": "call",
"sender": "+447777100100",
"options": {
"schedule": {
"start": "now",
"delay": "1h"
}
},
"linkedAlertModifiers": {
"except": {
"previouslySeen": "sms,email,shortlink"
}
},
"contactSets" : [ "all" ],
"tag": "t1",
"voiceFormat": "tts",
"content": "Hello, this is a message for {firstname} {lastname}. Please press any key and then hangup. Thank you.",
"contentEncoding": "utf8",
"ivrControl":
"ivrRequireResponse": true,
"ivrAttempts" : 3
},
"lookups": {
"performLookups": true,
"uniqueLookups": true
}
}
]
}