從 Voice Gateway 報告轉錄事件

對於自助式代理程式和代理程式助理，IBM® Voice Gateway 提供即時存取通話中之轉錄文字的功能。在許多情況下，轉錄通話可能有其價值，包括：

在進行交談時加以監視
記載交談並於之後分析，例如，細部調整您的 Watson 服務，使客戶有更好的體驗

您可以將 Voice Gateway 配置成將轉錄訊息產生成 REST 事件，並將它們發佈至所配置的 REST 伺服器。在 1.0.0.2 版及更新版本中提供這種方法。在 1.0.0.6 版以及更新版本中，您也可以將 Voice Gateway 配置成直接發佈轉錄事件至 IBM Cloudant。每一個轉錄事件都含有話語文字、信任評分，以及階段作業資訊。如需轉錄事件內容和格式的相關資訊，請參閱報告事件。

將 Voice Gateway 配置成發佈轉錄事件
將 Voice Gateway 配置成發佈轉錄事件至 IBM Cloudant 資料庫
將 Voice Gateway 配置成發佈轉錄事件至 CouchDB
在報告事件中抑制轉錄文字
轉錄事件格式
Voice Gateway 產生的 SMS Gateway 轉錄事件

將 Voice Gateway 配置成發佈轉錄事件

設置 Splunk HTTP Event Collector (HEC) 或可用來儲存事件（例如，儲存在 noSQL 資料庫中）的 REST 伺服器。
配置 REST 伺服器 URL 和授權認證，並在 Voice Gateway 中啟用轉錄事件。
- 單租戶環境：在您的配置中設定下列環境變數。
```
REPORTING_URL=http://myresteventserver.ibm.com/
REPORTING_USERNAME=myRestAdmin
REPORTING_PASSWORD=myRestTokenOrPassword
REPORTING_TRANSCRIPTION_EVENT_INDEX=transcription
```
- 多租戶 JSON 配置：在多租戶 JSON 配置檔中，針對您想啟用轉錄報告的每一個租戶，配置一個含有下列內容的 reporting 物件。您可以在相同物件內，針對其他類型的報告事件配置索引。
```
...
"reporting": {
 "url": "http://myresteventserver.ibm.com/",
 "username": "myRestAdmin",
 "password": "myRestTokenOrPassword",
 "transcriptionEventInd": "transcription"
}
...
```
轉錄事件索引值會以 index 值形式，包含在所有轉錄事件中，以便讓取用它們的 REST 伺服器能夠區分事件的類型。針對 Splunk HEC，索引欄位是必要的；不過，任何人只要想建置自己的 REST 伺服器來處理這些事件，則索引欄位也很有用。

重新部署 Voice Gateway 之後，每當偵測到話語，它就會將事件記錄發佈至所配置的 REST 伺服器。

將 Voice Gateway 配置成發佈轉錄事件至 IBM Cloudant 資料庫

將 Voice Gateway 配置成發佈至 IBM Cloudant 之前，請先設置 IBM® Cloudant® for IBM Cloud。在您從 IBM Cloudant 儀表板產生服務認證時，您可以選擇使用 IAM，或是 API 金鑰與使用者名稱和密碼的組合。

在您的配置中設定下列環境變數，以便將轉錄事件發佈到 IBM Cloudant 資料庫。您可以在配置中新增 IBM Cloudant 配置變數，以同步使用 IBM Cloudant 和另一項報告服務。

下列範例顯示使用密碼和使用者名稱鑑別來發佈各回交談事件至 IBM Cloudant 的配置。請參閱使用 API 金鑰來進行鑑別。您可以使用 API 金鑰，來配置 IBM Cloudant 的鑑別，作法是新增 REPORTING_TRANSCRIPTION_CLOUDANT_APIKEY 變數，或是新增 REPORTING_TRANSCRIPTION_CLOUDANT_USERNAME 和 REPORTING_TRANSCRIPTION_CLOUDANT_PASSWORD，以使用使用者名稱和密碼。

單租戶環境：在您的配置中設定下列環境變數。
```
REPORTING_TRANSCRIPTION_CLOUDANT_USERNAME=myCloudantUsername
REPORTING_TRANSCRIPTION_CLOUDANT_PASSWORD=myCloudantPassword
REPORTING_TRANSCRIPTION_CLOUDANT_DB_NAME=myCloudantDB
REPORTING_TRANSCRIPTION_CLOUDANT_EVENT_INDEX=transcription
```
如果您對 IBM Cloudant 使用非預設帳戶配置，您可能需要包含其他的環境變數。請參閱報告事件配置中的 REPORTING_TRANSCRIPTION_CLOUDANT_URL 和 REPORTING_TRANSCRIPTION_CLOUDANT_ACCOUNT。
多租戶 JSON 配置：在多租戶 JSON 配置檔中，針對您想啟用轉錄事件的每一個租戶，配置一個含有下列內容的 reporting 物件。如果您對 IBM Cloudant 使用非預設帳戶配置，您可能需要包含其他的環境變數。請參閱 reporting 物件的內容中的 transcriptionCloudant。
```
...
"reporting": {
    "transcriptionCloudant": {
    "username": "myCloudantUsername",
    "password": "myCloudantPassword",
    "dbName": "myCloudantDB",
    "eventInd": "transcription"
  }
}
...
```

使用 API 金鑰來進行鑑別

除了使用您 IBM Cloudant 認證的使用者名稱與密碼組合，另一種替代作法是使用 API 金鑰來進行鑑別。您可以尋找或產生對 IBM Cloudant 的服務認證，然後將 URL 和 API 金鑰值複製到 Voice Gateway 報告事件配置中。如需 API 金鑰的相關資訊，請參閱 IBM Cloudant：API 金鑰。

單租戶環境：在您的配置中設定下列環境變數。

REPORTING_TRANSCRIPTION_CLOUDANT_URL=http://mytranscriptioncloudant.ibm.com/
REPORTING_TRANSCRIPTION_CLOUDANT_APIKEY=a1b2c3d3fgh1jk1mn0
REPORTING_TRANSCRIPTION_CLOUDANT_DB_NAME=myCloudantDB
REPORTING_TRANSCRIPTION_CLOUDANT_EVENT_INDEX=transcription

多租戶 JSON 配置：您必須配置 url 和 apikey 配置變數，而非配置 username 和 password。

...
"reporting": {
  "transcriptionCloudant": {
  "url": "http://mytranscriptioncloudant.ibm.com/",
  "apikey": "a1b2c3d3fgh1jk1mn0",
  "dbName": "myCloudantDB",
  "eventInd": "transcription"
}
}
...

將 Voice Gateway 配置成發佈轉錄事件至 CouchDB

如果要設置 CouchDB，請複製儲存庫，並遵循 Github 上的指示。如果您使用 CouchDB，則無法使用 API 金鑰進行鑑別。

在您的配置中設定下列環境變數，以便將轉錄事件發佈到 CouchDB 資料庫。您可以在配置中新增 CouchDB 配置變數，以同步使用 CouchDB 和另一項報告服務。

下列範例顯示的配置是使用密碼和使用者名稱鑑別，將各回交談事件發佈至 CouchDB。

單租戶環境：在您的配置中設定下列環境變數。

REPORTING_TRANSCRIPTION_CLOUDANT_URL="http://<svc-couchdb>:5984/"
REPORTING_TRANSCRIPTION_CLOUDANT_USERNAME=myCouchDBUsername
REPORTING_TRANSCRIPTION_CLOUDANT_PASSWORD=myCouchDBPassword
REPORTING_TRANSCRIPTION_CLOUDANT_DB_NAME=myCouchDB
REPORTING_TRANSCRIPTION_CLOUDANT_EVENT_INDEX=transcription

多租戶 JSON 配置：在多租戶 JSON 配置檔中，針對您想啟用轉錄事件的每一個租戶，配置一個含有下列內容的 reporting 物件。如果您對 IBM Cloudant 使用非預設帳戶配置，您可能需要包含其他的環境變數。請參閱 reporting 物件的內容中的 transcriptionCloudant。

...
"reporting": {
      "transcriptionCloudant": {
      "url": "http://<svc-couchdb>:5984/",
    "username": "myCouchDBUsername",
    "password": "myCouchDBPassword",
    "dbName": "myCouchDB",
    "eventInd": "transcription"
  }
}
...

在報告事件中抑制轉錄文字

您可以透過程式，使用 vgwActEnableTranscriptionReport 和 vgwActDisableTranscriptionReport，以便在報告事件中啟用或抑制轉錄文字。利用這些動作標籤，您可以將 Watson Assistant 配置成在報告事件中啟用或抑制文字併入，以阻止從發話端收集任何個人或機密性資訊。

在下列範例中，動作順序會先停用接收端 callee，然後同時停用 caller 和 callee。最後，只啟用 callee。

"vgwActionSequence": [
      {
        "command": "vgwActDisableTranscriptionReport",
      "parameters": {
        "targets": [
          "callee"   // disable just the callee
        ]
      }
    },
    {
      "command": "vgwActDisableTranscriptionReport",
      "parameters": {
        "targets": []  // disable both callee and caller
      }
    },
    {
      "command": "vgwActEnableTranscriptionReport",
      "parameters": {
        "targets": [
          "callee"    // enable just the callee
        ]
      }
    }]

轉錄事件格式

所有 Voice Gateway 報告事件都是以 Splunk HTTP Event Controller JSON 格式為基礎。

重要事項：轉錄事件包含文字轉錄和其他資訊，且這些資訊可能含有「受保護的健康資訊 (PHI)」、個人識別資訊 (PII) 或「PCI 資料安全標準 (PCI DSS)」資料。因此，耗用端伺服器適當儲存這些事件以防個人資訊曝光，就很重要。

在下列範例中，轉錄事件的 JSON 物件顯示已在 SIPREC 階段作業中，將話語傳送給 Watson Assistant。

{
  "time": 1558628246.008,
  "host": "9.42.89.143",
  "source": "sip:18883141589@114.589.797.1",
  "sourcetype": "sipURI",
  "index": "transcription",
  "event": {
    "transcription": "Good morning",
    "globalSessionID": "0dzMpLgyJ5",
    "sipCallID": "0dzMpLgyJ5",
    "sipRecCallID": "1232673994_41860201@115.110.121.1",
    "sipFromURI": "sip:18883141589@114.589.797.1",
    "sipToURI": "sip:18882718281@182.845.045.2",
    "conversationID": "a23de67h-d2da-4fc7-8a04-a868d760671e",
    "customSIPInviteHeaders": {
      "Custom-Header1": "123",
      "Custom-Header2": "456"
    },
    "destination": "a23de67h-d2da-4fc7-8a04-a868d760671e",
    "destinationType": "conversationID",
    "sttConfig": {
      "confidenceScoreThreshold": 0.7,
      "credentials": {
        "password": "***",
        "username": "3b36c01c-6dfb-4cb6-9a7f-ea4fafd1b2f1"
      },
          "config": {
            "smart_formatting": true,
        "model": "en-US_NarrowbandModel",
        "profanity_filter": true
      }
    },
    "confidence": 0.94,
    "dtmf": false,
    "sttResponse": {
      "result_index": 0,
      "results": [
        {
          "final": true,
      "alternatives": [{
        "transcript": "Good morning",
              "confidence": 0.94
            }
          ]
        }
      ]
    },
    "speechRecognitionLatency": 800,
    "disabled": "false"
  }
}

在下列範例中，轉錄事件 JSON 物件顯示已在自助式階段作業中，將音訊 URL 播放給發話端。

{
  "time": 1558626870.906,
  "host": "192.168.0.3",
  "source": "e165e846-a2f6-493a-94e5-544647af81a8",
  "sourcetype": "conversationID",
  "index": "trx",
  "event": {
    "audioURL": "https://www.example.com/acm/8k16bitpcm.wav",
    "destination": "sip:alice@192.168.0.4",
    "destinationType": "sipURI",
    "sipCallID": "ujtu6PMqLs",
    "globalSessionID": "ujtu6PMqLs",
    "sipToURI": "sip:watson-conversation@192.168.0.3",
    "sipFromURI": "sip:alice@192.168.0.4",
    "assistantID": "bf5a9423-b0d6-437b-bcc4-01f2bc647ca4",
    "conversationLatency": 538,
    "intents": [
      {
        "intent": "One",
        "confidence": 1
      }
    ],
    "ttsConfig": {
      "credentials": {
          "password": "***",
        "username": "e48b9a83-98e2-4499-8db0-e09b2d8f2629"
      }
    },
    "disabled": false
  }
}

事件 meta 資料

所有報告事件都是以下列 meta 資料開頭：

表 1. 事件 meta 資料的索引鍵
索引鍵	說明
`time`	事件的時間。預設格式是 Epoch 時間，採用 <sec>.<ms> 格式。
`host`	產生事件之 Voice Gateway 實例的主機名稱。
`source`	代表產生事件的 Voice Gateway 租戶。一般而言，此值設為受話端的電話號碼。
`sourcetype`	來源類型，會定義成 `e164`（代表電話號碼）、`conversationID`（代表 Watson Assistant 工作區）或 `sipURI`（代表 SIP URI）。
`index`	報告事件索引配置環境變數中所定義的事件索引。
`event`	CDR 事件、Watson Assistant 各回交談事件或轉錄事件。

轉錄事件物件

每一個轉錄事件的 JSON 物件含有下列索引鍵：

表 2. 用來定義轉錄的索引鍵
索引鍵	說明
`transcription`	所轉錄之話語中的文字。
`sipCallID`	從通話相關 SIP INVITE 要求取回的 SIP 通話 ID。
`sipRecCallID`	從 SIPREC meta 資料取出的 SIPREC 通話 ID。必須是 SIPREC 階段作業，此索引鍵才會有一值。
`globalSessionID`	此索引鍵的值視 Voice Gateway 的配置方式而定。依預設，此值與 `sipCallID` 值相同。若有配置 `CUSTOM_SIP_SESSION_HEADER` 環境變數或 `customSIPSessionHeader` JSON 內容，則會對映至該 ID。若為 SIPREC 階段作業，則欄位等同於 SIPREC meta 資料中的 `gcid` 欄位。若為 SIPREC 階段作業，並且已配置 `CUSTOM_SIPREC_SESSION_FIELD` 環境變數或 `customSIPRECSessionField` JSON 內容，就會對映至該欄位。
`conversationID`	Watson Assistant ID。只有在將話語傳送給 Watson Assistant 時，此索引鍵才會有一值。
`customSIPInviteHeader`	自訂 SIP INVITE 標頭的值。如果要設定此值，必須在 `CUSTOM_SIP_INVITE_HEADER` 環境變數中定義標頭欄位，且 INVITE 要求必須包含指定的標頭。1.0.0.5 版及更新版本。
`customSIPInviteHeaders`	自訂 SIP INVITE 標頭的值。如果要設定此值，必須在 `CUSTOM_SIP_INVITE_HEADERS` 環境變數中定義標頭欄位，且 INVITE 要求必須包含指定的標頭。1.0.1 版及更新版本。

`destination`	傳送轉錄時的目的地。
`destinationType`	目的地類型，會定義成 `e164`（代表電話號碼）、`conversationID`（代表 Watson Assistant 工作區）或 `sipURI`（代表 SIP URI）。
`confidence`	來自 Speech to Text 服務之話語的信任評分。1.0.0.3 版及更新版本。
`sipFromURI`	來自起始 SIP INVITE `From` 欄位的 SIP URI。在 SIPREC 階段作業中，會從 SIPREC meta 資料擷取發話端 ID。1.0.0.6a 版及更新版本。
`sipToURI`	來自起始 SIP INVITE `To` 欄位的 SIP URI。在 SIPREC 階段作業中，會從 SIPREC meta 資料擷取發話端 ID。1.0.0.6a 版及更新版本。
`speechRecognitionLatency`	從在發話端語音中偵測到沈默，一直到收到 Speech to Text 的最終結果，這兩者的間隔時間量（毫秒）。若要設定此值，必須將 `STT_LATENCY_TRACKING` 設為 `true`。如果 Media Relay 偵測不到延遲，會在轉錄事件中省略此值。1.0.0.8 版及更新版本。
`disabled`	指出是否在報告事件中包含轉錄事件中的文字。如果設為 `true`，會在報告事件中排除文字。依預設，會設為 `false`。1.0.0.8 版及更新版本。
`audioURL`	已播放給使用者的音訊 URL。1.0.2 版及更新版本。
`mediaURLs`	經由 SMS 通道傳送或接收的媒體 URL 清單。1.0.2 版及更新版本。
`sttConfig`	用於這項交易的 Speech to Text 服務配置。1.0.2 版及更新版本。
`bargeinOccurred`	指出在播放交易期間是否會發生打斷。1.0.2 版及更新版本。
`dtmf`	指出來自使用者的輸入是否為 DTMF。1.0.2 版及更新版本。
`sttResponse`	Speech to Text 服務以 JSON 格式所做出的最終回應，包括最常見假設和任何替代方案的轉錄與信任評分。1.0.2 版及更新版本。
`workspaceID`	Watson Assistant 工作區 ID。1.0.2 版及更新版本。
`assistantID`	Watson Assistant ID。只有在使用 Watson Assistant 第 2 版 API 時，這個索引鍵才具有值。1.0.2 版及更新版本。
`conversationLatency`	從起始與 Conversation 服務的一回交談，一直到收到 Conversation 服務的回應，這兩者的間隔時間量（毫秒）。1.0.2 版及更新版本。
`intents`	使用者輸入中所辨識的意圖陣列，會依遞減信任順序排序。1.0.2 版及更新版本。
`ttsConfig`	用於播放交易的 Text to Speech 服務配置。1.0.2 版及更新版本。
`ttsLatency`	從傳送文字給 Text to Speech 服務，一直到收到第一個音訊片段，這兩者的間隔時間量（毫秒）。1.0.2 版及更新版本。

由 Voice Gateway 產生的 SMS Gateway 轉錄事件

當 Voice Gateway 上已啟用轉錄事件而且有 SMS 訊息到達時，Voice Gateway 會產生轉錄事件，指出轉錄的來源。

在下列範例中，sourcetype 值 sms 指出轉錄是透過 SMS 通道而到達。source 值提供傳送 SMS 訊息的電話號碼。destinationType 指出訊息傳送至 Watson Assistant。

{
  "time": 1531231769,
  "host": "9.16.25.144",
  "source": "+14445556666",
  "sourcetype": "sms",
  "index": "transcription",
  "event": {
    "transcription": "Hello.",
    "sipCallID": "AbcdEF2G~",
    "globalSessionID": "AbcdEF2G~",
    "sipToURI": "sip:watson-conversation@9.95.87.495",
    "sipFromURI": "sip:14448675309@9.40.540.440",
    "destination": "6abcde93-5393-53f9-g430-907hi2j7k936",
    "destinationType": "conversationID"
  }
}

當 Voice Gateway 傳送訊息給 SMS Gateway 時，SMS Gateway 會產生轉錄事件，指出已傳送 SMS 訊息。

在下列範例中，destinationType 值 sms 指出轉錄已傳送至 SMS 訊息中的發話端。destination 值提供 Voice Gateway 傳送 SMS 訊息的目的地電話號碼。

{
  "time": 1531231769,
  "host": "9.16.25.144",
  "source": "6abcde93-5393-53f9-g430-907hi2j7k936",
  "sourcetype": "conversation",
  "index": "transcription",
  "event": {
    "transcription": "Hello.",
    "sipCallID": "AbcdEF2G~",
    "globalSessionID": "AbcdEF2G~",
    "sipToURI": "sip:watson-conversation@9.95.87.495",
    "sipFromURI": "sip:14445556666@9.40.540.440",
    "destination": "+14445556666",
    "destinationType": "sms"  }
}