IBM Watson Assistant is an AI-based service on the IBM Cloud to help you build and deploy virtual assistants. This is a beneficial technology that can serve in many relevant social and business cases.
It can be easily integrated with IBM cloud functions, a serverless approach allowing developers to code without caring for hardware provisioning. IBM Watson Assistant can be enriched with integrated cloud functions.
In this article, we see how to add a connection to an automated translator to leverage a single-language knowledge base toward a multilingual audience.
Multi-lingual text-based Assistants
Automated answering systems are today a viable solution in all kinds of organizations. The use of text-based applications allows for adoption in most parts of the world, only needing a basic communication service.
Many times the local needs are covered with a single-language solution. A multi-language approach is more satisfying in all cases if it’s possible to automate it starting from reference documentation in one language.
A multi-lingual, text-based approach looks like the best solution to pre-process the incoming questions before connecting the users with a human operator. A common question is why not relying on human operators directly.
It is a problem of service optimization: many questions can be managed through an automated answering service. Many cases can be best addressed to operators starting with an automated question/answer phase.
Using AI-based services inside chatbot systems is an ideal starting point. It allows for great improvements, such as voice input, where needed or allowed.
Starting from Watson Assistant and expanding its capabilities with cloud-function microservices is a very flexible way to approach modern ICT solutions that are easy to deploy and great for cost and bill purposes.
You can learn these skills by watching the live recording of the Data and AI Forum on IBM’s on-demand content platform, along with many more.
In many regions of the world, the B2C push is very challenging and such solutions are of great relevance. In developing countries, in particular, there is a great need for working answering systems for all their basic needs about food, water, and production.
IBM Call for Code Global Challenge 2021 addresses these problems proposing every developer or open-minded person to join as an individual, or with her/his own team, to improve the living conditions of billions of people, participating in the IBM Call for Code Challenge: change your life, change the world!
Making a call before processing a message
The goal of this project is to make a call to an external service or application every time a customer submits input. The external service can process the message before it is processed by your assistant.
This choice greatly optimizes both the number of calls that can be processed by human operators and the final quality of the answers.
Watson Assistant allows you to code your expertise in “skills” that leverage IBM’s cognitive services. Writing cloud functions to exploit specific cloud-based microservices makes the best solution when integrated with cognitive skills.
The user call triggers the following actions to be automated by software. This kind of notification is often named “webhook” in the event-driven programming paradigm. The basic structure of your code will include three sections: a pre-message, a webhook, and a post-message.
You have to keep in mind that a webhook sends traffic over the internet. This can be relevant to environments where private endpoints are in use.
Managing events by webhooks
More precisely, a webhook is a mechanism that allows you to call out to an external program based on events in your program. Adding a pre-message webhook to your assistant allows the webhook to be triggered before each incoming message is processed by your assistant.
You can use a pre-message webhook to do the following types of things:
- translate the customer’s input to the language that is used by your skill.
- check for and remove any personally identifiable information, such as an email address or social security number that a customer might submit.
You can use this webhook in coordination with the post-message webhook. For example, the post-message webhook can do things like translate the response back into the customer’s native language or add back information that was removed for privacy reasons, if necessary.
For more information, see Making a call after processing a message.
If you want to perform a one-time action when certain conditions are met during a conversation, you can use a dialog webhook. This is not the case for our example.
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 call must be completed in 8 seconds or less
- the format of the request and response must be in JSON. For example: Content-Type: application/JSON.
Do not set up and test your webhook in a production environment where the assistant is deployed and is interacting with customers.
Use an external service that can execute and return a result in less than 8 seconds. Otherwise, the customer will experience a lag in the conversational exchange.
To add the webhook details, complete the following steps:
- From your assistant, click the icon, and then choose Settings.
- Click Webhooks > Pre-message webhook.
- Set the Pre-message webhook switch to Enabled.
- 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, enable this setting. Take steps to test the process that you are calling regularly so you will know if it’s down, and can change this setting to prevent all of your message calls from failing.
If the preprocessing step is helpful but not critical, consider keeping this setting disabled: the assistant will ignore any errors without taking the preprocessing step.
- In the URL field, add the URL for the external application to which you want to send HTTP POST request callouts. In this example, you write a Cloud Function that checks whether a message is in a language other than English and if so, sends it to the Language Translator service to convert 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. Please note that 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.
- 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”. Its 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. For more information about how this field is used, see Webhook security.
- 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 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. Your webhook details are saved automatically.
Testing the webhook
A fundamental recommendation is to do extensive testing for an assistant that is being used in a production environment before you enable an assistant.
It 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.
If you call a 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 following error codes can help you track down the cause of issues you might encounter. If you have a webchat 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. The main error codes (422, 500) and messages are listed in the original article.
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:
The request body
It is useful to know the format of the request body of the pre-message 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 pre message webhook. For more information about the message request body, see the API reference.
Discover and translate
Let’s now see how to manage multiple languages when your conversational script (the assistant’s conversational skill) is in English.
First, the software checks the language of the incoming message; if it’s not English, the message is translated into English; then there is the submission to the assistant.
You have to 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.
Check the language of the incoming text
In the pre-message 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:
Translate the text into English
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:
Caption: Translate the text into English
ALT text: A node.js code is used to translate the text message.
SOURCE: IBM Watson Assistant pages
The final step will be adding a call to the translation service. The assistant answers in English, that is not the user’s language. This language has been detected and the correspondant parameter is passed to the service, in order to supply the translation.
You can add a post-message webhook to translate the message’s response back into the customer’s native language before it is displayed. For more information see this article.
Removing the webhook
If you decide you don’t want to preprocess customer input, complete the following steps:
- From the assistant overview page, click the icon, and then choose Settings.
- Click Webhooks > Pre-message webhook.
- 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.
Let’s change the world!
It’s time to be aware of how managed frameworks and microservices can be the foundation of a new approach to technology leverage. All CxO’s and developers need to be up to date.
Much information has been delivered during the Data and AI Forum Italy. You can still watch its live recording on IBM’s on-demand content platform.
Another big chance to evolve in an international environment is teaming up to change the world. It is not a way of saying thanks to the IBM Call for Code Challenge. The whole planet is going through a transformation that’s partially in technology, and partially in our souls.
The Challenge is a great way to give a contribution to improve Earth’s health, and change the scope of your future: consider joining the IBM Call for Code Global Challenge 2021!
