Send Alert API – Simple, single REST transaction

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, WhatsApp, 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.

Sending Alerts

ParameterRequirementDefaultDescription
versionMandatoryNoneSee Alerting Hub API basics
apiKeyMandatoryNoneSee Alerting Hub API basics
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.
storeDetailsOptionalNoneIf a valid, existing, store is specified then it is loaded and used in place of all the items that follow in this table. See Alerting Hub API basics" for more details. Alerts can be pre-stored by either calling the /storecontent api call or by specifying a deferral JSON object when making a /sendalert api call.
triggerOptionalNoneSets up the specified trigger points (SMS keyword, Email subject line or URL shortlink) and then stores the alert away until one of the trigger points is activated. See triggered alerts.
deferralOptionalNoneStores the entire alert for later activation See deferred alerts. If you specify a deferral you will receive the unique storage id back as part of the return from the api call. You can use this id, or the deferral name you specified in later calls to /sendalert with a storeDetails object set.
contactGroupOptionalNoneSpecifies a contact group that can be used across all alerts specified in this api call. See contact groups
linkedAlertsOptionalNoneSpecifies any cross-alert linking, mainly used for escalation type activities. See automated escalation

Alert-wide options (encapsulated in options {} JSON object)

ParameterRequirementDefaultDescription
notificationOptionalUses API key settingOne of "none", "poll" or "callback". If "none" then no response events will be generated for you. If set to "poll" then see collecting events for more details. If set to "callback" then the "callbackURL" must also be set to a valid, reachable, URL that Alerting Hub will send events to.
notificationTypeOptionalUses API key settingCurrently only "json" is supported.
callbackURLOptionalUses API key settingIf notification is "callback" this specifies the URL Alerting Hub will try to send events and responses to for this alert.
scheduleOptionalOptional schedule with which to launch the alert See scheduling alerts
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.

Alert items (encapsulated in alert [] JSON array)

ParameterRequirementDefaultDescription
alertTypeMandatoryNoneThe type of alert to initiate one of: "sms", "whatsapp", "email","call"
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 recipients & contacts
linkedAlertModifiersOptionalNoneIf using escalation then this object specifies what to do with the contacts depending upon what responses have been previously received. See automated escalation
storedContentOptionalNoneThe id of previously stored content href="https://www.alertinghub.net/store-content-api/">See store 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
timeWindowsOptionalNoneArray of time windows See time windows. If the current time falls within one of the windows the alert will be processed, if not it will be ignored. This allows you to specify a number of different alerting outcomes depending upon the date and time from within the same sendalert. If no time windows are specified the alert will be processed.
timeWindowZoneOptionalNoneOnly relevant
if timeWindows is set. Specifies an optional timezone (e.g. America/Los_Angeles) with which to interpret the timeWindows. If not specified, your account default will be used.

SMS messages

ParameterRequirementDefaultDescription
alertType=sms
senderOptionalNoneThis field determines who the recipient will appear to receive the message from. It can be an E.164 number or an alpha-numeric. 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. If sender is not specified or is empty then the default for your account will be used.
lookupsOptionalNoneAllows templated lookups and unique short-links in messages See personalisation

WhatsApp messages

ParameterRequirementDefaultDescription
alertType=whatsapp
senderOptionalNoneThis field determines who the recipient will appear to receive the message from. It must be an E.164 number that you are permitted to send WhatsApp messages from. If you are using customer specific replies then you will have been allocated an E.164 number to use. If sender is not specified or is empty then the default for your account will be used.
lookupsOptionalNoneAllows templated lookups and unique short-links in messages See personalisation

(Please see here for more information on sending WhatsApp messages.)

Email messages

ParameterRequirementDefaultDescription
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, if sender is not specified or is empty then 'Undisclosed' will be used.
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 multipart boundary
multipartTypeOptionalmixedIf emailBodyIsMultipart: true then this option is used to specify the type of multipart message. Currently supported are 'mixed' and 'alternative'.
omitReferenceOptionalfalseIf true then the auto-generated unique reference will not be added to the email subject line; this will also mean that reply emails can not be tied back to the alert.
lookupsOptionalNoneAllows templated lookups and unique short-links in messages See personalisation

Voice messages

ParameterRequirementDefaultDescription
alertType=call
senderOptionalNoneThe E.164 number to use as the caller line id for this outbound call. If sender is not specified or is empty then the default for your account will be used.
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 TTS
ivrControlOptionalControl over the outbound call flow. See IVR
additionalContentOptional arrayNoneOptional array of additional content for more advanced IVRs. See IVR

Inbound voice

ParameterRequirementDefaultDescription
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 TTS

Response

ParameterDescription
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