Simple, single REST transaction

Want to send SMS, voice and email alerts as part of the same mass notification? Using the Alerting Hub API you can trigger multiple events to multiple recipients all within a single one-shot API call. What’s more we also monitor and track responses and tie those back to your API call, allowing you to easily marshal results and replies. We also offer an number of additional APIs to provide useful services for more advanced use cases, see below.

Want to get started straight away? Request a free sample API key that allows you to send a limited number of real SMS or emails and make a limited number of voice calls. See our quick-start guide for more information.

For testing, our sample API key also allows unlimited use of our sandbox. There is also an email API route as an alternative option.

  • Connect

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

    • https://sandboxapi.alert.alertinghub.co.uk
    • mailto://api@awsemail.alertinghub.co.uk
    • mailto://sandboxapi@awsemail.alertinghub.co.uk
  • Send

    POST/Attach

    {
      "version": "latest",
      "apiKey": "abcdef..."
    }
  • Response

    200 OK/Reply

    {
      "success": true
    }

Sending alerts

APIExplanation
/api/json/sendalertPossibly the only API you ever need. Sends an alert which can consist of as many different SMS, voice calls or emails as you wish in one go. The alert can be sent immediately or scheduled for later activation.
/api/json/sendstoredalertSends a previously stored alert (see below for storing of alerts and other items). The alert can be sent immediately or scheduled for later activation.
/api/json/cancelalertCancels an ongoing live alert

Common parameters

Every API has the same basic structure, which is then added to depending upon the specific API being called. They must all have the following parameters in their top level JSON block:

ParameterDescription
versionThe version of the API you would like to use. Versions are in the form 'vX.Y' or you can use the special value 'latest' (which is recommended). The current latest version is v1.0.
apiKeyThe API key is used to identify and validate your request with Alerting Hub. If you do not have an API key, please contact your account manager to obtain one. Note that you can have several API keys (e.g. one live and one for sandboxing). You should treat your API key with care and not send it or publish it anywhere where it could be copied or used by another party. In addition Alerting Hub can also restrict the IP addresses from which your API key can be used as an additional security measure for you.

Collection

APIExplanation
/api/json/collecteventsPolls Alerting Hub for any outstanding events. This relies on your API key being marked as allowing collection. You can also setup a callback URL to avoid having to repeatedly poll Alerting Hub. See below for more details on callbacks and polling.
/api/json/getinfoGets general information relating to client account

Storage APIs

Alerting Hub can store various items on your behalf so that you can reuse them without having to specify their contents every time you wish to send an alert. These items include alerts, recipient lists, audio files, sms and email content etc. When storing an item Alerting Hub will issue you with a unique reference to that stored item, you can then use that reference in place of actual content when sending alerts.

APIExplanation
/api/json/storecontentStores content for later use (alert, sms/email/voice content, recipient lists)
/api/json/deletecontentDeletes previously stored content
/api/json/checkcontentChecks status of previously stored content

Results and responses

Results from sending alerts include items such as sent notifications, SMS delivery notes, SMS and email replies, voice call results and so forth. Where possible Alerting Hub will link these results to the original /api/json/sendalert, or related, API call using the unique Alert Id that is generated. All results are returned in JSON form and are identical regardless of which method is used to obtain them; these methods are described below:

MethodExplanation
CallbackThis is the preferred method of use as it ensures that you obtain any results as soon as they are available. Callbacks are achieved using a standard URL (e.g. https://alertcallback.mycompany.com).
Callback URLs can be specified either at the API key level (please contact your account manager to configure your API key callback URL) or on a per-API call basis. This latter mode of operation allows you to specify a callback URL as part of the /api/json/sendalert or related API call. If we can't get through to your callback URL we'll keep trying for a while; once too much time has passed we will archive the events so that they can then be obtained at a later time once your callback URL is available again.
Polling / collectionUses the /api/json/collectevents API call to retrieve a set of results. In order to use this API call you must contact your account manager in order to have collection enabled. In addition, you will be restricted on the frequency with which this API call can be made, again please contact your account manager for more information.
For APIs involved in sending alerts you can override your API key’s default behaviour using the following JSON in the options block of your API call (this assumes your API key is set to allow such overriding):
"options" : {
  "notification" : "callback",
  "callbackUrl" : " https://callmebackhere.com/landing"
}
ParameterRequirementDefaultDescription
notificationOptionalAPI key modeOne of callback, poll or none. If set to none then all events relating to the alert will be discarded. If set to poll then the /collectevents API should be used to obtain results.
callbackUrlMandatory (only if notification is 'callback')API key callback URLWhere to callback to

Scheduling

When sending an alert via any of the appropriate APIs the default is to send the alert immediately. Alternatively you can also specify a schedule which will send the alert at a later time and also, optionally, repeat the alert as required, see the example:

"schedule" : {	
  "start" : "now",
  "startOffset" : 1,
  "startInterval" : "minute",
  "period" : 2,
  "periodicity" : "hours",
  "end" : "2021-02-01T01:02:03.0Z"
}

The following table describes the various parameters that can form a schedule block:

ParameterRequirementDefaultDescription
startMandatoryNoneStart time in YYYY-MM-DDTHH:MM:SS.MS[TZ] form or 'now'. Where [TZ] can be 'Z' for GMT or +/-H:MM as per ISO 8601
startOffsetOptional1Offset from start time to begin 1st (or only) alert
startIntervalOptionalhourInterval that startOffset relates to (one of "minutes", "hours", "days", "weeks", "months", "minute", "hour", "day", "week", "month"
periodOptional0Period between repeated alerts (0 = one shot alert)
periodicityOptionalneverInterval that period relates to (one of "none", "never", "minutes", "hours", "days", "weeks", "months", "minute", "hour", "day", "week", "month"
pausedOptionalfalseEither “true” or “false. Whether the scheduled alert is paused to begin with
endOptional (Mandatory if periodicity is set)End time in YYYY-MM-DDTHH:MM:SS.MS[TZ] form, must be specified if period/periodicty is set
The following additional scheduling APIs can also be used.
APIExplanation
/api/json/schedulestoredalertSchedules a previously stored alert. Very similar in nature to the api/json/sendstoredalert api call but available here for completeness.
/api/json/cancelscheduledalertCancels an upcoming scheduled alert
/api/json/pausescheduledalertPauses an upcoming scheduled alert
/api/json/resumescheduledalertResumes an upcoming scheduled alert

Text to Speech (TTS)

When dealing with audio for outbound or inbound calling it is possible, rather than specifying or providing the actual encoded audio data, to use Alerting Hub’s Text-To-Speech facility, also known as TTS. This is generally achieved by specifying the voiceFormat JSON key as ‘tts’ and then providing some optional extra parameters in their own ‘tts’ block; as shown below (the values shown are the default values if not specified, or the entire tts block is omitted):

"tts" : {
  "language": "en-GB",
  "gender": "FEMALE",
  "enhancedTts" : false
}
ParameterRequirementDefaultDescription
languageOptionalen-GBLanguage / accent to use.
genderOptionalFEMALEGender to use from MALE|FEMALE|NEUTRAL.
enhancedTtsOptionalfalseIf false then the content to which the tts block refers is treated as just text to be spoken. If true then the content block contains SSML.

Email API

Instead of the conventional HTTPS based API we also offer an email route to Alerting Hub that supports all the published APIs.

To use the email route you must send an email to one of the following email addresses:

  • api@awsemail.alertinghub.co.uk
  • sandboxapi@awsemail.alertinghub.co.uk

The email must have the following:

  • Subject line must be the api call required (e.g. sendalert) without any /api/json preliminary text.
  • An attachment consisting of a single text file, containing the JSON request, and with a filename ending in .json and of type application/json.

Once sent you should receive an email reply (it may take a few minutes to be delivered) containing the response in both the body of the email and as an attachment named ‘response.json’.