Sending alerts

Parameter			Requirement	Default	Description
version			Mandatory	None	See API guide
apiKey			Mandatory	None	See API guide
clientRef			Mandatory		Free form The client reference will be associated with the alert that you are sending and will, when possible, be provided as part of alert responses (such as sms delivery notification, voice-call responses etc.). Can only contain alphanumeric and + - _ characters.
contactGroup			Optional	None	Specifies a contact group that can be used across all alerts specified in this api call. See below
linkedAlerts			Optional	None	Specifies any cross-alert linking, mainly used for escalation type activities. See below
alert			Mandatory (array)		Alert details as a JSON array. If required multiple alert elements can be declared allowing more than one alert to be combined into a single RESTfull transaction.
	alertType		Mandatory	None	The type of alert to initiate one of: "sms", "email","call","inboundCall"
	tag		Mandatory	None	Free form client defined tag which will be returned when results are either polled or events triggered allowing the client application to sort events.
	recipients|recipientList|storedRecipients contacts|contactList|storedContactList contactSet|contactSetList|storedContactSetList		Mandatory (at least one form)	None	One or more of the ways of specifying to whom the alert is to be sent See below
	linkedAlertModifiers		Optional	None	If using linked-alerts then this object specifies what to do with the contacts depending upon what responses have been previously received. See below
	storedContent		Optional	None	The uuid of previously stored content . This or content must be specified.
	content		Optional	None	The content to be used as the payload of the alert. This or storedContent must be specified.
	contentEncoding		Optional (used if content set)	None	One of "base64" | "utf8". This is the encoding used for the content
alertType=sms
	sender		Mandatory	None	This field determines who the recipient will appear to receive the message from. It can be an E.164 number or an alpha-numberic. There are restrictions to the use of both. If you are using customer specific replies then you will have been allocated an E.164 number to use.
	lookups		Optional	None	Allows templated lookups and unique short-links in messages See below
alertType=email
	to		Optional	None	Email display part of name (e.g. "undisclosed") no @ is needed the right hand side will be provided internally
	sender		Optional	None	Email display part of name (e.g. "alerts") no @ is needed the right hand side will be provided internally
	replyTo		Optional	None	Email display part of name (e.g. "alertResponses") no @ is needed the right hand side will be provided internally
	subject		Optional	None	Email subject line. When the email is sent, this field will have a unique reference number appended by the alerting hub system such that replies can be tied in to the alert that was sent
	emailBodyIsMultipart		Optional	False	If the body of the email message is multi-part
	emailBodyContentType		Optional	text/plain; charset=us-ascii	If emailBodyIsMultipart: false then is used (def text/plain; charset=us-ascii
	multipartBoundary		Optional	Blank	If emailBodyIsMultipart: true then this flag is used to denote start of a new mulitpart bounday
	lookups		Optional	None	Allows templated lookups and unique short-links in messages See below
alertType=call
	sender		Mandatory	None	The E.164 number to use as the caller line id for this outbound call
	voiceFormat		Mandatory if content set	None	One of "mp3","wav","aiff", "tts". The format of the audio which is encoded in the content
	tts		Optional (used if content set)	None	Optional tts block used if voiceFormat is 'tts'. See API guide
	ivrControl		Optional		Control over the outbound call flow. See below
	additionalContent		Optional array	None	Optional array of additional content for more advanced IVRs. See below
alertType=inboundCall
	telephoneNumber		Mandatory	None	Where is the expected inbound number that will be called
	voiceFormat		Optional	None	One of "mp3","wav","aiff", "tts". The format of the audio which is encoded in the content
	tts		Optional	None	Optional tts block used if voiceFormat is 'tts'. See API guide
options			Optional	None
	notification		Optional		See API guide
	notificationType		Optional		See API guide
	callbackURL		Optional		See API guide
	schedule		Optional		Optional schedule with which to launch the alert See API guide
	lifetime		Optional		Lifetime of the alert, after which no responses will be processed and the alert will be deleted from the system - only valid if client is permitted to set. Lifetime is specified as {n}{M|w|d|h|m|s} where M = months, w = weeks, d = days, h = hours and s = seconds. A value of 0d will mean no expiration.

Response

Parameter		Description
If schedule not requested
success		One of “true”, “false”. If false then failureReason should also be returned
clientRef		From the request
alertRef		Internally generated alertId relating to all alerts[] in /sendalert
emailSubjectRef		If at least one alert[] was of type "email" this gives the subject reference on all emails within this alert
alerts
	alertType	From request
	tag	From request
	success	If false then failureReason should also be returned
	requestedCount	Number of recipients originally asked for
	sentCount	Actual number of recipients processed
	remainingCapacity	Capacity remaining for the given type
If schedule requested
success		If false then failureReason should also be returned
scheduleId		Unique schedule reference
storeId		Store id used to internally store the scheduled alert
expirationInDays		Stored alert lifetime in days

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.	"e42b1fd0-70fc-4697-b646-9f0fab7306d0"
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.	"e42b1fd0-70fc-4697-b646-9f0fab7306d0"
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.	"e42b1fd0-70fc-4697-b646-9f0fab7306d0"

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:

{
      "name": "example",
      "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" ]
        }
      ]
    }

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.

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.

Linked alerts and 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.

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.

Lookups and shortlinks

When sending bulk SMS, emails and TTS voice calls it is possible to replace some or all of the message or voice content with information unique to each recipient; this is known as performing ‘lookups’. Items such as recipient telephone number (or email address), current date and time and sending number or email address can be specified. In addition, if contact groups are used instead of simple recipient lists then you can supply your own lookups (such as firstname, lastname or any other item you so choose). 

In addition it is possible to specify the use of a ‘shortlink’. This results in a unique (per-recipient) small url being placed in the SMS or email (or even in the TTS voice call but this would be less useful), allowing the recipient to ‘click’ on that link when they receive the message. The link will take them back via AlertingHub for collection of information such as browser, OS type, recipient number or email address and so on. If you specify an onward url as part of the sendalert then AlertingHub will automatically forward the recipients ‘click’ to your url, together with pertinent information about the recipient. If you do not specify an onward url the recipient will simply see an AlertingHub ‘thank-you’ landing page.

Lookups are specified using the “lookups” JSON section with the relevant alert section in /sendalert as shown here and described in the table following:

"lookups": {
    "performLookups": true,
    "uniqueLookups": true,
    "shortlink": {
        "reference": "a-reference",
        "url": "https://my-companies-url.com/alertinghub-click-through"
    }
}

Parameter	Requirement	Default	Description
performLookups	Optional	false	Whether to actually perform lookups or not. You would normally set this to true to perform lookups.
uniqueLookups	Optional	false	Specifies if the lookups to be used will include items that will be unique to each recipient.
shortlink	Optional	Not set	Specifies shortlink properties if short links are to be used. If you specify a shortlink section then performLookups and uniqueLookups will be automatically set to a true value.
reference	Optional	Overall alert client-ref	Reference to associate with the shortlinks.
url	Optional	None	Specifies your own url that the recipient will be redirected to after clicking the shortlink.

To use the lookups in an SMS, email message or TTS voice call you need to encase the relevant special keyword within curly braces {}, so to specify the recipients own telephone number in an SMS simply use {recipient} in the SMS text. (If no “lookups” section is specified in the alert section of /sendalert or “performLookups” is set to false then no lookups are performed.) The currently supported keywords are:

Lookup keyword	Description	Need to set uniqueLookups
{recipient}	The telephone number or email address of the recipient.	Yes
{sender}	The telephone number or email address of the sender.	No
{alertid}	The internal unique alert-id for this /sendalert api call.	No
{reference}	The reference from the lookups part of the alert or the overall client-ref from the /sendalert api call	No
{type}	sms for SMS email for emails	No
{datetime-[TZ]-[format]}	Datetime of sending. [TZ] is an optional timezone and must be in the conventional ISO format such as 'America/Los_Angeles'. The [format] should be replaced with a date/time format string where DD = day, MM = month, YYYY = year, HH = hour, mm = minute, ss = seconds. Example of just current date with default timezone (UTC): {datetime--DD/MM/YYYY}.	No
{shortlink}	A unique short-url per-recipient.	Yes

It should be noted that if lookups are used that are per-recipient unique (“uniqueLookups” is true or “shortlink” is specified) then there are some additional constraints in terms of the number of recipients that can be included in any one /sendalert request. This is currently set at 500 recipients per request.

Outbound IVR

Outbound calls are controlled by Alerting Hub’s configurable IVR system. You can control aspects of the default or standard IVRs we provide using the information below. If you require a more complex or bespoke IVR service please contact your account manager who will be happy to discuss options. The IVR is always specified using the ivrControl JSON block; with the ivrType denoting which type of IVR to use. Other ivrControl elements are then dependent upon the ivrType.

Example ivrControl

"ivrControl": {
    "ivrType": "simple",
    "ivrRequireResponse": false,
    "ivrAttempts": 3,
    "ivrRequireFullPlay": true
}

ivrType

ivrType	Description
simple	This is the default. Plays a single audio message and can then optionally wait for a DTMF press (which is reported back). The IVR can also retry the call a number of times until it receives a key press or simply call once.
replay	A more complex IVR that can play a sequence of audio messages, collect a keypress and also allow the recipient to get the messages repeated.

additionalContent

For more feature rich IVRs there may often be more than one audio message / prompt to play to the recipient as the IVR progresses. These additional prompts are specified within the ‘additionalContent’ array within the main alert JSON block. The type if IVR will denote how many items should be in the array; each item follows a very similar structure to normal content provision with the addition of the ‘contentTag’ explained below.

"additionalContent": [
    {
      "content" : "This is an additional message",
      "contentEncoding": "utf8",
      "voiceFormat": "tts",
      "tts" : {
        "language": "en-GB",
        "gender" : "FEMALE"
       },
      "contentTag": "ivr-dependant-tag"
    },
    {
      "storedContent" : "98be22e5-4d21-4a6c-a189-d4d51d4940d8",
      "contentTag": "ivr-dependant-tag"
    }
]

Parameter	Requirement	Default	Description
storedContent	Optional	None	The uuid of previously stored content . Either this or content must be specified.
content	Optional	None	The content to be used as the payload of the alert. Either this or storedContent must be specified.
contentEncoding	Mandatory if content is set	None	One of "base64" | "utf8". This is the encoding used for the content
voiceFormat	Mandatory if content is set	None	One of "mp3","wav","aiff", "tts". The format of the audio which is encoded in the content
tts	Optional (only applicable if content is set)	None	Optional tts block used if voiceFormat is 'tts'. See API guide
contentTag	Mandatory	None	The ivrType within the ivrControl block will denote how many additional content items there should be and what each one's contentTag must be set to.

Available IVRs

ivrType: simple (the default)

The simple IVR just plays a single audio message and then optionally waits on a keypress from the recipient. ivrControl options are:

Parameter	Requirement	Default	Description
ivrAttempts	Optional	1	Number of times the call will be attempted, if non of the 'success' states are reached.
ivrRequireFullPlay	Optional	false	If false then a call must reach the connected state (at least) in order to be considered a success. If true then the full voice prompt must have been played before the recipient hung up in order to be considered a success.
ivrRequireResponse	Optional	false	If false then no DTMF press is required by the recipient. If true then the recipient must press a DTMF key in order to acknowledge receipt of the call. If this option is used it is recommended that the voice prompt contains relevant instructions for the recipient.

ivrType: replay

The replay IVR plays a preliminary message to the recipient, then the main message and then a final message. This allows for situations where you may wish to reuse the same preliminary and final messages (for instance a generic welcome and generic instructions respectively) whilst then tailoring the main message on a per-event basis. In addition a message is also played if / when the recipient acknowledges via a key press. There is also more fine tuned control over the IVR in comparison to the simple variant.

To use the replay IVR you must include additionalContent with the following contentTags (the main message is provided by the normal content/storedContent items in the alert JSON):

• pre – this specifies the preliminary message
• post – this specifies the final message
• done – this specifies the message played if the recipient presses a key

Parameter	Requirement	Default	Description
ivrAttempts	Optional	1	Number of times the call will be attempted, if non of the 'success' states are reached.
ivrSayAgainDigits	Optional	1	The keypad value(s) that can be used to replay the message.
ivrAmOkDigits	Optional	2	The keypad value(s) that if pressed will result in a status of 'recipientOk' being returned to you as part of the call complete event.
ivrAmNotOkDigits	Optional	*	The keypad value(s) that if pressed will result in a status of 'recipientNotOk' being returned to you as part of the call complete event.
ivrDigitsStopPlay	Optional	false	If true then if the recipient presses a key during the play out of the audio messages then those messages will stop playing and the IVR will move on to the final stages.
ivrRepeatPrePrompt	Optional	false	If true then the preliminary message (contentTag pre) will be included again if the recipient requests to hear the message again.