Annex D: Voice Steps

In the Robocall outbound call procedure, you can build your own Robocall Campaign through a set of mini-structures called “steps”, that define a specific behaviour each one and allows the consumer create elaborated calls with powerful functionalities, only with a simple JSON. Today, we dispose of the following steps, listed above:

• PLAY: execute the reproduction of an audio, referenced by its URL.
• SAY: creates and reproduces an audio, based on an text provided by you.
• WILCARD_SAY: (TO USE IN MULTI-LEVEL IVR CAMPAIGNS) Contains a text with wilcards. The wilcards are the column names of your personalized file, the system creates an audio with the content file por every destination.
• DIAL: redirects your call destination to another phone number
• DETECT: waits for a key event (telephone numeric keyboard press) from the destination, and saves the captured event.
• REPEAT_AUDIO: execute once the reproduction of an specific audio.
• HANGUP: hangups the call

So, how I can use that steps? Through some similar to the following JSON:

The example above indicates how to create a SAY step for our calls, indicating some text to convert to audio, and a voice that says our message. Wonderful, isn’t?

It’s necessary to clarify that the “type” field is strictly mandatory; because if you don’t provide that, we can’t identify the step you provide to us.

So, to go into the detail of each step, in the following tables we disposed the specific description for each step defined in Robocall. You’re free to tell us if you consider that we need to include more details about the steps in this KB!

PLAY STEP

This step allows the reproduction of a WAV file hosted in a specific URL

The field “source” is mandatory, and must be an URL-type String

SAY STEP

Creates an audio file, based on the text that you provides to it and a voice that you choose, and plays it.

Both “text” and “voice” fields are mandatory. The maximum length (in characters, including spaces) of the text to reproduce is 1000. The available list of voices for this step are in the section: Annex C: Available Voices

WILCARD_SAY (FOR MULTILEVEL IVR CAMPAIGNS)

The wilcards are the column names of your personalized file, the system creates an audio with the content file por every destination. For example if your file have the column headers: NAME and CUSTOM1, you can use like:

Both “text” and “voice” fields are mandatory. The maximum length (in characters, including spaces) of the text to reproduce is 1000. The available list of voices for this step are in the section: Annex C: Available Voices

DIAL STEP

Allows the redirection of a call to another phone number, without lose the communication with your destination.

The “destination” field is mandatory, and must be a valid mobile or local destination in international format (with its respective country code)

DETECT STEP

This step allows to control the flow of your call, based on a key event received by the destination. Supports two different ways to use it, related to its “captureType” field:

• Static way: in this case, you provide the different flows that could execute this step and their content to execute. To define that flows, we dispose a special step called OPTION, where you can specify the telephone keyboard key that will match with the user key event (dtfmCommand), a brief description of the step (optionId), and a subset of steps that will be executed if the user selects this option. A JSON example of the above is the following snippet:

• In this case, the following restrictions applies to the fields defined in the OPTION step
  • dtfmCommand: numeric value between 0 and 9 (single digit). Not null
  • optionId: alphanumeric value, no length restriction (preferable as brief as possible). Not null.
  • steps: at least one step in list.

  As a additional restriction, the DETECT step in this way must have at least one OPTION step defined.

As a additional restriction, the DETECT step in this way must have at least one OPTION step defined.

• Dynamic way: it will have the following structure:
  
  { "type": "DETECT", "captureType":"DYNAMIC", "maxDigitsAccepted":"9", "action": "http://example.com/detectcallbackservice" }

  1 2 3 4 5 6

  {   "type": "DETECT",   "captureType":"DYNAMIC",   "maxDigitsAccepted":"9",   "action": "http://example.com/detectcallbackservice" }

  The most important difference about static way is it doesn’t define explicit options (through OPTION steps); on the another hand, this step define a “action” field that must contains an URL to a third-party REST service (a service that you manage); when we catched an keyboard event for this step, we send you a JSON-based message with the following fields:
  • callerId: mobile number of the call destination
  • callId: id of the call entity
  • actionTimestamp: date of the key event
  • detectedDigit: key marked by your client

  A example of the callback JSON is the following:

  { "callerId": "15556667788", "callId": "123456", "actionTimestamp": "2016-04-22T13:05:57.678Z", "detectedDigit" : "123456789" }

  1 2 3 4 5 6

  {   "callerId": "15556667788",   "callId": "123456",   "actionTimestamp": "2016-04-22T13:05:57.678Z",   "detectedDigit" : "123456789" }

  In response to our request, you must to response us a set of steps in JSON format, that will be annexed to the DETECT step and then executed. The received JSON must have the following structure:

In response to our request, you must to response us a set of steps in JSON format, that will be annexed to the DETECT step and then executed. The received JSON must have the following structure:

Additionally, with the “maxDigitAccepted” you can define the maximum number of keyboard key events to capture, in other words, limits the quantity of digits that will be catched in the step execution; the quantity of captured digits could be less to that quantity, but if your customer inputs more digits that expected the service doesn’t recognize them, only catches and sends the quantity of digits that fits with the defined limit.

It’s very important to highlight that the DETECT step only have sense if and only if an audio step (e.g. PLAY, SAY) is above of it. 

REPEAT_AUDIO STEP

As its name indicates, this step allows to repeat the execution of an audio step that was processed before an DETECT step, as PLAY or SAY. Let’s see it in an example:

In the list of steps above we create a simple call with an IVR structure. The audio will be executed, and the user can choose from 3 option, 2 of them will execute an audio reproduction and then a call redirection; but the 3rd option, will replay the first SAY step and again will execute the DETECT step.

This step has no fields defined aside from the step type, and this step can be executed only three times per call.

HANGUP STEP

This step indicates the end of the call. It will be placed in any location in the audio list, but not as the first step of the call.