Webhook 配置

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

1. 从导航面板中单击环境，然后打开要配置 webhook 的环境。

2. 单击 打开环境设置。

3. 将预发信息 webhook 开关设置为已启用。

4. 在同步事件中，从以下选项中选择一个：

   • 如果出现错误，则继续处理用户输入，不更新 webhook。

   • 如果 webhook 调用失败，则向客户端返回错误信息。

   更多信息，请参阅“为预处理配置 webhook 错误处理”。

5. 在 URL 字段中，添加要向其发送 HTTP POST 请求调出的外部应用程序的 URL。

   例如，您可以编写一个 Cloud Functions 网页操作，检查信息是否使用英语以外的语言，然后将其发送到 Language Translator 服务，将其转换为英语。 为网络操作指定 URL，如本示例所示：

   https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json
   

   您必须指定一个使用 SSL 协议的 URL，因此请指定一个以 https 开头的 URL。

6. 要配置消息前网络钩子的身份验证，请单击编辑身份验证。 有关详细说明，请参阅 为信息前和信息后网络钩子定义身份验证方法。

7. 在“超时”字段中，以秒为单位指定助手在返回错误前等待网络钩子响应的时间长度。 超时时间不能短于 1 秒或长于 30 秒。

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

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

   头示例

   头名称	头值
   Content-Type	application/json

9. 保存标题值后，字符串将被星号替换，无法再次查看。

10. 这将自动保存 Webhook 详细信息。

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

如果 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 请求，以便查看错误代码和返回的完整消息。

请求正文示例

了解预消息网络钩子请求体的格式非常有用，这样您的外部代码就可以处理它。

有效载荷包含 /message、有状态或无状态、第 2 版 API 请求的请求正文。 事件名称 message_received 表示该请求由预消息 Webhook 生成。 有关消息请求体的更多信息，请参阅 API 参考资料。

{
  "payload" : { Copy of request body sent to /message }
  "event": {
      "name": "message_received"
   }
}

跳过助理处理

消息前网络钩子的增强功能允许 Cloud Pak for Data 跳过消息处理，直接返回网络钩子的响应。 通过在网络钩子的 HTTP 响应中设置 x-watson-assistant-webhook-return 标头，可激活该功能。

响应主体

从 webhook 接收 POST 请求的服务必须返回一个 JSON 对象 (Accept: application/json)。

回复正文必须具有以下结构：

{
  "payload": {
    ...
  }
}

payload 必须包括请求正文中的 payload。 您的代码可以修改属性值或修改上下文变量，但返回的消息有效载荷必须遵循 message 方法模式。 更多信息，请参阅 API 参考。

示例 1

本例向您展示如何检查输入文本的语言，并将语言信息附加到输入文本字符串。

在预消息 webhook 配置页面中，可指定以下值：

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language
• 标头名称：Content-Type
• 标头值：application/json

消息前网络钩子调用 IBM Cloud Functions 网络操作，操作名称为 check_language。

check_language 网页操作中的 node.js 代码如下。

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

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
  // Send a request to the Watson Language Translator service to check the language of the input 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': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        //Append "in" plus "the language code" to the input text, surrounded by parentheses.
        const response = {
            body : {
                payload : {
                    input : {
                        text : params.payload.input.text + ' ' + '(in ' + res.languages[0].language + ')'
                    },
                },
            },
        };
        return response;
})
}
return {
    body : params
}
};

要测试网络钩子，请单击“预览”。 提交文本 Buenos días。 助手可能无法理解输入内容，因此会返回 Anything else 节点的响应。 不过，如果您进入助手的“分析”页面并打开“对话”，就可以看到提交的内容。 查看最近的用户对话。 日志显示用户输入为 Buenos días (in es)。 括号中的 es 代表西班牙语的语言代码，因此网络钩子成功识别出提交的文本是西班牙语短语。

示例 2

本例向您展示了如何检查收到的信息的语言，如果不是英语，则在提交给助手之前将其翻译成英语。

在 IBM Cloud Functions 中定义网络操作序列。 序列中的第一个操作是检查输入文本的语言。 序列中的第二个动作是将文本从原文翻译成英文。

在预消息 webhook 配置页面中，可指定以下值：

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence
• 标头名称：Content-Type
• 标头值：application/json

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

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

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.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': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  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 params
}
};

序列中的第二个网络操作将文本发送到 Watson Language Translator 服务，将输入文本从上一个网络操作中识别的语言翻译成英语。 翻译后的字符串会发送给您的助手，而不是原始文本。

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

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

function main(params) {
console.log(JSON.stringify(params))
//If the the incoming message is not null and is not English, translate it.
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'
       },
  headers: {
    "Content-Type":"application/json"
  },
       //The body includes the parameters that are required by the Language Translator service, the text to translate and the target language to translate it into.
  body: {
      text: [
          params.payload.input.text
          ],
          target: 'en'
  },
  json: true
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["original_input"] = params.payload.input.text;
        const response = {
            body : {
                payload : {
                    "context" : params.payload.context,
                    "input" : {
                        "text" : res.translations[0].translation,
                        "options" : {
                            "export" : true
                            }
                    },
                },
            },
        };
    return response
})
}
return {
    body : params
    }
};

在预览面板中测试网络钩子时，您可以提交 Buenos días，助手就会像您用英语说 Good morning 一样做出回应。 事实上，当您查看助手的“分析”页面并打开“对话”时，日志会显示用户输入的内容是 Good morning。

您可以添加一个信息后 webhook，在显示信息之前将信息回复翻译成客户的语言。 更多信息，请参见 示例 2。

示例 3

本例展示了如何编写网络钩子响应，让 Cloud Pak for Data 跳过处理消息，直接返回网络钩子的响应。

function main(params) {
  // Your custom logic to determine the response
  let responseText = "This response is directly from the pre-message webhook.";

  const response = {
    headers: {
      "X-Watson-Assistant-Webhook-Return": "true"
    },
    body: {
      output: {
        generic: [
          {
            response_type: "text",
            text: responseText
          }
        ]
      }
    }
  };

  return response;
}

删除网络钩子

如果不想用网络钩子预处理客户输入，请完成以下步骤：

1. 在助手中，转到环境并打开要移除 webhook 的环境。

2. 单击 打开环境设置。

3. 在“环境”设置页面，单击“预发消息 webhook”。

4. 执行下列其中一个操作：

• 要停止调用 webhook 来处理每一条收到的信息，请将“信息前 webhook”开关设置为禁用。

• 要更改要调用的网络钩子，请单击删除网络钩子。