SEND BULK NOTIFICATIONS WITH
ALERTING HUB API
Voice, SMS, Email
Education
Send parent notifications to entire schools or year groups from snow days and school trips to safeguarding incidents
SEND BULK NOTIFICATIONS WITH
Send bulk notifications – voice, sms, email
Alerting Hub is tailored to the needs of mass outbound notification solutions; where you can send bulk notifications, to multiple recipients with Alerting Hub’s single ‘one-shot’ API call. That’s bulk SMS, voice and email notifications all from a single request to the Alerting Hub platform. For Alerting Hub, this wasn’t an ‘add on’ feature – it was an integral part of the initial design specification. What’s more Alerting Hub can also handle all the notifications and replies to those messages and collate them under a single reference; allowing you to track who has received which notifications and who has replied.
What are the use cases?
The need to send bulk notifications and alerts to multiple recipients is common across many different scenarios. Whilst the objectives may differ greatly from situation to situation the ability to contact people in a timely, robust and simple manner is a universal requirement; this is where Alerting Hub can help. This post provides a guide on sending bulk notifications using the Alerting Hub SendAlert API.
Crisis
Notify public and community groups when an incident occurs. Ensure everyone gets the message in time.
Business
Make sure employees always have up-to-date information – whether at home, in the office or out in the field.
Utilities
Notify and update subscribers on power outages, water supply and disruption to service issues in their area
Events
Send event reminders, instructions and agendas to enhance the attendee experience
Recipients
At the heart of a bulk mass notification solution is the recipient list. Alerting Hub has the flexibility to utilise both dynamic lists or stored lists. Dynamic lists are those where the likelihood of recipient numbers and details changing is high. Whereas stored lists are unlikely to change, and so used again and again. In addition, when raising an alert with Alerting Hub, different recipient lists can be specified for each part of the alert; so you can have a dynamic list for an SMS broadcast, another dynamic list for an email broadcast and a stored list a set of voice calls. What’s more, you can actually have multiple different SMS messages, emails and voice calls all occurring with their own recipient lists, all within the same single alert.
Dynamic lists
When sending an alert you can provide a formatted list of recipients for each alert item (SMS/email/voice-call). You could, for instance, pull recipients from your CRM, custom database or spreadsheet to populate the recipient list at the time of sending the alert.
Stored lists
There will be occasions when the recipient list for an alerting event will be known in advance and may be reused regularly. Alerting Hub allows you to store predefined lists of recipients and to use them at will during the sending of alerts. This data, as with all customer data on AlertingHub, is encrypted at rest, automatically destroyed unless used within a customisable time period and locked to your API key. What’s more, should your recipient list change, you can update the stored lists held by Alerting Hub at any time; thus keeping the stored lists in-sync with your latest data.
Sending a bulk alert – an example
In the following example, we’ll look at using a single invocation of Alerting Hub’s sendalert API to send a “School’s closed due to snow” alert. The alert will notify parents of the school closure via SMS and, at the same time, notify the teaching staff of the same event via SMS, email and voice-call (the latter using Alerting Hub’s text-to-speech capability). All recipients will be specified using dynamic lists within the API call data itself.
What to send to the sendalert API
The following snippet shows the JSON formatted data that could be sent to initiate the example alert. As you can see, it’s pretty straight forward to contact groups of people and to send them different types of messages with varying content.
{
"version" : "latest",
"apiKey" : "abcdefghijklmnopqrstuvwxyz",
"clientRef" : "snowalert",
"alert" : [
{
"alertType" : "sms",
"tag" : "parent_sms",
"recipientList" : "+447777100100,+447777100101,+447777100102,+447777100103,+447777100104",
"content" : "Due to snow the school will be closed today, for any queries please contact 07777200000",
"contentEncoding" : "utf8",
"sender" : "SNOW ALERT"
},
{
"alertType" : "sms",
"tag" : "teacher_sms",
"recipientList" : "+447777200100,+447777200101,+447777200102",
"content" : "The school is closed today, parents have been informed, please contact the Head for further information",
"contentEncoding" : "utf8",
"sender" : "SNOW ALERT"
},
{
"alertType" : "email",
"tag" : "teacher_email",
"to": "All staff",
"sender" : "Snow Alert",
"subject": "Important - school is closed today",
"recipientList" : "teacher1@school.com,teacher2@school.com,teacher3@school.com",
"content" : "The school is closed today, parents have been informed, please contact the head for further information. Please reply to this email when you receive it.",
"contentEncoding" : "utf8"
},
{
"alertType" : "call",
"tag" : "teacher_call",
"recipientList" : "+447777200100,+447777200101,+447777200102,+441603111222",
"sender" : "+447777200000",
"voiceFormat": "tts",
"content": "This is an important school announcement. The school is closed today, I repeat the school is closed. Please press any key to acknowledge you have heard this message and then hangup. Thank you.",
"contentEncoding": "utf8",
"ivrControl": {
"ivrRequireResponse": true,
"ivrAttempts" : 3
}
}
]
}
All you need to do now is get the above data to us, we’ll do the rest. You can do that either by a secure web transaction, which is the conventional route or we even let you send us the data via email, where it will be automatically received and processed. See the API guide for more details on these methods.
And that’s it – you’ve sent a bulk notification with two different SMS messages, an email and a voice call (using text-to-speech so no need to encode audio files) all sent to different sets of recipients and all from the same, single, sendalert API call.
If you’re just interested in sending bulk notifications without worrying about responses, or you’ve seen enough technical detail for today then there’s no need to read on; thanks for taking the time to look at this post, hopefully it’s been useful. However, if you do want to know about dealing with responses, the use of stored recipient lists or want a greater technical insight into this example, then the sections below are for you.
Response from Alerting Hub
Once you’ve initiated the alert using the sendalert API call we’ll respond with some initial information. If all goes well you’ll receive something similar to the example response below:
{
"success": true,
"returnCode": 200,
"alertId": "9ab246a9-7b22-4eed-aaca-7fc21bf05ce7",
"clientRef": "snowalert",
"alerts": [
{
"alertType": "sms",
"tag": "parent_sms",
"success": true,
"sentCount": 5,
"requestedCount": 5,
"remainingCapacity": 95
},
{
"alertType": "sms",
"tag": "teacher_sms",
"success": true,
"sentCount": 3,
"requestedCount": 3,
"remainingCapacity": 92
},
{
"alertType": "email",
"tag": "teacher_email",
"success": true,
"sentCount": 3,
"requestedCount": 3,
"remainingCapacity": 497
},
{
"alertType": "call",
"tag": "teacher_call",
"success": true,
"sentCount": 4,
"requestedCount": 4,
"remainingCapacity": 862
}
],
"emailRefId": "0409_09172254"
}
The most important piece of information returned by Alerting Hub is the alertId as seen above. This is the unique reference for the alert and, where possible, Alerting Hub will try to give you that reference when issuing you with delivery notes, sms replies, voice call responses, email replies and so forth.
Don’t worry about the other information returned; there’s plenty of information in the specific API pages relating to what to expect back. For now let’s move on to how Alerting Hub can provide you with details of how the alert is progressing.
Progress from Alerting Hub
There’s two main methods of obtaining progress updates from Alerting Hub: callback or collection (also known as polling). These are described in detail in the API guide, with callback being the preferred method. In both cases the information returned to you is the same. For the purposes of this example we’ll assume you’re going to poll us for collection.
To poll you would use the collectevents API call; the example below asks for any progress on any alert, with a maximum of 50 progress events to be returned at a time.
{
"version" : "latest",
"apiKey" : "abcdefghijklmnopqrstuvwxyz",
"alertId" : "all",
"options" : {
"maximumItemsToReturn" : 50
}
}
The response from Alerting Hub is an array of progress events, if any are found. In our example, the response to the 1st collectevents API call could look something like the following:
{
"success": true,
"returnCode": 200,
"numEventsRemaining": 0,
"events": [
{
"alertId": "9ab246a9-7b22-4eed-aaca-7fc21bf05ce7",
"clientRef": "snowalert",
"event": "started",
"type": "alert",
"whence": "2020-09-04T16:58:52.000Z"
},
{
"event": "sent",
"type": "sms",
"clientRef": "snowalert",
"alertId": "9ab246a9-7b22-4eed-aaca-7fc21bf05ce7",
"alertees": [
"+447777100100",
"+447777100101",
"+447777100102",
"+447777100103",
"+447777100104"
],
"whence": "2020-09-04T17:19:20.000Z"
},
{
"event": "sent",
"type": "sms",
"clientRef": "snowalert",
"alertId": "9ab246a9-7b22-4eed-aaca-7fc21bf05ce7",
"alertees": [
"+447777200100",
"+447777200101",
"+447777200102"
],
"whence": "2020-09-04T17:19:20.000Z"
},
{
"event": "sent",
"type": "email",
"clientRef": "snowalert",
"alertId": "9ab246a9-7b22-4eed-aaca-7fc21bf05ce7",
"alertees": [
"teacher1@school.com",
"teacher2@school.com",
"teacher3@school.com"
],
"whence": "2020-09-04T17:19:20.000Z"
}
]
}
As you can see from the above progress reports, Alerting Hub is indicating that the alert has started and also that the two SMS have been sent to the relevant recipients as has the email. Repeated polling over time will also yield other events such as SMS delivery notes, SMS replies (if enabled), email replies (if enabled) and voice-call responses. Alternatively, and preferred, Alerting Hub can send progress reports as they happen by a callback URL you provide, this is the most efficient way of handling Alerting Hub progress reports. See the API guide for more information.
Using stored lists
In the example above, we saw the use of dynamic recipient lists, where each message or voice call was sent to a list of recipients specified within the API call data.
The storecontent API allows you to upload recipient lists (amongst other things) to be stored by Alerting Hub for repeated use. Multiple content can be included within a single transaction allowing you to upload a variety of pre-prepared items at the same time. You can then use these stored items when sending alerts instead of specifying all the details in the API call.
We will re-visit the example above, this time using stored lists. Firstly you can store your various lists with Alerting Hub using the following example.
What to send to the storecontent API
The following snippet shows the JSON data that could be sent to create the relevant recipient lists for the teaching staff: one list for sms, one for emails and one for voice calls – we’re showing separate sms and voice lists as the latter could have non-mobile telephone numbers). These lists can be uploaded ahead of time, days, weeks or months before they are needed. Should the lists change, you can call the storecontent API to update them as needed.
{
"version": "latest",
"apiKey": "abcdefghijklmnopqrstuvwxyz",
"content": [
{
"contentType": "recipientList",
"tag" : "teacher_sms",
"content" : "+447777200100,+447777200101,+447777200102",
"contentEncoding": "utf8",
"options": {
"expirationInDays": 0
}
},
{
"contentType": "recipientList",
"tag" : "teacher_emails",
"content" : "teacher1@school.com,teacher2@school.com,teacher3@school.com",
"contentEncoding": "utf8",
"options": {
"expirationInDays": 0
}
},
{
"contentType": "recipientList",
"tag" : "teacher_call",
"content" : "+447777200100,+447777200101,+447777200102,+441603111222",
"contentEncoding": "utf8",
"options": {
"expirationInDays": 0
}
}
]
}
What the storecontent API returns
As you can see in the following return snippet, Alerting Hub returns a unique storage identifier for each requested store. The tags you specified are also returned here, allowing you to link the Alerting Hub storage identifier with your own internal data.
{
"success": true,
"returnCode": 200,
"content": [
{
"contentType": "recipientList",
"tag": "teacher_sms",
"success": true,
"storeId": "58007144-d97f-4b09-a7e1-682ac59b6419",
"expirationInDays": 0
},
{
"contentType": "recipientList",
"tag": "teacher_emails",
"success": true,
"storeId": "9c7e0902-2eb1-4209-ba05-121b1cc9b594",
"expirationInDays": 0
},
{
"contentType": "recipientList",
"tag": "teacher_call",
"success": true,
"storeId": "ffe8c208-5aaf-4259-8ba8-cc61b60b5997",
"expirationInDays": 0
}
]
}
Using the stored recipient lists
We now look at the JSON data you could use to send an alert similar to the one shown further above. As you will see, the only real difference is that the recipientList items are replaced with storedRecipients items. We’ve kept the parent list as dynamic to show that you can mix and match dynamic and stored lists at will; in fact let’s go one step further, if you look at the teacher’s sms section below you’ll see that Alerting Hub can support a stored recipient list combined with a dynamic one for the same alert item.
{
"version" : "latest",
"apiKey" : "abcdefghijklmnopqrstuvwxyz",
"clientRef" : "snowalert",
"alert" : [
{
"alertType" : "sms",
"tag" : "parent_sms",
"recipientList" : "+447777100100,+447777100101,+447777100102,+447777100103,+447777100104",
"content" : "Due to snow the school will be closed today, for any queries please contact 07777200000",
"contentEncoding" : "utf8",
"sender" : "SNOW ALERT"
},
{
"alertType" : "sms",
"tag" : "teacher_sms",
"storedRecipients": "58007144-d97f-4b09-a7e1-682ac59b6419",
"recipientList" : "+447777100500,+447777100501",
"content" : "The school is closed today, parents have been informed, please contact the Head for further information",
"contentEncoding" : "utf8",
"sender" : "SCHOOL ALERT"
},
{
"alertType" : "email",
"tag" : "teacher_email",
"to": "All staff",
"sender" : "School Alert",
"subject": "Important - school is closed today",
"storedRecipients": "9c7e0902-2eb1-4209-ba05-121b1cc9b594",
"content" : "The school is closed today, parents have been informed, please contact the head for further information. Please reply to this email when you receive it.",
"contentEncoding" : "utf8"
},
{
"alertType" : "call",
"tag" : "teacher_call",
"storedRecipients": "ffe8c208-5aaf-4259-8ba8-cc61b60b5997",
"sender" : "+447777200000",
"voiceFormat": "tts",
"content": "This is an important school announcement. The school is closed today, I repeat the school is closed. Please press any key to acknowledge you have heard this message and then hangup. Thank you.",
"contentEncoding": "utf8",
"ivrControl": {
"ivrRequireResponse": true,
"ivrAttempts" : 3
}
}
]
}
