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.

More API samples

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		Requirement	Default	Description
version		Mandatory	None	See API guide
apiKey		Mandatory	None	See API guide
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.
options
	notification	Optional		See API guide
	notificationType	Optional		See API guide
	callbackURL	Optional		See API guide
	schedule	Optional		Optional schedule with which to launch the alert See API guide
alert		Mandatory		Alert details. If required multiple alert sections can be declared allowing more than one alert to be combined into a single RESTfull transaction
	alertType	Mandatory	None	The type of alert to initiate one of: "sms", "email","call","inboundCall"
	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.
	recipientList	Optional	None	Comma Separated Variable list of recipients (e.g. “a,b,c”)
	recipients	Optional	None	Array of recipients [“a”,”b”,”c”]
	storedRecipients	Optional	None	The uuid of previously stored recipientList
	storedContent	Optional	None	The uuid of previously stored 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
sms	sender	Mandatory	None	This 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.
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
	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 mulitpart bounday
call	sender	Mandatory	None	The E.164 number to use as the caller line id for this outbound call
	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 API guide
	ivrControl	Optional		Control over the outbound call flow. See below
	additionalContent	Optional array	None	Optional array of additional content for more advanced IVRs. See below
inboundCall	telephoneNumber	Mandatory	None	Where is the expected inbound number that will be called
	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 API guide

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

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

ivrType	Description
simple	This 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.
replay	A 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"
    }
]

Parameter	Requirement	Default	Description
storedContent	Optional	None	The uuid of previously stored content . Either this or content must be specified.
content	Optional	None	The content to be used as the payload of the alert. Either this or storedContent must be specified.
contentEncoding	Mandatory if content is set	None	One of "base64" \| "utf8". This is the encoding used for the content
voiceFormat	Mandatory if content is set	None	One of "mp3","wav","aiff", "tts". The format of the audio which is encoded in the content
tts	Optional (only applicable if content is set)	None	Optional tts block used if voiceFormat is 'tts'. See API guide
contentTag	Mandatory	None	The 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:

Parameter	Requirement	Default	Description
ivrAttempts	Optional	1	Number of times the call will be attempted, if non of the 'success' states are reached.
ivrRequireFullPlay	Optional	false	If 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.
ivrRequireResponse	Optional	false	If 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

Parameter	Requirement	Default	Description
ivrAttempts	Optional	1	Number of times the call will be attempted, if non of the 'success' states are reached.
ivrSayAgainDigits	Optional	1	The keypad value(s) that can be used to replay the message.
ivrAmOkDigits	Optional	2	The keypad value(s) that if pressed will result in a status of 'recipientOk' being returned to you as part of the call complete event.
ivrAmNotOkDigits	Optional	*	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.
ivrDigitsStopPlay	Optional	false	If 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.
ivrRepeatPrePrompt	Optional	false	If true then the preliminary message (contentTag pre) will be included again if the recipient requests to hear the message again.

Back to API guide