Contribute in GitHub:

Defining actions and states

The IBM® Voice Gateway API provides action tags and state variables that you define within the dialog in the IBM Watson™ Assistant service. Action tags initiate actions that Voice Gateway takes during a conversation session, and state variables define Voice Gateway characteristics that persist throughout the conversation unless otherwise changed.

Editing JSON in the Watson Assistant dialog response

Both actions and states are defined within the Watson Assistant service in a dialog node response in JSON format. To edit the JSON code, you need to open the JSON editor.

From the IBM® Cloud dashboard, select your Watson Assistant service instance.
Launch the Watson Assistant tool.
Click the workspace that contains the dialog you want to edit.
Go to the Dialog tab, and select the node where you want to set an action or state.
In the response, click the Advanced response icon (⋮), and select Open JSON editor.

Within the JSON editor, you can define actions on the output property and states on the context property as described in the following sections.

Initiating actions

To initiate actions in the Voice Gateway during a call, you can define action tags on a Watson Assistant dialog node in JSON format on the output property. You can define either a single action on the vgwAction tag or a sequence of actions on the vgwActionSequence tag. Each action consists of a command property, followed by an optional parameter property to define attributes for commands that require them.

For a full list of action commands and attributes, see Action tags and state variables in the Voice Gateway API.

Important: Action tags can't be defined in a node that uses deprecated state variables. When you change your node definitions to use the action tags, be sure to update the entire JSON node definition. Your overall dialog can contain a mixture of nodes that use each approach.

Action tags are available in Voice Gateway 1.0.0.2 and later.

Single actions

To perform a single action, define the action in the vgwAction tag with any necessary parameter attributes. In the text block in the output property, you can optionally include an utterance that Voice Gateway plays after the action is performed.

The following single action on the vgwAction tag tells the Voice Gateway to hang up the call when the node response is triggered. Because the vgwActHangup command has no parameters, none are defined.

{
  "output": {
    "vgwAction": {
      "command": "vgwActHangup"
    }
  }
}

The following action tells the Voice Gateway to play the defined text to the caller, and then transfer the call to the defined transfer target.

{
  "output": {
    "text": {
      "values": [
        "Transferring your call."
      ]
    },
    "vgwAction": {
      "command": "vgwActTransfer",
      "parameters": {
        "transferTarget": "tel:+18883334444"
      }
    }
  }
}

Action sequences

To perform one or more actions on a single conversation turn, you can define a sequence of actions within the vgwActionSequence tag as a JSON list. The actions are performed in the order that you define them.

Note: For Voice Gateway to play an utterance when using the vgwActionSequence tag, the list of actions must contain the vgwActPlayText action. In contrast to the vgwAction tag, an utterance in the output.text field isn't automatically played.

In the following more complex example, the Voice Gateway plays the utterance, and then the actions defined on the vgwActionSequence tag tell the Voice Gateway to disable Speech to Text processing and collect dual-tone multi-frequency signaling (DTMF) input.

{
  "output": {
    "text": {
        "values": [
          "Enter your social security number."
        ]
    },
    "vgwActionSequence": [
      {
        "command": "vgwActPauseSTT"
      },
      {
        "command": "vgwActCollectDTMF",
        "parameters": {
          "dtmfTermKey": "#"
        }
      },
      {
        "command": "vgwActPlayText"
      }
    ]
  }
}

Defining actions in the dialog context

You can alternatively define the vgwAction and vgwActionSequence tags on the context property within the Watson Assistant dialog. Certain Watson Assistant service features, such as dialog slots, might require that you specify an action in the dialog context. This capability is supported in Version 1.0.0.5 and later.

Important notes:

Action tags that are defined on the output property take precedence over the tags that you define on the context property. If you specify any action or action sequence on the output property, any actions or action sequences in the context property are ignored.
When the vgwAction and vgwActionSequence tags are specified on the context property, they are not preserved between turns. Voice Gateway removes these tags from the context when it'ssues a new turn to Watson Assistant.

In the following example, the vgwPostResponseTimeoutCount state variable sets the post-response timeout to 3000 milliseconds, and the vgwActHangup action command hangs up the call.

"context": {
  "vgwPostResponseTimeoutCount": "3000",
  "vgwAction": {
    "command": "vgwActHangup"
  }
}

Setting states

To indicate a change of state that remains between conversation turns, Voice Gateway exchanges state variables with the configured Watson Assistant service. These state variables are defined on a dialog node as context variables in JSON format.

For a full list of state variables, see Action tags and state variables in the Voice Gateway API.

For example, the following state variable tells Voice Gateway that starting from this node response, failed call transfers don't end the call but instead force a new conversation turn so a different action can be taken.

{
  "context": {
    "vgwDisconnectCallOnTransferFailure": "No"
  }
}

Voice Gateway assumes that Watson Assistant is stateless and that all state is maintained at Voice Gateway between exchanges with Watson Assistant. This means that for each turn within a single call, the state is passed to Watson Assistant and received back from Watson Assistant in the context section of the REST messages.