Voice Gateway Markup Language Commands

Chaining Multiple Commands

Use the following syntax to chain multiple commands. The Voice Gateway Markup Language allows chaining multiple commands within the JSON array containing the command elements. Oracle® Intelligent Communication Orchestration Network executes the commands in the order specified in the Voice Gateway Markup Language.

{
  "voicegateway": [
    {
      "command": {
        "setbargein": {
          "allowed": "false"
        }
      }
    },
    {
      "command": {
        "say": {
          "text": "This is a Partial barge in. After you hear limes you can make your selection!! apples,pears,oranges, grapefruits, mandarins,limes"
        }
      }
    },
    {
      "command": {
        "setbargein": {
          "allowed": "true"
        }
      }
    },
    {
      "command": {
        "say": {
          "text": "nectarines, apricots, peaches,plums, bananas,mangoes,strawberries, raspberries, blueberries, kiwifruit, passionfruit, watermelons, rockmelons and honeydew melons.!!  Which one do you want"
        }
      }
    }
  ]
}

Attach Data and Transfer Call

Use the Attach Data command to insert the specified data into a SIP Header, which Oracle® Intelligent Communication Orchestration Network forwards when transferring the call to another destination so that the receiving endpoint can extract the data from the header to preserve context:

The Transfer Call Command initiates transferring the call to a third party away from its current endpoint in the form of a blind transfer.

{
  "voicegateway": [
    {
      "command": {
        "attachdata": {
          "value": "SessionID123456789|CustData1|CustData2|CustData3",
          "name": "User-To-User"
        }
      }
    },
    {
      "command": {
        "transfer": {
          "targetNumber": "+61979555005"
        }
      }
    }
  ]
}

Other options for target numbers include +16035551212@bot, or +16035551212@company1.byoc.mypurecloud.com. Either one can be used to maintain the call on net and pass data from Bot to Bot, or from Bot to Genesys. Without the @ symbol the call will be routed off net and all header information will be stripped.

Default Destination Error

Use the setdefaultdestinaion command to configure the destination number during the welcome event set up. If an error occurs when connecting to the Bot or Text-to-Speech or Speech-to-Text engines, the Voice Gateway transfers the call to the configured destination number. If the transfer fails, Oracle® Intelligent Communication Orchestration Network disconnects the call.

{
   "voicegateway": [
     {
      "command": {
        "setdefaultdestination": {
          "destinationnumber": "+61979555009"
           }
        }
     }
  ]
}

Configure DTMF Input

Use the Configure DTMF Input command to configure how Oracle® Intelligent Communication Orchestration Network collects DTMF-based input.

The hash (#) character is the default terminating digit.
After reaching the maximum number of digits, the action is complete regardless of whether # is pressed.
The inter digit timeout is in milliseconds.
The VG_NO_MATCH event is used if the minimum number of digits is not reached or the inter digit timeout is triggered.
The VG_NO_INPUT event is used if no input is detected.

{
  "voicegateway": [
    {
      "command": {
        "setdtmfcapture": {
          "mindigits": "10",
          "maxdigits": "6",
          "interdigittimeout": "3000"
        }
      }
    }
  ]
}

DTMF-Only Mode

Use the setdtmfonlymode command to configure a call to operate in DTMF-only mode, allowing flexibility in managing how the call handles DTMF inputs during its lifecycle.

{
  "voicegateway": [
    {
  "command": {
    "setdtmfonlymode": {
      "enable": <boolean>,
      "scope": <enum>
    }
  }
}

Hang Up Call

Use the Hangup command to hang up the call from within Oracle® Intelligent Communication Orchestration Network , with an optional reason for the hangup recorded in logging and forwarded as a SIP header when the BYE message is sent.

{
    "voicegateway": [{
        "command": {
            "hangup": {
                "reason": "XXX"
            }
        }
    }]
}

Partial Barge-In

Use the partial barge-in tag to stop barge-in until this tag is reached. This tag can only be used in a Voice Gateway Markup Language Text response.

<speak>Hey there, This is important and you must listen to it. 
<mark name='partial_barge_in'/> 
You can now barge-in?</speak>

Recognition Hint

Use the Recognition Hint command to provide a dynamic grammar hint to the speech recognizer about what to detect, which improves the speed and accuracy of recognition, rather than operating in open recognition mode.

{
  "voicegateway": [
    {
      "command": {
        "recognitionhint": {
          "phrases": [
            "cabernet sauvignon",
            "alfalfa"
          ]
        }
      }
    }
  ]
}

Say Command

Use the Say command to use a Supported Text to Speech Engine to synthesize and “Say” the provided input on the active call, with input being a plain text string or, optionally, a Voice Gateway Markup Language formatted string. The Voice Gateway Markup Language eables the bot to pass any SSML command to the TTS engine.

Note:

Voice Gateway Markup Language only influences output where the underlying speech engine supports the language and the specific capabilities requested.

Precedence

"Say" overrides standard bot response text or audioResponse, instructing the Oracle® Intelligent Communication Orchestration Network to synthesize the speech with a nominated speech engine, including Voice Gateway Markup Language.

Speaking Plain Text String

{
    "voicegateway": [{
        "command": {
            "say": {
                "text": "Thanks for confirming you want 12345 Items"
            }
        }
    }]
}

Speaking an SSML String

{
    "voicegateway": [{
        "command": {
            "say": {
                "ssml": "<speak>Thanks for confirming you want <say-as interpret-as=\"cardinal\">12345</say-as> Items</speak>"
            }
        }
    }]
}

Set Barge-In

Use the Set Barge-In command to enable and disable Barge-In at any time during the lifecycle of the call, providing the flexibility to allow or disallow barge-in during the call when required.

 {
    "voicegateway": [{
        "command": {
            "setbargein": {
                "allowed": "false"
            }
        }
    }]
}

Set No Input Timer

Use the Set No Input Timer Command configure the duration of the No Input Timer, controlling how long the platform will wait for input either through DTMF or Speech before triggering a no input event.

{
  "voicegateway": [
    {
      "command": {
        "setnoinputtimer": {
          "seconds": "20"
        }
      }
    }
  ]
}

Configure Speech Recognition

Use the Configure Sppech Recognition command to instruct Oracle® Intelligent Communication Orchestration Network to configure the behavior of the Speech Recognizer, including attributes such as the recognition model to use.

Supported attributes:

Model Name
Language Code
Dumping Utterance Audio to Disk

{
  "voicegateway": [
    {
      "command": {
        "setspeechrec": {
          "modelname": "latest_long"
        }
      }
    },
    {
      "command": {
        "setspeechrec": {
          "singleutterance": "true"
        }
      }
    },
    {
      "command": {
        "setspeechrec": {
          "languagecode": "en-AU"
        }
      }
    }
  ]
}

Configure Speech Synthesis

Use the Speech Synthesis command to configure the default behavior of the speech synthesizer when speaking plain text strings received from the bot during Voice Gateway interactions.

The speech synthesis command does not validate any of the arguments, such as voice name, and assumes the value provided is valid for the selected speech engine.

Voice Gateway Markup Language attributes such as voice will override speech synthesis and the Voice Gateway Markup Language specified voice will be used instead of the configured voice at a Voice Gateway session level.

{
    "voicegateway": [{
        "command": {
            "setspeechsynth": {
                "voicename": "en-AU-Wavenet-A"
            }
        }
    }
  ]
}

Substitute Value

Use the Substitute Value command to configure a runtime variable substitution within the Voice Gateway Markup Language before it is sent to the Speech Synthesizer, allowing the replacement of strings with a specific value at runtime.

{
  "voicegateway": [
    {
      "command": {
        "substitute": {
          "token": "$$FILE_PATH_MCP$$/ifyourdonejustsaythatsall.wav",
          "value": "https://www.myurl.com/tech/piano2.wav"

        }
      }
    },
    {
      "command": {
        "substitute": {
          "token": "$$FILE_PATH_PHONE_BOT$$/OrSayThatsAll.wav",
          "value": "https://www.myurl.com/tech/piano2.wav"
        }
      }
    }
  ]
}

Events

The Voice Gateway supports the following events:

VG_WELCOME—Used on the initial call arrival.
VG_NO_INPUT—Used when no input is detected.
VG_NO_MATCH—Used when the DTMF digits do not meet the minimum length requirement.
VG_RECORDING—Used when a recording event is completed.
VG_ERROR—Used when an error occurs within the Voice Gateway while handling a call. Includes include a parameter with further information about the errors.

A Voice Gateway Markup Language Commands