从对话节点发起程序化调用

要发起程序化调用，请定义 Webhook 以用于将 POST 请求调出发送到执行程序化功能的外部应用程序。然后，您可以从一个或多个对话节点启动网络挂钩。

如果您正在使用操作而不是对话，那么可以使用定制扩展来进行程序化调用。有关更多信息，请参阅调用定制扩展。

Webhook是一种机制，您可以根据程序中的事件调用外部程序。当用于对话时，当助手处理启用了网络挂钩的节点时，网络挂钩就会被触发。 Webhook 会收集指定的数据或在交谈期间从用户那里收集的数据，并将其保存在上下文变量中。它将数据作为 HTTP的一部分发送到您作为网络挂钩定义的一部分指定的 URL。接收 Webhook 的 URL 是侦听器。它执行预定义的操作，使用您在webhook定义中指定的信息，并可选择性地返回响应。

可以使用 Webhook 来执行以下类型的操作：

验证从用户那里收集的信息。
与外部 Web 服务进行交互以获取信息。例如，可以根据空中交通服务查看某个航班的预期到达时间，或者根据天气服务获取天气预报。
向外部应用程序（例如，餐馆预订站点）发送请求，以代表用户完成简单的交易。
触发 SMS 通知。

有关如何调用客户机应用程序的信息，请参阅请求客户机操作。

在使用私有端点的情况下，请记住，网络挂钩通过互联网发送流量。

定义 Webhook

您可以为对话框定义一个URL，然后从一个或多个对话框节点调用网络挂钩。

对外部服务的程序化调用必须满足以下需求：

调用必须是 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，然后添加调出的详细信息。

找到要在其中添加调出的对话节点。每当与用户对话时触发此节点，就会发生网络挂钩的调用。

例如，您可能希望从 #General_Greetings 节点向 Webhook 发送调出。
单击以打开对话节点，然后单击定制。
向下滚动到 Webhook 部分。将 Call out to webhook/actions 开关设置为 On。
选择调用 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	$destination

任何通过调用做出的响应都会保存到返回变量中。可以对自动添加到返回变量字段的变量重命名。如果调出生成错误，那么此变量会设置为 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?

如果标注返回空字符串，表示呼叫成功，但返回的值是空字符串，如果您想对此做出特定响应，可以添加一个条件响应，条件语法如下：
```
$webhook_result_1.size() == 0
```

完成后，单击 X 以关闭节点。这将自动保存您的更改。

测试 Webhook

当您首次添加网络挂钩标注时，查看外部应用程序响应中返回的确切内容、数据及其格式可能很有用。将此表达式添加为成功调用条件响应的文本响应：$webhook_result_n，其中 n 是您正在测试的网络挂钩的相应编号。

此响应会将返回变量的完整主体返回，因此您可以查看调出所发回的内容，并决定要与用户共享的内容。然后，您可以使用 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 并提供动态响应。有关更多信息，请参阅博客文章 How to Dynamically Add Response Options to Dialog Nodes。