Making a call before processing a message

Defining the webhook

You can define one webhook URL to use for preprocessing every incoming message.

The programmatic call to the external service must meet these requirements:

• The call must be a POST HTTP request.
• The request body must be a JSON object (Content-Type: application/json).
• The call must return in 30 seconds or less.

If your external service supports only GET requests, or if you need to specify URL parameters dynamically at run time, consider creating an intermediate service that accepts a POST request with a JSON payload containing any runtime values. The intermediate service can then make a request to the target service, passing these values as URL parameters, and then return the response to the dialog.

Do not set up and test your webhook in a production environment where the assistant is deployed and is interacting with customers.

To add the webhook details, complete the following steps:

1. From your assistant, click the icon, and then choose Settings.

2. Click Webhooks > Pre-message webhook.

3. Set the Pre-message webhook switch to Enabled.

4. Decide whether to return an error if the webhook call fails.

   When enabled, everything stops until the preprocessing step is completed successfully.

   • If you have a critical preprocessing step that must be taken before you want to allow the message to be processed by the assistant, enable this setting.

     Take steps to test the process that you are calling on a regular basis so you will know if it's down, and can change this setting to prevent all of your message calls from failing.

   • When this setting is disabled, the assistant ignores any errors it encounters and continues to process the incoming message without taking the preprocessing step. If the preprocessing step is helpful but not critical, consider keeping this setting disabled.

5. In the URL field, add the URL for the external application to which you want to send HTTP POST request callouts.

   For example, you might write a Cloud Functions web action that checks whether a message is in a language other than English, and if so, send it to the Language Translator service to covert it to English. Specify the URL for your web action.

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

   You must specify a URL that uses the SSL protocol, so specify a URL that begins with https.

   You cannot use a webhook to call a Cloud Functions action that uses token-based Identity and Access Management (IAM) authentication. However, you can make a call to a Cloud Functions web action or a secured web action.

6. In the Secret field, add a private key to pass with the request that can be used to authenticate with the external service.

   The key must be specified as a text string, such as purple unicorn. Maximum length is 1,024 characters. You cannot specify a context variable.

   It is the responsibility of the external service to check for and verify the secret. If the external service does not require a token, specify any string you want. You cannot leave this field empty.

   If you want to see the secret as you enter it, click on the Show password icon before you start typing. After you save the secret, the string is replaced by asterisks and can't be viewed again.

   For more information about how this field is used, see Webhook security.

7. In the Timeout field, specify the length of time (in seconds) you want the assistant to wait for a response from the webhook before returning an error. The timeout duration cannot be shorter than 1 second or longer than 30 seconds.

8. In the Headers section, add any headers that you want to pass to the service one at a time by clicking Add header.

   For example, if the external application that you call returns a response, it might be able to send a response in multiple different formats. The webhook requires that the response is formatted in JSON. The following table illustrates how to add a header that indicates that you want the resulting value to be returned in JSON format.

   Header example

   Header name	Header value
   Content-Type	application/json

   The service automatically sends an Authorization header with a JWT; you do not need to add one. If you want to handle authorization yourself, add your own authorization header and it will be used instead.

   After you save the header value, the string is replaced by asterisks and can't be viewed again.

Your webhook details are saved automatically.

Testing the webhook

Do extensive testing of your webhook before you enable it for an assistant that is being used in a production environment.

Your assistant must have a skill added to it before your webhook can do anything useful. The webhook is triggered when a message is sent to your assistant to be processed by the associated skill.

If you enable the setting that returns an error when the webhook call fails, the processing of the assistant is halted entirely if the webhook encounters any issues. Take steps to test the process that you are calling on a regular basis so you will be alerted if the external service is down, and can take actions to prevent all of the incoming messages from failing to be received.

If you call an Cloud Functions web action, you can use the logging capability in Cloud Functions to help you troubleshoot your code. You can download the command line interface, and then enable logging with the activation polling command.

Troubleshooting the webhook

The following error codes can help you track down the cause of issues you might encounter. If you have a web chat integration, for example, you will know that your webhook has an issue if every test message you submit returns a message such as There is an error with the message you just sent, but feel free to ask me something else. If this message is displayed, use a REST API tool, such as cURL, to send a test /message API request, so you can see the error code and full message that is returned.

Webhook security

To authenticate the webhook request, verify the JSON Web Token (JWT) that is sent with the request. The webhook microservice automatically generates a JWT and sends it in the Authorization header with each webhook call. It is your responsibility to add code to the external service that verifies the JWT.

For example, if you specify purple unicorn in the Secret field, you might add code similar to this:

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
  // error thrown if token is invalid
}

Request body

It is useful to know the format of the request body of the premessage webhook so that your external code can process it.

The payload contains the request body of the /message (stateful and stateless) v2 API request. The event name message_received indicates that the request is generated by the premessage webhook. For more information about the message request body, see the API reference.

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

Response body

The service that receives the POST request from the webhook must return a JSON object (Accept: application/json).

The response body must have the following structure:

{
  "payload": {
    ...
  }
}

The payload object in the response should contain the payload object that was received in the request body. Your code can modify property values in the message payload it received (for example, to update property values, or to add or remove context variables); but the message payload returned to the service must conform to the schema for a request to the message method. For more information, see the API reference.

Example 1

This example shows you how to check the language of the input text, and append the language info to the input text string.

In the premessage webhook configuration page, the following values are specified:

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language
• Secret: none
• Header name: Content-Type
• Header value: application/json

The premessage webhook calls an IBM Cloud Functions web action name check_language.

The node.js code in the check_language web action looks as follows.

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["main 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
}
};

To test the webhook, click Preview. In the preview panel, submit the text Buenos días. The assistant probably won't understand the input, and will return the response from your Anything else node. However, if you go to the Analytics page of your skill and open the User conversations page, you can see what was submitted. Check the most recent user conversation. The log will show that the user input is Buenos días (in es). The es in parentheses represents the language code for Spanish, so the webhook worked and recognized that the submitted text was a Spanish phrase.

Example 2

This example shows you how to check the language of the incoming message, and if it's not English, translate it into English before submitting it to the assistant. Doing so can be useful if the assistant's conversational skill is in English.

Define a sequence of web actions in IBM Cloud Functions. The first action in the sequence checks the language of the incoming text. The second action in the sequence translates the text from its original language into English.

In the premessage webhook configuration page, the following values are specified:

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence
• Secret: none
• Header name: Content-Type
• Header value: application/json

The node.js code for the first web action in your sequence looks as follows:

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["main skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        return params;
})
}
else {
    params.payload.context.skills["main skill"].user_defined["language"] = 'none'
    return params
}
};

The second web action in the sequence sends the text to the Watson Language Translator service to translate the input text from the language that was identified in the previous web action into English. The translated string is then sent to your assistant instead of the original text.

The node.js code for the second action in your sequence looks as follows:

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["main skill"].user_defined.language !== 'en') && (params.payload.context.skills["main 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["main 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
    }
};

When you test the webhook in the preview panel, you can submit Buenos días, and the assistant responds as if you said Good morning in English. In fact, when you check the Analytics>User conversations page, the log shows that the user input was Good morning.

You can add a postmessage webhook to translate the message's response back into the customer's native language before it is displayed. For more information see Example 2.

Removing the webhook

If you decide you do not want to preprocess customer input, complete the following steps:

1. From the assistant overview page, click the icon, and then choose Settings.

2. Click Webhooks > Pre-message webhook.

3. Do one of the following things:

   • To change the webhook that you want to call, click Delete webhook to delete the currently specified URL and secret. You can then add a new URL and other details.
   • To stop calling a webhook to process every incoming message, click the Pre-message webhook switch to disable the webhook altogether.