Send Alert API

https://api.alert.alertinghub.co.uk/api/json/sendalert

Alerting Hub’s sendalert API enables you to trigger multiple events from a single REST API transaction. That means you can send SMS, voice and email messages to multiple people through a single, one-off call to our platform. We’ll then handle all of the sending for you, track the results and responses and collate them all under a single reference.

We can either send you those results via a callback or you can poll ask us for them via a collection API. If you don’t want any responses, that’s also fine, you can tell us via the API call and we’ll handle that.

We’ve also made the platform highly configurable, so there’s a number of options are available to to meet the specific requirements of your solution should the default settings not be enough.

Json sample

{
    "version": "latest",
    "apiKey": "abcdefghijklmnopqrstuvwxyz",
    "clientRef": "abcd-efgh",
    "alert": [
        {
            "alertType": "sms",
            "tag": "t1",
            "content": "This is an SMS",
            "contentEncoding": "utf8",
            "sender": "+447777100100",
            "recipients": [
                "+447777100100",
                "+447777100101",
                "+447777100102"
            ]
        }
    ]
}

Sending alerts

Parameter  RequirementDefaultDescription
versionMandatoryNoneSee API guide
apiKeyMandatoryNoneSee API guide
clientRefMandatoryFree 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.
contactGroupOptionalNoneSpecifies a contact group that can be used across all alerts specified in this api call. See below
linkedAlertsOptionalNoneSpecifies any cross-alert linking, mainly used for escalation type activities. See below
alertMandatory (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.
alertTypeMandatoryNoneThe type of alert to initiate one of: "sms", "email","call","inboundCall"
tagMandatoryNoneFree 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)NoneOne or more of the ways of specifying to whom the alert is to be sent See below
linkedAlertModifiersOptionalNoneIf using linked-alerts then this object specifies what to do with the contacts depending upon what responses have been previously received. See below
storedContentOptionalNoneThe uuid of previously stored content . This or content must be specified.
contentOptionalNoneThe content to be used as the payload of the alert. This or storedContent must be specified.
contentEncodingOptional (used if content set)NoneOne of "base64" | "utf8". This is the encoding used for the content
alertType=sms
senderMandatoryNoneThis 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.
lookupsOptionalNoneAllows templated lookups and unique short-links in messages See below
alertType=email
toOptionalNoneEmail display part of name (e.g. "undisclosed") no @ is needed the right hand side will be provided internally
senderOptionalNoneEmail display part of name (e.g. "alerts") no @ is needed the right hand side will be provided internally
replyToOptionalNoneEmail display part of name (e.g. "alertResponses") no @ is needed the right hand side will be provided internally
subjectOptionalNoneEmail 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
emailBodyIsMultipartOptionalFalseIf the body of the email message is multi-part
emailBodyContentTypeOptionaltext/plain; charset=us-asciiIf emailBodyIsMultipart: false then is used (def text/plain; charset=us-ascii
multipartBoundaryOptionalBlankIf emailBodyIsMultipart: true then this flag is used to denote start of a new mulitpart bounday
lookupsOptionalNoneAllows templated lookups and unique short-links in messages See below
alertType=call
senderMandatoryNoneThe E.164 number to use as the caller line id for this outbound call
voiceFormatMandatory if content setNoneOne of "mp3","wav","aiff", "tts". The format of the audio which is encoded in the content
ttsOptional (used if content set)NoneOptional tts block used if voiceFormat is 'tts'. See API guide
ivrControlOptionalControl over the outbound call flow. See below
additionalContentOptional arrayNoneOptional array of additional content for more advanced IVRs. See below
alertType=inboundCall
telephoneNumberMandatoryNoneWhere is the expected inbound number that will be called
voiceFormatOptionalNoneOne of "mp3","wav","aiff", "tts". The format of the audio which is encoded in the content
ttsOptionalNoneOptional tts block used if voiceFormat is 'tts'. See API guide
optionsOptionalNone
notificationOptionalSee API guide
notificationTypeOptionalSee API guide
callbackURLOptionalSee API guide
scheduleOptionalOptional schedule with which to launch the alert See API guide
lifetimeOptionalLifetime 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
successOne of “true”, “false”. If false then failureReason should also be returned
clientRefFrom the request
alertRefInternally generated alertId relating to all alerts[] in /sendalert
emailSubjectRefIf at least one alert[] was of type "email" this gives the subject reference on all emails within this alert
alerts
alertTypeFrom request
tagFrom request
successIf false then failureReason should also be returned
requestedCountNumber of recipients originally asked for
sentCountActual number of recipients processed
remainingCapacityCapacity remaining for the given type
If schedule requested
successIf false then failureReason should also be returned
scheduleIdUnique schedule reference
storeIdStore id used to internally store the scheduled alert
expirationInDaysStored 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 sectionDescriptionJSON example
recipientsArray of phone numbers or email addresses[ "+447976100001", "+447976100002" ]
recipientListComma delimited string list of recipients"+447976100001",+447976100002"
storedRecipientsPreviously stored recipientList. Would have been stored using the /storecontent api."e42b1fd0-70fc-4697-b646-9f0fab7306d0"
contactsArray of contacts[ "contact-1" , "contact-2" ]
contactListComma delimited list of contacts"contact-1,contact-2"
storedContactListPreviously stored contactList. Would have been stored using the /storecontent api."e42b1fd0-70fc-4697-b646-9f0fab7306d0"
contactSetsArray of contact sets[ "sales_team" , "security" ]
contactSetListComma delimited list of contact sets"sales_team,security"
storedContactSetListPreviously 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:

ParameterRequirementDefaultDescription
inlineContactGroupOptionalNoneA contact group as per the specification above.
storedContactGroupOptionalNonePreviously 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
}
ParameterRequirementDefaultDescription
linkRefMandatoryNoneA 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.
lifetimeOptionalSystem defaultLifetime 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.
linkOnlyIfRefAlreadyExistsOptionalfalseIf 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 RequirementDefaultDescription
exceptOptionalNoneJSON object describing possible exception conditions.
previouslySeenOptionalNoneSpecifies 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"
    }
}

ParameterRequirementDefaultDescription
performLookupsOptionalfalseWhether to actually perform lookups or not. You would normally set this to true to perform lookups.
uniqueLookupsOptionalfalseSpecifies if the lookups to be used will include items that will be unique to each recipient.
shortlinkOptionalNot setSpecifies 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.
  referenceOptionalOverall alert client-ref Reference to associate with the shortlinks.
  urlOptionalNoneSpecifies 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 keywordDescriptionNeed 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 callNo
{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

ivrTypeDescription
simpleThis 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.
replayA 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"
    }
]
ParameterRequirementDefaultDescription
storedContentOptionalNoneThe uuid of previously stored content . Either this or content must be specified.
contentOptionalNoneThe content to be used as the payload of the alert. Either this or storedContent must be specified.
contentEncodingMandatory if content is setNoneOne of "base64" | "utf8". This is the encoding used for the content
voiceFormatMandatory if content is setNoneOne of "mp3","wav","aiff", "tts". The format of the audio which is encoded in the content
ttsOptional (only applicable if content is set)NoneOptional tts block used if voiceFormat is 'tts'. See API guide
contentTagMandatoryNoneThe 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:

ParameterRequirementDefaultDescription
ivrAttemptsOptional1Number of times the call will be attempted, if non of the 'success' states are reached.
ivrRequireFullPlayOptionalfalseIf 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.
ivrRequireResponseOptionalfalseIf 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
ParameterRequirementDefaultDescription
ivrAttemptsOptional1Number of times the call will be attempted, if non of the 'success' states are reached.
ivrSayAgainDigitsOptional1The keypad value(s) that can be used to replay the message.
ivrAmOkDigitsOptional2The keypad value(s) that if pressed will result in a status of 'recipientOk' being returned to you as part of the call complete event.
ivrAmNotOkDigitsOptional*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.
ivrDigitsStopPlayOptionalfalseIf 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.
ivrRepeatPrePromptOptionalfalseIf true then the preliminary message (contentTag pre) will be included again if the recipient requests to hear the message again.