In this repo, you learn how to add multi-languages support to your Watson Assistant chatbot. You learn how to develop, deploy and configure pre-Webhook and post-Webhook of Watson Assistant.
There are many ways to add multi-languages capability when developing a Watson Assistant chatbot. Mitchell Mason wrote a great blog on the subject at The Watson Assistant Guide to Multilingual Chatbots.
For simplicity and portability, this repo implements the Full Machine Translation
option.
The flow is simple: a user sends a message to Watson and Watson sends a response back. We’ll use the pre- and post-message webhooks to intercept and translate in between.
Data flow:
- Take the user’s message
- Identify the language in the message with the Language Translator
Language Identification
endpoint, and then translate the message to the language of the assistant - Get the response from Watson
- Translate it back to the user’s language based on context set in step 2
- Send response user.
Complete procedures in this section to add generic and portable multi-languages capability to a Watson Assistant chatbot by implementing the Full Machine Translation
option.
There are many ways to support multi-languages capability in Watson Assistant chatbot. Depending on your specific use cases, the options may perform differently. The Full Machine Translation
method is a generic, portable option. Because it provides an universal catching-all multi-languages capability, other implementation options may offer a more accurate solution in certain specific use cases.
Before you deploy your code as a service in IBM Cloud Function, clone the repo locally.
-
Login to IBM Cloud in a browser.
-
Open the
IBM Cloud Shell
. TheIBM Cloud Shell
is opened in a separate tab. -
Since you were authenticated when you logined to the IBM Cloud, you are automatically autenticated in the
IBM Cloud Shell
. -
Clone the repo.
git clone https://github.com/lee-zhg/watson-chatbot-pre-post-webhook
-
Navigate to the repo folder.
cd watson-chatbot-pre-post-webhook/
The following tasks complete the Watson Assistant pre-webhook deployment and configuration.
- Develop source code that holds the translation logic.
- Deploy the above application as a microservice. In this repo, the service is deployed as a IBM Cloud Function in IBM Cloud.
- Configure Watson Assistant pre-webhook to apply the language translation logic to the chatbot.
Sample code preMessageTranslate.js
offers a starting point. It locates in the root folder of this repo.
The sample code helps you create a service running synchronisely to
- identify the language ID of the input phrase if necessary
- store the identified language ID for the reference during the remaining chat session
- translate the input phrase to the desired language
The application running as the Watson Assistant pre-webhook. It
- intercepts the in-coming payload from chatbot end user
- performs its language translation logic and manipulates the payload
- passes the payload to the Watson Assistant
The payload is a JSON object. A sample payload can be found in file ./data/sample_pre_payload.json
.
Note: an instance of Watson Translator service is required for the sample code to work. Lite version (free version) of Watson Translator service is available with your IBM Cloud account.
Note: to debug in IBM Cloud Function, you likely need an instance of
IBM Log Analysis with LogDNA
.
It's easy and economical to deploy a microservice as a IBM Cloud Function. In this repo, the language translation microservice is deployed as a IBM Cloud Function.
Alternatively, you may choose deploying the service to different platform such as Cloud Foundry, Kubernetes cluster, OpenShift cluster and etc.
In this section, you deploy your code as a service in IBM Cloud Function. Because the Cloud Functions is not the focus of the repo, basic CLI commands are used to show the procedure.
-
Login to IBM Cloud in a browser.
-
Open the
IBM Cloud Shell
. TheIBM Cloud Shell
is opened in a separate tab. -
Since you were authenticated when you logined to the IBM Cloud, you are automatically autenticated in the
IBM Cloud Shell
. -
Target a resource group by executing
ibmcloud target -g Default
Note: you may use a different resource group in your account.
-
Create a Cloud Function Namespace. Execute
ibmcloud fn namespace create team1a-ns-<your initial> --description "namespace for team1a"
-
Verify the new namespace was created.
ibmcloud fn namespace list
-
Set the new namespace as default
ibmcloud fn property set --namespace team1a-ns-<your initial>
-
Create package
ibmcloud fn package create multi-language-pkg-<your initial>
-
Create action for setup using Node.js environment
ibmcloud fn action create multi-language-pkg-<your initial>/preMessageTranslate preMessageTranslate.js --kind nodejs:12 --web true --web-secure <YOURSECRET>
Note: can be any text string that helps to keep your cloud functions secure. Note down for future reference.
-
Verify the action cloud function was created succerssfully.
ibmcloud fn action list multi-language-pkg-<your initial>
Alternatively, you may also deploy the Cloud Function via IBM Cloud UI.
The cloud function calls Watson Translator APIs. It has to authenticate and point to the correct Translator endpoint. For simplicity, the Watson Translator API key and URL is hardcoded in the Node.js source code.
Note: it's posssible to bind cloud function and Watson services without hardcode. But, it's not covered at the time of writing.
-
Login to IBM Cloud
-
Select the main
Navigation Menu
(often referred as Hamburge menu) at the top-left corner. -
Select the
Functions
and thenActions
. -
Select
preMessageTranslate
entry. -
The source code is displayed in the
Code
tab. -
Locate the following source code.
url: "<Watson Translator URL>/v3/identify?version=2018-05-01", auth: { username: "apikey", password: "<Watson Translator API key>", },
-
Replace
<Watson Translator API key>
and<Watson Translator URL>
. -
Both
<Watson Translator API key>
and<Watson Translator URL>
can be found in theManage
tab of yourWatson Language Translator
instance window. -
Locate the following source code.
url: "<Watson Translator URL>/v3/translate?version=2018-05-01", auth: { username: "apikey", password: "<Watson Translator API >", },
-
Replace
<Watson Translator API key>
and<Watson Translator URL>
. -
Save
.
When you configure the Pre-webhook for your Watson Assistant instance, you need couple of you cloud function information.
-
Login to IBM Cloud
-
Select the main
Navigation Menu
(often referred as Hamburge menu) at the top-left corner. -
Select the
Functions
and thenActions
. -
Select
preMessageTranslate
entry. -
Navigate to
Endpoints
in the left navigation pane. -
Collect URL of
HTTP Method
underWeb Action
. -
Collect username and password if the cloud function resides in a
cloud foundry
name space.non-IAM
authentication is used in this case.a) Copy the CURL command at the bottom. It should look like
curl -u 6e1bf-a76e-4bc2-9c24-8784af9:Vc1jv13mD6nJEIqouEFPwQjLkAnnJ6GzDvTBr3P2 -X POST https://us-south.functions.cloud.ibm.com/api/v1/namespaces/SL2272168_dev/actions/multi-language-pkg/postMessageTranslate?blocking=true
b) The authentication credential to access the cloud function is embedded as part of the command. In this example,
6e1bf-a76e-4bc2-9c24-8784af9:Vc1jv13mD6nJEIqouEFPwQjLkAnnJ6GzDvTBr3P2
is the username and password.Note:
6e1bf-a76e-4bc2-9c24-8784af9:Vc1jv13mD6nJEIqouEFPwQjLkAnnJ6GzDvTBr3P2
is for illustration purpose. It's not valid credential.c) Take note of the credential.
Now, you have deployed a service to IBM Cloud Function. Whenever you call the service, the cloud function fires up.
To configure the pre-webhook of Watson Assistant instance,
-
Login to IBM Cloud.
-
Locate and open the Watson Assistant instance.
-
On the
Manage
tab of Watson Assistant window, clickLaunch Watson Assistant
button. -
Develop or import a skill. Couple of sample skills are available in the
/data
folder.Note: you may use your existing skill.
-
For the rest of this repo, a skill
photo-shop
based on sampleskill-watson-photo.json
will be used for discussion. -
Create an
Assistant
on theAssistant
tab. Name itphoto-shop-assistant-<your initial>
.Note: you may use your existing assistant.
-
Add the skill
photo-shop
to the assistant.Note: if you use your existing skill and assistant, you may skip the step.
-
Click the 3 dots at the top-right corner and select
Assistant settings
. -
In the left navigation, select
Webhooks
and thenPre-message webhook
. -
Enable the pre-webhook.
-
Select
Return an error to the client if the webhook call fails
under sectionSynchronous event
.Note: you should consider to turn on the option initially while you test the post-webhook. It can help you identify any post-webhook related problem. After the pre-webhook works stably, you may evaluate your use case and determine how the option should be set.
-
In the URL field, copy and paste the
HTTP URL
of the cloud function for the pre-webhook. -
Add
.json
extension at the end of the URL to indicate that JSON data should be returned. -
In the
Secret
field, enter the same<YOURSECRET>
that was used when you deployed the cloud function.Note: If you did not specify its secret when deploying the cloud function, you may enter any string here.
-
Enter header information of the pre-webhook.
a) Select
Add header
link.b) Enter
Content-Type
in theHeader name
field.c) Enter
application/json
in theHeader value
field.d) Tab out the field. This saves the pre-webhook configuration changes.
-
Enter header information for authenticating the pre-webhook.
For
IAM
authentication (used bynon-cloud foundry
name space in IBM Cloud Function),a) Select
Add header
link again.b) Enter
X-Require-Whisk-Auth
in theHeader name
field.c) Enter the same
<YOURSECRET>
(that was used when you deployed the cloud function) in theHeader value
field.d) Tab out the field. This saves the pre-webhook configuration changes.
For
non-IAM
authentication (userid and password) (used bycloud foundry
name space in IBM Cloud Function),a) Select
Add header
link again.b) Enter
Authorization
as the header name.c) User name and Password are prompted in a popup window.
Note: in case the pop-up is not opened, you may click the
gear
icon to the right of the fields to manually open it.d) Enter user name and password for the pre-webhook cloud function.
e)
Save
. The user name and password are encoded before they are stored.Note: this repo uses
Secret
for authentication. The step above is for reference only.
The following tasks complete the Watson Assistant post-webhook deployment and configuration.
- Develop source code that holds the translation logic.
- Deploy the above application as a microservice. Cloud Function in IBM Cloud is used for this repo.
- Configure Watson Assistant post-webhook to apply the language translation logic to the chatbot.
Sample code postMessageTranslate.js
offers a starting point. It locates in the root folder of this repo.
The sample code helps you create a service running synchronisely to
- identify the language ID of the input phrase if necessary
- store the identified language ID for the reference during the remaining chat session
- translate the input phrase to the desired language
The application running as the Watson Assistant post-webhook. It
- intercepts the out-going payload from Watson Assistant
- performs its language translation logic and manipulates the payload
- passes the payload to chatbot end user
The payload is a JSON object. A sample payload can be found in file ./data/sample_post_payload.json
.
Note: an instance of Watson Translator service is required for the sample code to work. Lite version (free version) of Watson Translator service is available with your IBM Cloud account.
Note: to debug in IBM Cloud Function, you likely need an instance of
IBM Log Analysis with LogDNA
.
It's easy and economical to deploy a microservice as a IBM Cloud Fuction. In this repo, the language translation microservice is deployed to IBM Cloud Function.
Alternatively, you may choose deploying the service to different platform such as Cloud Foundry, Kubernetes cluster, OpenShift cluster and etc.
In this section, you deploy your code as a service in IBM Cloud Function. Because the Cloud Functions is not the focus of the repo, basic CLI commands are used to show the procedure.
-
Go back to the
IBM Cloud Shell
. -
Create action for a service for post-webhook using Node.js environment
ibmcloud fn action create multi-language-pkg-<your initial>/postMessageTranslate postMessageTranslate.js --kind nodejs:12 --web true --web-secure <YOURSECRET>
Note: is a text string that helps to keep your cloud functions secure. Notes down for future reference.
-
Verify the action cloud function was created succerssfully.
ibmcloud fn action list multi-language-pkg-<your initial>
Alternatively, you may also deploy the Cloud Function via IBM Cloud UI.
The cloud function calls Watson Translator APIs. It has to authenticate and point to the correct Translator endpoint. For simplicity, the Watson Translator API key and URL is hardcoded in the Node.js source code.
Note: it's posssible to bind cloud function and Watson services without hardcode. But, it's not covered at the time of writing.
-
Login to IBM Cloud
-
Select the main
Navigation Menu
(often referred as Hamburge menu) at the top-left corner. -
Select the
Functions
and thenActions
. -
Select
postMessageTranslate
entry. -
The source code is displayed in the
Code
tab. -
Locate the following source code.
try { const languageTranslator = new LanguageTranslatorV3({ authenticator: new IamAuthenticator({ apikey: '<Watson Translator API key>' }), serviceUrl: '<Watson Translator URL>', version: '2018-05-01', });
-
Replace
<Watson Translator API key>
and<Watson Translator URL>
. -
Both
<Watson Translator API key>
and<Watson Translator URL>
can be found in theManage
tab of yourWatson Language Translator
instance window. -
Save
.
When you configure the Post-webhook of Watson Assistant instance, you need couple of you cloud function information.
-
Navigate to
Endpoints
in the left navigation pane. -
Collect URL of
HTTP Method
. -
Collect username and password when
non-IAM
authentication is used. This occurs for thecloud foundry
name space.a) Copy the CURL command at the bottom. It should look like
curl -u 6e1bf-a76e-4bc2-9c24-8784af9:Vc1jv13mD6nJEIqouEFPwQjLkAnnJ6GzDvTBr3P2 -X POST https://us-south.functions.cloud.ibm.com/api/v1/namespaces/SL2272168_dev/actions/multi-language-pkg/postMessageTranslate?blocking=true
b) The authentication credential to access the cloud function is embedded as part of the command. In this example,
6e1bf-a76e-4bc2-9c24-8784af9:Vc1jv13mD6nJEIqouEFPwQjLkAnnJ6GzDvTBr3P2
is the username and password.Note:
6e1bf-a76e-4bc2-9c24-8784af9:Vc1jv13mD6nJEIqouEFPwQjLkAnnJ6GzDvTBr3P2
is for illustration purpose. It's not valid credential.c) Take note of the credential.
Now, you have deployed a service to IBM Cloud Function. Whenever you call the service, the cloud function fires up.
To configure the Post-webhook of Watson Assistant instance,
-
Login to IBM Cloud.
-
Locate and open the Watson Assistant instance.
-
On the
Manage
tab of Watson Assistant window, clickLaunch Watson Assistant
button. -
Open
photo-shop-assistant-<your initial>
Assistant. -
Click the 3 dots at the top-right corner and select
Assistant settings
. -
In the left navigation, select
Webhooks
and thenPost-message webhook
. -
Enable the post-webhook.
-
Select
Return an error to the client if the webhook call fails
option under sectionSynchronous event
. Alternative isContinue processing user input without webhook update if there is an error
.Note: you should consider to turn on the option initially while you test the post-webhook. It can help you identify any post-webhook related problem. After the post-webhook works stably, you may evaluate your use case and determine how the option should be set.
-
In the URL field, copy and paste the
HTTP URL
of the cloud function for the post-webhook. -
Add
.json
extension at the end of the URL to indicate that JSON data should be returned. -
In the
Secret
field, enter the same<YOURSECRET>
that was used when you deployed the cloud function.Note: If you did not specify its secret when deploying the cloud function, you may enter any string here.
-
Enter header information of the post-webhook.
a) Select
Add header
link.b) Enter
Content-Type
in theHeader name
field.c) Enter
application/json
in theHeader value
field.d) Tab out the field. This saves the post-webhook configuration changes.
-
Enter header information for authenticating the post-webhook.
For
IAM
authentication (used bynon-cloud foundry
name space in IBM Cloud Function),a) Select
Add header
link again.b) Enter
X-Require-Whisk-Auth
in theHeader name
field.c) Enter the same
<YOURSECRET>
(that was used when you deployed the cloud function) in theHeader value
field.d) Tab out the field. This saves the pre-webhook configuration changes.
For
non-IAM
authentication (userid and password) (used bycloud foundry
name space in IBM Cloud Function),a) Select
Add header
link again.b) Enter
Authorization
as the header name.c) User name and Password are prompted in a popup window.
Note: in case the pop-up is not opened, you may click the
gear
icon to the right of the fields to manually open it.d) Enter user name and password for the pre-webhook cloud function.
e)
Save
. The user name and password are encoded before they are stored.
With all the deployments and configurations that you have completed, you added the multi-langages capability to your chatbot.
This is an universal solution. You don't have to do special configuration in order to chat with chatbot in individual language as long as Watson Translator
supports it.
-
Login to IBM Cloud.
-
Locate and open the Watson Assistant instance.
-
On the
Manage
tab of Watson Assistant window, clickLaunch Watson Assistant
button. -
Open
photo-shop-assistant-<your initial>
Assistant. -
Select
Preview
at the top-right corner. -
Enter
imprimir fotografías de 8x10 en acabado brillante
("print 8x10 photos in glossy finish" in Spanish). The chatbot replies in Spanish. -
Clear the chat history by selecting
Restart conversation
button or refresh the browser. -
Enter
광택 마감의 6 x 8 사진은 얼마입니까
("How much is a 6 x 8 photo with a glossy finish" in Korean). The chatbot replies in Korean. -
Clear the chat history by selecting
Restart conversation
button or refresh the browser. -
Enter
اطبع صور 6 × 8 بلمسة نهائية غير لامعة
("Print 6 x 8 photos in a matte finish" in Arabic). The chatbot replies in Arabic. -
Clear the chat history by selecting
Restart conversation
button or refresh the browser. -
Enter
печать фотографий 4x6 с матовым покрытием
("print 4x6 photos in matte finish" in Russian). The chatbot replies in Russian.
Develops once and works everywhere! Have you heard the phrase before? When Java was introduced, it was a popular phrase. It's the main characteristics how Java differentiates itself. About 20 years later, when Kubernetes and RedHat OpenShift became main street for IT deployment, it got popular again.
In fact, the multi-language capability introduced in the repo is another good example. But, works everywhere
in this context means works in any language
. You can develop your chatbot once, in English for example, and port to any supported language.
There are use cases that you may have developed chatbot in English and you like to quickly port to another language. You can certainly rebuild it for a different language. But, it takes time and resource.
The knowledge you have learned in this repo can can help you port an existing chatbot developed in English to a different language in no time. Chinese is used as new language for illustration.
-
Login to IBM Cloud.
-
Locate and open the Watson Assistant instance.
-
On the
Manage
tab of Watson Assistant window, clickLaunch Watson Assistant
button. -
Navigate to
Skills
tab. -
Select the 3 dots on the
photo-shop-<your initial>
skill tile. -
Select
Duplicate
. -
Go back to
Skills
tab. -
Select the 3 dots on the
photo-shop-<your initial> copy
skill tile. -
Select
Rename
. -
Rename to
photo-shop-<your initial>-zh
. -
Open the new skill.
-
Select
Dialog
in the left navigation pane. -
Select the
Welcome
node to open its property window. -
Change context variable
lang_id
tozh
fromnone
. -
Tab out to save the change.
-
Navigate to
Assistant
tab. -
Select
Create assistant
button. -
Enter
photo-shop-assistant-<your initial>-zh
as the name. -
Select ``Create assistant` button.
-
Configure the pre-webhook and post-webhook as you have done. The same source codes and cloud functions can be re-used.
As promised at the begining of the section, You can port an existing chatbot to another language in no time. You have done that for chatbot photo-shop-<your initial>
.
To verify,
-
Login to IBM Cloud.
-
Locate and open the Watson Assistant instance.
-
On the
Manage
tab of Watson Assistant window, clickLaunch Watson Assistant
button. -
Open
photo-shop-assistant-<your initial>-zh
Assistant. -
Select
Preview
at the top-right corner. -
The chatbot displays the greeting in Chinese instead of English, although you did not modify its skill which was originally developed in English.
Note: The greeting text translation to Chinese is not the best translation for the current context. Since this is not a custom solution, you have to accept the imperfection.
-
Enter
以哑光效果打印 6x8 照片
. The chatbot continuosely chats in Chinese.Note: This is a perfect translation for the current context. You may have to evaluate your specific use cases to determine if this easy and universal multi-languages solution offers a valid solution to your use cases.
Now, let's how easily and quickly you can switch to Spanish.
-
Navigate to
Skills
tag. -
Open skill
photo-shop-<your initial>-zh
. -
Select the
Welcome
node to open its property window. -
Change context variable
lang_id
toes
fromzh
. -
Tab out to save the change.
You just port your chatbot to Spanish from English. To verify,
-
Login to IBM Cloud.
-
Locate and open the Watson Assistant instance.
-
On the
Manage
tab of Watson Assistant window, clickLaunch Watson Assistant
button. -
Open
photo-shop-assistant-<your initial>-zh
Assistant. -
Select
Preview
at the top-right corner. -
The chatbot displays the greeting in Spanish instead of English or Chinese, after you made one change to the context variable
lang_id
in theWelcome
node. -
Enter
imprimir fotografías de 8x10 en acabado brillante
. The chatbot continuosely chats in Spanish.