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.
groupInitiate 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"
    }
]
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.

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.

Group calling

For ivrType: group, please refer to group calling.