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