Recipients & Contacts
Specifying who receives the alerts
When sending alerts you must specify at least one receiver of the alert. There are many ways to let the system know who you would like to receive the alert as described below (you can specify any or all of these in each alert section when sending alerts but you must specify at least one).
Receivers can be specified in 3 broad categories:
- Recipients – simple phone numbers and email addresses.
- Contacts – a contact holds phone numbers for sms/voice and an email address under a unique name or identifier. It is that identifier that is specified when sending the alert and the system will lookup the relevant number or email address to use. Contacts can also hold other information that allows personalisation of alerts to be made.
- Contact set – a pre-generated set of contact identifiers; this allows common groupings of contacts to be made and the alert simplified (e.g. you could have a contact set called ‘sales_team’ and you simply specify that when sending the alert; the platform will lookup all the relevant contacts and ensure that the alert reaches them by their relevant number of email address.
When using contacts or contact sets these must refer to items that have been defined in a contact-group (think of a contact-group as an entire address list) and that contact-group must have been specified in the alert itself.
| Parameter within the alert section | Description | JSON example |
|---|---|---|
| recipients | Array of phone numbers or email addresses | [ "+447976100001", "+447976100002" ] |
| recipientList | Comma delimited string list of recipients | "+447976100001",+447976100002" |
| storedRecipients | Previously stored recipientList. Would have been stored using the /storecontent api. | See below |
| contacts | Array of contacts | [ "contact-1" , "contact-2" ] |
| contactList | Comma delimited list of contacts | "contact-1,contact-2" |
| storedContactList | Previously stored contactList. Would have been stored using the /storecontent api. | See below |
| contactSets | Array of contact sets | [ "sales_team" , "security" ] |
| contactSetList | Comma delimited list of contact sets | "sales_team,security" |
| storedContactSetList | Previously stored contactSetList. Would have been stored using the /storecontent api. | See below |
Contact-groups
A contact-group is a collection of contacts and contact-sets. Each contact consists of an identifier (which should be non-compromising from a user or customer’s perspective) and items such as SMS number, email address and voice call number (these and all other contact details except for the identifier are held in encrypted form whilst at rest at all times). Contact-sets are simply collections of contacts (specified by their identifier) to allow for concepts such as ‘sales_team’, ‘parents’, ‘security’ and so on. When you define a contact-group Alerting Hub will automatically add the contact-set ‘all’ for you, which can then be used to specify all the contacts in that contact-group.
Example contact-group:
{
"contacts": [
{
"id": "name-0",
"sms": "+447976100000",
"email": "a.smith@mycompany.com",
"call": "+447976200000",
"lookups": {
"firstname": "adam",
"lastname": "smith"
}
},
{
"id": "name-1",
"sms": "+447976100001",
"email": "j.jones@mycompany.com",
"call": "+447976200001",
"lookups": {
"firstname": "jenny",
"lastname": "jones"
}
},
{
"id": "name-2",
"sms": "+447976100002",
"email": "e.sharples@mycompany.com",
"call": "+447976200002",
"lookups": {
"firstname": "edna",
"lastname": "sharples"
}
}
],
"sets": [
{
"name": "sales_team",
"ids": [ "name-0", "name-2" ]
},
{
"name": "management",
"ids": [ "name-1" ]
}
],
"storeName" : "myContactGroup"
}
The contacts array is described here:
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| id | Mandatory | None | Unique name within this contact group, note this identifier will be kept on the system unencrypted. |
| sms | Optional | None | Number to use for SMS |
| Optional | None | Email address to use | |
| call | Optional | None | Number to use to call |
| lookups | Optional | None | Key : value string pairs of arbitrary content. Used when performing lookups with contacts. E.g. 'This is an SMS for {firstname} {lastname}' |
The sets array is described here:
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| name | Mandatory | None | Unique name for the set in this contact group. |
| ids | Mandatory | None | Array of contact ids from the contact group. |
When using the /sendalert API call you can specify a single contact-group to be used via the top-level ‘contactGroup’ JSON key with the following form:
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| inlineContactGroup | Optional | None | A contact group as per the specification above. |
| storedContactGroup | Optional | None | Previously stored contact group. Would have been stored using the /storecontent api or by specifying a storeName in a previous alert's inlineContactGroup. |
If a contact-group has been specified for an alert you can then use the contact identifiers and / or contact-sets in-place of or in addition to normal recipients. In addition, if you specify a storeName for the contact group it will be preserved using that name so that you can specify it by name in other alerts (this bypasses the need to use the /storecontent API call).