定義動作和狀態

IBM® Voice Gateway API 提供動作標籤和狀態變數，可讓您定義在 IBM Watson™ Assistant 服務中的對話內。在交談階段作業期間，動作標籤會起始 Voice Gateway 要採取的動作，而狀態變數則用來定義在整個交談期間要持續保存的 Voice Gateway 性質（除非另行變更）。

編輯 Watson Assistant 對話回應中的 JSON

動作和狀態會以 JSON 格式同時定義在 Watson Assistant 服務內的對話節點回應中。如果要編輯 JSON 程式碼，您需要開啟 JSON 編輯器。

從 IBM® Cloud 儀表板，選取您的 Watson Assistant 服務實例。
啟動 Watson Assistant 工具。
按一下含有您要編輯之對話的工作區。
移至對話標籤，選取您要在其中設定動作或狀態的節點。
在回應中，按一下進階回應圖示 (⋮)，並選取開啟 JSON 編輯器。

在 JSON 編輯器內，您可以依照下列各節的說明，在 output 內容上定義動作，以及在 context 內容上定義狀態。

起始動作

在通話期間，如果要在 Voice Gateway 中起始動作，您可以在 output 內容中以 JSON 格式，在 Watson Assistant 對話節點上定義動作標籤。您可以在 vgwAction 標籤上定義單一動作，或是在 vgwActionSequence 標籤上定義一系列的動作。每一個動作各包含一個 command 內容，後面接著選用的 parameter 內容，用來為需要屬性的指令定義這些屬性。

如需完整的動作指令和屬性清單，請參閱 Voice Gateway API 中的動作標籤和狀態變數。

重要事項：如果節點使用已淘汰的狀態變數，就無法在該節點中定義動作標籤。當您將節點定義變更為使用動作標籤時，請務必更新整個 JSON 節點定義。整個對話中可以混合了使用每一種方式的節點。

動作標籤提供於 Voice Gateway 1.0.0.2 版及更新版本中。

單一動作

如果要執行單一動作，請在 vgwAction 標籤中，使用任何必要的參數屬性來定義動作。在 output 內容的 text 區塊中，您可以選擇性地包含話語，以便在執行動作之後，讓 Voice Gateway 播放。

以下是 vgwAction 標籤上的單一動作，告知 Voice Gateway 在觸發節點回應時掛斷通話。由於 vgwActHangup 指令沒有參數，因此未定義任何參數。

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

下列動作是告知 Voice Gateway 播放所定義的文字給發話端，然後將通話轉接給所定義的轉接目標。

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

動作順序

如果要對單回交談執行一或多個動作，您可以在 vgwActionSequence 標籤內，以 JSON 清單形式定義一系列的動作。動作會依照您定義的順序來執行。

附註：當使用 vgwActionSequence 標籤時，如果要讓 Voice Gateway 播放話語，動作清單必須包含 vgwActPlayText 動作。不同於 vgwAction 標籤，並不會自動播放 output.text 欄位中的話語。

在下列較複雜的範例中，Voice Gateway 會播放話語，且 vgwActionSequence 標籤上所定義的動作告知 Voice Gateway 停用 Speech to Text 處理程序，並收集雙音多頻信號 (DTMF) 輸入。

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

在對話環境定義中定義動作

或者，您可以在 Watson Assistant 對話內的 context 內容上，定義 vgwAction 和 vgwActionSequence 標籤。某些 Watson Assistant 服務特性（例如對話介面槽）可能需要您在對話環境定義中指定動作。1.0.0.5 版及更新版本中支援此功能。

重要注意事項：

對於定義於 output 內容上的動作標籤，其優先順序高於您在 context 內容上所定義的標籤。如果您在 output 內容上指定任何動作或動作順序，則會忽略 context 內容中的任何動作或動作順序。
當在 context 內容上指定 vgwAction 和 vgwActionSequence 標籤時，各回交談之間並不會保留這些標籤。當 Voice Gateway 對 Watson Assistant 發出新一回的交談時，它會將這些標籤從環境定義移除。

在下列範例中，vgwPostResponseTimeoutCount 狀態變數將回應後的逾時值設為 3000 毫秒，且 vgwActHangup 動作指令會掛斷通話。

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

設定狀態

為了指出各回交談之間所維持的狀態已變更，Voice Gateway 會與所配置的 Watson Assistant 服務交換狀態變數。這些狀態變數會以環境定義變數形式，以 JSON 格式定義在對話節點上。

如需完整的狀態變數清單，請參閱 Voice Gateway API 中的動作標籤和狀態變數。

舉例來說，下列狀態變數會告知 Voice Gateway，從這個節點回應開始，通話轉接失敗並不會結束通話，而會強制進行新一回的交談，以便可以採取不同的動作。

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

Voice Gateway 會假設 Watson Assistant 是無狀態的，且在與 Watson Assistant 的各次交換之間，所有的狀態都是在 Voice Gateway 中維護的。也就是說，會針對單次通話內的每一回交談，將狀態放在 REST 訊息的 context 區段中傳遞給 Watson Assistant，再從 Watson Assistant 收回。