处理信息后调用服务 watsonx Assistant

在助手生成回复后，使用消息后 webhook 调用外部服务。

您可以在以下用例中使用消息后网络钩子：

使用自定义操作 ID 从外部源获取响应。
将助手的回复翻译成用户的语言。
重新插入之前为保护隐私而删除的个人数据。

了解更多

有关相关功能和细节的更多信息，请参阅以下资源：

准备工作

您的 Webhook 服务必须满足这些技术要求：

请勿在生产环境中设置或测试 webhook。
调用必须是 POST HTTP 请求。
请求和响应必须使用 JSON 格式（Content-Type: application/json）。
回复必须在 30 秒内返回。

过程

本节介绍为 watsonx Assistant 定义、测试和删除消息后网络钩子的步骤。

Webhook 配置
为后处理配置网络钩子错误处理
测试网络钩子
排除网络钩子故障
请求正文示例
示例 1
示例 2
删除网络钩子

Webhook 配置

要添加 Webhook 详细信息，请完成以下步骤：

从导航面板中单击环境，然后打开要配置 webhook 的环境。
单击打开环境设置。
将“信息发布后 webhook ”开关设置为已启用。
在同步事件中，从以下选项中选择一个：
- 如果出现错误，则继续处理用户输入，不更新 webhook。
- 如果 webhook 调用失败，则向客户端返回错误信息。
更多信息，请参阅为后处理配置 webhook 错误处理。
在 URL 字段中，添加要向其发送 HTTP POST 请求调出的外部应用程序的 URL。

例如，您可以将助理的回复存储在一个单独的内容管理系统中。当助手理解了输入内容后，处理过的操作会返回一个唯一的 ID，该 ID 与 CMS 中的响应相对应。要调用从 CMS 获取指定唯一 ID 响应的服务，请为服务实例指定 URL。例如，https://example.com/get_answer。

您必须指定一个使用 SSL 协议的 URL，因此请指定一个以 https 开头的 URL。
要配置消息后网络钩子的身份验证，请单击编辑身份验证。有关详细说明，请参阅为信息前和信息后网络钩子定义身份验证方法。
在“超时”字段中，指定助手在返回错误前等待网络钩子响应的时间长度（秒）。超时时间不能短于 1 秒或长于 30 秒。

在“标头”部分，单击“添加标头 +”，一次添加一个要传递给服务的标头。

如果您调用的外部应用程序返回响应，它可能会以不同的格式发送响应。网络钩子要求以 JSON 格式作出响应。下表说明了如何添加标头，以表明您希望返回 JSON 格式的结果值。

头示例
头名称	头值
`Content-Type`	`application/json`

保存标题值后，字符串将被星号替换，无法再次查看。
这将自动保存 Webhook 详细信息。

为后处理配置网络钩子错误处理

如果 webhook 调用失败，您可以决定是否在后处理步骤中返回错误信息。您有两个选择：

如果出现错误，则继续处理用户输入，而不更新网络钩子：助手会忽略错误，并在不更新网络钩子结果的情况下处理信息。如果后期处理有用但不是必须的，可以考虑这一选项。
如果 webhook 调用失败，则向客户端返回错误信息：如果在助手发送响应后，后处理至关重要，请选择此选项。

当您启用 “如果 webhook 调用失败则向客户端返回错误” 时，一切都会停止，直到后处理步骤成功完成。

定期测试外部流程，找出潜在故障。如有必要，请调整此设置，以防止响应处理中断。

测试 Webhook

在为生产环境中使用的助手启用网络钩子之前，请对其进行大量测试。

只有当您的助手处理了一条信息并准备好向通道返回响应时，才会触发 webhook。

排除网络钩子故障

以下错误代码可以帮助您找出可能遇到的问题的原因。例如，如果您有一个网络聊天集成，如果您提交的每条测试消息都返回 There is an error with the message you just sent, but feel free to ask me something else 这样的消息，您就知道网络钩子出了问题。如果显示此消息，请使用 cURL, 等 REST API 工具发送测试 /message API 请求，以便查看错误代码和返回的完整消息。

错误代码详情
错误代码和信息	描述
422 Webhook 响应的 JSON 主体无效	网络钩子的 HTTP 响应体无法解析为 JSON 格式。
422 Webhook 响应的状态代码为 `[500]`	您调用的外部服务出现问题。代码失败或外部服务器拒绝了请求。
500 处理器异常：`[connections to all backends failing]`	网络钩子微服务发生错误。无法连接后台服务。

请求正文示例

了解请求后消息 Webhook 主体的格式非常有用，这样外部代码就能对其进行处理。

有效载荷包含助手为 /message 的第 2 版、有状态和无状态 API 调用返回的响应体。事件名称 message_processed 表示消息后网络钩子生成了请求。有关消息请求体的更多信息，请参阅 API 参考资料。

下面的示例展示了一个简单请求正文的格式：

{
 "event": {
    "name": "message_processed"
},
"options": {},
"payload": {
    "output": {
        "intents": [
            {
                "intent": "General_Greetings",
                "confidence": 1
            }
        ],
        "entities": [],
        "generic": [
            {
                "response_type": "text",
                "text": "Hello. Good evening"
            }
        ]
    },
    "user_id": "test user",
    "context": {
        "global": {
            "system": {
                "user_id": "test user",
                "turn_count": 11
            },
            "session_id": "sxxx"
        },
        "skills": {
            "actions skill": {
                "user_defined": {
                    "var": "anthony"
                },
                "system": {
                    "state": "nnn"
                }
            }
        }
    }
}

示例 1

本示例展示了如何在助手的每个响应末尾添加 y'all。

在信息发布后网络钩子配置页面中，可指定以下值：

URL: https://your-webhook-url/
标头名称：Content-Type
标头值：application/json

信息发布后网络钩子调用 IBM Cloud Functions 网络操作，操作名称为 add_southern_charm。

add_southern_charm 网页操作中的 node.js 代码如下：

function main(params) {
  console.log(JSON.stringify(params))
  if (params.payload.output.generic[0].text !== '') {
      //Get the length of the input text
        var length = params.payload.output.generic[0].text.length;
        //create a substring that removes the last character from the input string, which is typically punctuation.
        var revision = params.payload.output.generic[0].text.substring(0,length-1);
        const response = {
            body : {
                payload : {
                    output : {
                        generic : [
                              {
                                  //Replace the input text with your shortened revision and append y'all to it.
                                "response_type": "text",
                                "text": revision + ', ' + 'y\'all.'
                              }
                        ],
                    },
                },
            },
        };
        return response;
  }
  else {
    return {
        body : params
    }
  }
}

示例 2

本例展示了如何将信息回复翻译成客户语言。只有执行例 2 中的步骤，定义一个将原始信息翻译成英文的预发信息 webhook，它才会起作用。

在 IBM Cloud Functions 中定义网络操作序列。序列中的第一个操作是检查原始输入文本的语言，该语言存储在消息前 Webhook 代码中名为 original_input 的上下文变量中。序列中的第二个操作是将对话响应文本从英文翻译成客户使用的原始语言。

在信息发布后网络钩子配置页面中，可指定以下值：

URL: https://your-webhook-url/
标头名称：Content-Type
标头值：application/json

序列中第一个网络操作的 node.js 代码如下：

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))

if (params.payload.output.generic[0].text !== '') {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnnn'
       },
  headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.context.skills['actions skill'].user_defined.original_input
  ],
  json: true,
};
     return rp(options)
    .then(res => {
      //Set the language property of the incoming message to the language that was identified by Watson Language Translator.
        params.payload.context.skills['actions skill'].user_defined['language'] = res.languages[0].language;
        console.log(JSON.stringify(params))
        return params;
})
}
else {
    params.payload.context.skills['actions skill'].user_defined['language'] = 'none';
    return param
}
};

该序列中的第二个网络操作如下：

let rp = require("request-promise");

function main(params) {
  console.log(JSON.stringify(params))
    if ((params.payload.context.skills["actions skill"].user_defined.language !== 'en') && (params.payload.context.skills["actions skill"].user_defined.language !== 'none')) {
    const options = { method: 'POST',
    url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/translate?version=2018-05-01',
    auth: {
            'username': 'apikey',
            'password': 'nnn'
        },
    body: {
        text: [
            params.payload.output.generic[0].text
            ],
            target: params.payload.context.skills["actions skill"].user_defined.language
    },
    json: true
    };
      return rp(options)
      .then(res => {
          params.payload.context.skills["actions skill"].user_defined["original_output"] = params.payload.output.generic[0].text;
          params.payload.output.generic[0].text = res.translations[0].translation;
          return {
            body : params
          }
  })
  }
  return {
    body : params
  }
};

删除网络钩子

如果不想使用网络钩子处理消息响应，请完成以下步骤：

在助手中，转到环境并打开要移除 webhook 的环境。
单击打开环境设置。
在“环境设置”页面，单击“消息后 webhook”。
执行下列其中一个操作：

要停止调用 webhook 来处理每一条收到的信息，请将“信息后 webhook”开关设置为禁用。
要更改要调用的网络钩子，请单击删除网络钩子。