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
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| version | Mandatory | None | See Alerting Hub API basics |
| apiKey | Mandatory | None | See Alerting Hub API basics |
| 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. |
|
| storeDetails | Optional | None | If 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. |
| trigger | Optional | None | Sets 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. |
| deferral | Optional | None | Stores 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. |
| contactGroup | Optional | None | Specifies a contact group that can be used across all alerts specified in this api call. See contact groups |
| linkedAlerts | Optional | None | Specifies any cross-alert linking, mainly used for escalation type activities. See automated escalation |
Alert-wide options (encapsulated in options {} JSON object)
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| notification | Optional | Uses API key setting | One 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. |
| notificationType | Optional | Uses API key setting | Currently only "json" is supported. |
| callbackURL | Optional | Uses API key setting | If notification is "callback" this specifies the URL Alerting Hub will try to send events and responses to for this alert. |
| schedule | Optional | Optional schedule with which to launch the alert See scheduling alerts | |
| 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. |
Alert items (encapsulated in alert [] JSON array)
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| alertType | Mandatory | None | The type of alert to initiate one of: "sms", "whatsapp", "email","call" |
| 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 recipients & contacts |
| linkedAlertModifiers | Optional | None | If using escalation then this object specifies what to do with the contacts depending upon what responses have been previously received. See automated escalation |
| storedContent | Optional | None | The id of previously stored content href="https://www.alertinghub.net/store-content-api/">See store 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 |
| timeWindows | Optional | None | Array 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. |
| timeWindowZone | Optional | None | Only 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
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| alertType=sms | |||
| sender | Optional | None | This 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. |
| lookups | Optional | None | Allows templated lookups and unique short-links in messages See personalisation |
WhatsApp messages
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| alertType=whatsapp | |||
| sender | Optional | None | This 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. |
| lookups | Optional | None | Allows templated lookups and unique short-links in messages See personalisation |
(Please see here for more information on sending WhatsApp messages.)
Email messages
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| 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, if sender is not specified or is empty then 'Undisclosed' will be used. |
| 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 multipart boundary |
| multipartType | Optional | mixed | If emailBodyIsMultipart: true then this option is used to specify the type of multipart message. Currently supported are 'mixed' and 'alternative'. |
| omitReference | Optional | false | If 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. |
| lookups | Optional | None | Allows templated lookups and unique short-links in messages See personalisation |
Voice messages
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| alertType=call | |||
| sender | Optional | None | The 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. |
| 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 TTS |
| ivrControl | Optional | Control over the outbound call flow. See IVR | |
| additionalContent | Optional array | None | Optional array of additional content for more advanced IVRs. See IVR |
Inbound voice
| Parameter | Requirement | Default | Description |
|---|---|---|---|
| alertType=inboundCall | |||
| telephoneNumber | Mandatory | None | Where |
| 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 TTS |
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 | |