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