Interactive Voice Response - send alert API

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.

group Initiate a group call, where several people are called at the same time and placed into an ad-hoc conference.

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.
group	Initiate a group call, where several people are called at the same time and placed into an ad-hoc conference.

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 text-to-speech
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.

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.

Group calling

For ivrType: group, please refer to group calling.