從對話節點進行程式化呼叫

若要進行程式化呼叫，請定義 Webhook，以將 POST 要求外呼傳送至執行程式化功能的外部應用程式。然後，您可以從一個或多個對話節點啟動 webhook。

如果您是使用動作而非對話，則可以使用自訂延伸來進行程式化呼叫。如需相關資訊，請參閱呼叫自訂延伸。

webhook 是一種機制，您可以使用它來根據您程式中的事件呼叫外部程式。在對話框中使用時，當助手處理具有已啟用 webhook 的節點時，會觸發 webhook。 Webhook 會收集指定的資料或在交談期間從使用者處收集到的資料，並將其儲存在環境定義變數中。它會以 HTTP POST 請求的方式，將資料傳送至您在 webhook 定義中指定的 URL。接收 Webhook 的 URL 是接聽器。它會執行預先定義的動作，使用您在 webhook 定義中指定傳送給它的資訊，並可選擇回傳回應。

您可以使用 Webhook 來執行下列類型的作業：

驗證您從使用者收集的資訊。
與外部 Web 服務互動以取得資訊。例如，您可以從空中交通服務查看班機預計抵達的時間，或從氣象服務取得天氣預報。
將要求傳送至外部應用程式（例如餐廳預約網站），以代表使用者完成簡單交易。
觸發 SMS 通知。

如需如何呼叫用戶端應用程式的相關資訊，請參閱要求用戶端動作。

對於使用私人端點的環境，請記住 webhook 會透過網際網路傳送流量。

定義 Webhook

您可以為對話框定義一個 webhook URL，然後從一個或多個對話框節點呼叫 webhook。

對外部服務的程式化呼叫必須符合下列需求：

呼叫必須是 POST HTTP 要求。
要求內文必須是 JSON 物件 (Content-Type: application/json)。
回應必須是 JSON 物件 (Accept: application/json)。
呼叫必須在 8 秒或更短時間內回復。如果透過對話節點在單一訊息呼叫中啟動多次，則所有這些呼叫都必須在 8 秒內傳回。

如果您的外部服務僅支援 GET 要求，或者您需要在執行時間動態指定 URL 參數，請考慮建立中間服務，該服務接受包含任何執行時間值的 JSON 負載的 POST 要求。然後，中間服務可以向目標服務發出請求，將這些值作為 URL 參數傳遞，然後將回應傳回對話方塊。

如果您需要呼叫在 8 秒內可能未傳回的服務，您可以透過自訂用戶端應用程式來管理呼叫，並以個別步驟將資訊傳遞至對話。如需相關資訊，請參閱要求用戶端動作。

若要新增 Webhook 詳細資料，請完成下列步驟：

在您要新增 Webhook 的對話框中，按一下 Webhook。
在 URL 欄位中，新增您要傳送 HTTP POST 要求呼叫的目標外部應用程式 URL。

例如，若要呼叫 Language Translator 服務，請指定服務實例的 URL。
```
https://api.us-south.language-translator.watson.cloud.ibm.com/v3/translate?version=2018-05-01
```
如果您呼叫的外部應用程式傳回回應，它必須能夠以 JSON 格式將回應傳送回來。例如，對於 Language Translator 服務，您必須指定希望傳回結果的格式。作法是將標頭傳遞給服務。

在「標頭」區段中，按一下新增標頭來新增要傳遞給服務的任何標頭，一次新增一個標頭。

例如，此標頭指出要求為 JSON 格式。

標頭範例
標頭名稱	標頭值
`Content-Type`	`application/json`

如果外部服務要求您在要求中傳遞基本鑑別認證，請提供這些認證。請按一下新增授權，將您的認證新增至使用者名稱及密碼欄位，然後按一下儲存。

產品將根據認證建立 Base64 編碼的 ASCII 字串，產生標頭並將其新增到頁面。

標頭範例
標頭名稱	標頭值
授權	基本 `<encoded-credentials>`

如果您使用網路聊天整合並啟用安全性，您可以在授權標頭中使用用於保護網路聊天的相同令牌。如需相關資訊，請參閱 Web 會談：重複使用 JWT 進行 Webhook 鑑別。

您的 Webhook 詳細資料會自動儲存。

將 Webhook 外呼新增至對話節點

若要從對話節點使用 Webhook，您必須在節點上啟用 Webhook，然後新增外呼的詳細資料。

找到要在其中新增外呼的對話節點。只要在與使用者的對話過程中觸發此節點，就會發生對 webhook 的呼叫。

例如，建議您從 #General_Greetings 節點傳送 Webhook 外呼。
按一下以開啟對話節點，然後按一下自訂。
向下捲動至 Webhook 區段。將 對 Webhook/動作外呼 參數設為開啟。
選取呼叫 Webhook，然後按一下套用。

如果您尚未啟用它，多個條件式回應切換會自動設為開啟，而且您無法停用它。啟用此設定是為了支援新增根據 Webhook 呼叫成功或失敗而執行的不同回應。如果您已為節點指定了回應，它會成為第一個條件回應。

在參數區段中，將您要傳遞給外部應用程式的任何資料，新增為索引鍵及值的配對。

參數會作為要求內文內容來傳遞。您無法在對話節點中指定查詢參數或 URL 參數。這些參數只能作為 Webhook 定義的一部分來配置靜態值。如需相關資訊，請參閱定義 Webhook。

例如，如果您呼叫 Language Translator 服務，則必須提供下列參數的值：

參數範例
索引鍵	值	說明
model_id	`en-es`	識別輸入和輸出語言。在此範例中，要求是將英文 (en) 文字翻譯為西班牙文 (es)。
文字	`How are you?`	此參數包含您要服務翻譯的字串。您可以硬編碼此值、傳送上下文變數 (例如 $saved_text)，或直接將使用者輸入傳送至服務，方法是指定 `<? input.text ?>` 為此值。

在更複雜的使用案例中，您可能會在交談期間收集使用者的資訊，例如使用者的旅行計畫。您可以收集日期和目的地資訊，並將其儲存在環境定義變數中，以作為參數傳遞到外部應用程式。

旅行參數範例
索引鍵	值
depart_date	$departure
arrive_date	$arrival
origin	$origin
目的地	$destination

任何由呼出產生的回應都會儲存在 return 變數中。您可以重新命名自動新增至傳回變數欄位的變數。如果外呼導致錯誤，則此變數會設定為 null。

產生的變量名稱的語法是 webhook_result_n，其中 _n 後綴會在您每次新增 webhook 喚出到對話節點時遞增。此命名慣例可確保上下文變數名稱在整個對話框中是唯一的。如果您變更名稱，請務必使用唯一名稱。

在條件式回應區段中，會自動新增兩個回應條件，一個回應在 Webhook 外呼成功時顯示，並送回一個傳回變數。另一個回應在外呼失敗時顯示。您可以編輯這些回應，也可將更多條件式回應新增至節點。

如果外呼傳回回應，而且您知道 JSON 回應的格式，則您可以編輯對話節點回應，使其只包含您要與使用者共用的回應的區段。

例如，Language Translator 服務會傳回與下面類似的物件：

   {
   "translations":[
      {"translation":"¿Cómo estás?"}
   ],
   "word_count":3,
   "character_count":12
   }

使用僅擷取譯文值的 SpEL 表示式。

條件式回應範例
條件	回應
$webhook_result_1	你用西班牙語說:
anything_else	對外部應用程式的呼叫已失敗。請稍後重試。

如果您使用推薦的回應格式，並且傳回之前顯示的翻譯回應，助理對使用者的回應將會是 Your words in Spanish: ¿Cómo estás?

如果您想要在 callout 返回空字串（即呼叫成功，但返回的值是空字串）的情況下提供特定的回應，您可以新增一個有條件的回應，其條件的語法如下：
```
$webhook_result_1.size() == 0
```

完成時，按一下 X 關閉節點。您的變更會自動儲存。

測試 Webhook

當您第一次新增 webhook 呼出時，查看外部應用程式回覆的確切內容、資料及其格式可能很有用。將這個表達式新增為成功呼出條件回應的文字回應：$webhook_result_n，其中 n 是您要測試的 webhook 的適當編號。

此回應會將傳回變數的完整主體傳回，因此您可以查看外呼所送回的內容，並決定要與使用者共用的內容。然後，您可以使用 Expression 語言方法中記錄的方法，只從回應中擷取您關心的資訊。

測試某些使用者輸入是否會在外呼中產生錯誤，並建置處理這些狀況的方式。外部應用程式產生的錯誤會儲存在 output.webhook_error.<result_variable> 中。在測試以擷取這類錯誤時，您可以使用與下面類似的條件式回應：

條件式回應範例
條件	回應
output.webhook_error	呼出產生此錯誤： `<? output.webhook_error.webhook_result_1 ?>`

例如，您可能沒有正確鑑別要求 (401)，或者可能嘗試使用已由外部應用程式使用的名稱來傳遞參數。部署 Webhook 之前，請測試 Webhook 以探索並修正這些類型的錯誤。

移除 Webhook

如果您決定不要從對話節點進行 Webhook 呼叫，請開啟節點的自訂頁面，然後將 Webhook 切換為關閉。

即會從對話節點編輯器移除參數區段和傳回變數欄位。不過，仍會保留為您新增或您自己新增的任何條件式回應。

多個條件式回應 區段又將變為可編輯。您可以選擇關閉此功能。如果您這樣做，則只有第一個條件式回應會儲存為節點的唯一文字回應。

若要變更從對話節點呼叫的外部服務，請編輯選項標籤的 Webhook 頁面上定義的 Webhook 詳細資料。如果新服務預期向其傳遞不同的參數，則請務必更新呼叫該服務的所有對話節點。

使用 Webhook 更新 output.generic

您可以使用 Webhook 來更新 output.generic 並提供動態回應。如需相關資訊，請參閱部落格文章如何動態新增回應選項至對話節點。