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.
options
notificationOptionalSee API guide
notificationTypeOptionalSee API guide
callbackURLOptionalSee API guide
scheduleOptionalOptional schedule with which to launch the alert See API guide
alertMandatoryAlert details. If required multiple alert sections 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.
recipientListOptionalNoneComma Separated Variable list of recipients (e.g. “a,b,c”)
recipientsOptionalNoneArray of recipients [“a”,”b”,”c”]
storedRecipientsOptionalNoneThe uuid of previously stored recipientList
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
smssenderMandatoryNoneThis 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.
emailtoOptionalNoneEmail 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
callsenderMandatoryNoneThe 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
inboundCalltelephoneNumberMandatoryNoneWhere 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

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

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.