Overview
The following documentation outlines the configuration for the connector and how to implement functions specifically for IBM Watson Assistant Version 1 and 2.
IMPORTANT: In case of inactivity, the Watson Assistant session only last 5 minutes for the Lite/Standard plans and up to 24 hours for Plus/Premium plans. Because of the asynchronous nature of messaging, it could take longer until the user replies to the bot agent. In case the Watson session expires, the bot connector will create a new conversation session on the Watson side More Info.
IBM introduced an updated experience for Watson Assistant, focused on using actions to build customer conversations instead of dialogs. The documentation covers both the old and new experiences. If your account utilizes the new experience and desires to use dialogs or wants to migrate from the classic to the new experience, you can enable them from the assistant settings, as illustrated in the figure below.
Figure 1.0 Showing to enable Dialog with the new actions experience
IMPORTANT: When you activate the dialog feature, it takes precedence over actions.
Watson Version 1 Configuration
See the Getting Started guide before using this document to complete pre-requisite steps.
Please note that Watson does not support processing newline, tab and carriage-return characters. These symbols will be removed from any query that is sent to Watson via the provided connector.
With watson there are two ways of authentication that currently our system support, these are UserPass and IAM (token based) authentication. You can choose one of them for your bot configuration.
Please note Watson UserPass authentication is no longer supported by IBM. If your intention is to utilize a custom workspace URL, we recommend using the customEndpoint connector as an alternative.
UserPass authentication
You will be presented with following screen to complete the Vendor Settings in order to add bot connector using UserPass authentication.
Figure 1.1 Showing the configuration that needed to be filled using UserPass authentication
Following information needs to be completed for LivePerson:
| Item | Description | Example |
|---|---|---|
| Workspace URL | Watson Assistant Workspace URL | https://api.eu-de.assistant.watson.cloud.ibm.com |
| Workspace ID | Watson Assistant Workspace ID (Skill ID) | 8671e9a1-xxxx-xxxx-xxxx-xxxxf9dfcb74 |
| Conversation Username | Username of the Watson Assistant conversation | de0a48a5-9f4f-xxxx-xxxx-xxxxx9856751 |
| Conversation Password | password for the Watson Assistant conversation which should be used for the bot | Dxxxxxxxxxx1 |
IAM authentication
You will be presented with following screen to complete the Vendor Settings in order to add bot connector using IAM authentication.
Figure 1.2 Showing the configuration that needed to be filled using IAM authentication authentication
Following information needs to be completed for LivePerson:
| Item | Description | Example |
|---|---|---|
| Workspace URL | Watson Assistant Workspace URL | https://api.eu-de.assistant.watson.cloud.ibm.com |
| Workspace ID | Watson Assistant Workspace ID | 8671e9a1-xxxx-xxxx-xxxx-xxxxf9dfcb74 |
| API key | API key which will be used for the Bot's authentication in Watson | xxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxZG |
| Token endpoint url | URL for creating/refreshing Watson Assistant tokens | Dxxxxxxxxxx1 |
| Version Date | Version Date of the Watson API | 201X-xx-xx |
You have to agree to Data Disclaimer from now onward in order to use the services of bot connector. For that you can click on the checkbox "I agree to the Data Disclaimer
Test Connection
For validation of the credentials provided, you can now perform a test connection request to see if everything that you have provided is working and reachable. Please note that your bot should be capable of handling unsupported messages either via fallback nodes or as your design pleases. This will ensure the success of the call to the API of IBM Watson Assistant for testing the connection. You can click on the button "Test Connection" to see if connection succeed or fail. For IAM Token authentication see in Figure 1.3 and 1.4.
Figure 1.3 Showing the success case of the valid credentials for IAM authentication
Figure 1.4 Showing the fail case of the invalid credentials for IAM authentication
Please be careful while providing credentials that you have selected the right workspace URL. Selecting the wrong Watson Assistant gateway causes connection failure.
Once you are done with providing configuration you can save it by pressing on "Done". Congratulations! You have completed the configuration of the Watson Assistant bot.
Watson Assistant Version 2 Configuration
See the Getting Started guide before using this document to complete pre-requisite steps.
Please note that Watson does not support processing newline, tab and carriage-return characters. These symbols will be removed from any query that is sent to Watson via the provided connector.
With Watson V2 there are two methods of authentication that are currently supported. These methods are UserPass authentication and IAM (token based) authentication. You can choose either one for your bot configuration but IAM is highly recommended (as it is more secure).
Please note Watson UserPass authentication is no longer supported by IBM. If your intention is to utilize a custom workspace URL, we recommend using the customEndpoint connector as an alternative.
UserPass authentication
You will be presented with following screen to complete the Vendor Settings in order to add the bot connector using username/password authentication.
Figure 1.1 Showing the configuration that needs to be filled out when using username/password authentication
You need to fill in the following information:
| Item | Description | Example |
|---|---|---|
| Workspace URL | Watson Assistant Workspace URL. Note that this workspace URL changes according to your account. In order to figure out which URL is correct for you, check the location of your Assistant in IBM's Cloud console. Then, choose the corresponding URL based on geo-location. For example, if your IBM location is "eu-gb", the London URL is the correct one for you. | https://api.eu-de.assistant.watson.cloud.ibm.com |
| Assistant ID / Environment ID | In the new Actions Experience from IBM, the identifier to use is the Environment ID. For those still utilizing the classic experience from IBM, the identifier to use remains the Assistant ID. | 8671e9a1-xxxx-xxxx-xxxx-xxxxf9dfcb74 |
| Username | Username for the Watson Assistant conversation. Retrievable from the settings of your Watson Assistant. | de0a48a5-9f4f-xxxx-xxxx-xxxxx9856751 |
| Password | password for the Watson Assistant conversation which should be used for the bot | Dxxxxxxxxxx1 |
IAM authentication
You will be presented with following screen to complete the Vendor Settings in order to add the bot connector using IAM authentication.
Figure 1.2 Showing the configuration that needs to be filled in when using the IAM authentication method.
You need to fill in the following infromation:
| Item | Description | Example |
|---|---|---|
| Workspace URL | Watson Assistant Workspace URL. Note that this workspace URL changes according to your account. In order to figure out which URL is correct for you, check the location of your Assistant in IBM's Cloud console. Then, choose the corresponding URL based on geo-location. For example, if your IBM location is "eu-gb", the London URL is the correct one for you. | https://api.eu-de.assistant.watson.cloud.ibm.com |
| Assistant ID / Environment ID | In the new Actions Experience from IBM, the identifier to use is the Environment ID. For those still utilizing the classic experience from IBM, the identifier to use remains the Assistant ID. | 8671e9a1-xxxx-xxxx-xxxx-xxxxf9dfcb74 |
| API key | API key which will be used for the Bot's authentication in Watson. Retrievable from the settings of your Watson Assistant. | xxxxxxxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxZG |
| Token endpoint url | URL for creating/refreshing Watson Assistant tokens. Leave as is. | Dxxxxxxxxxx1 |
You have to agree to Data Disclaimer from now onward in order to use the services of bot connector. For that you can click on the checkbox "I agree to the Data Disclaimer
Test Connection
To validate the credentials you provided above, you can now perform a test connection request. Click on the "Test Connection" button to do so. For IAM authentication see in Figure 1.3 and 1.4.
Figure 1.3 Showing the success case of the valid credentials for IAM authentication
Figure 1.4 Showing the fail case of the invalid credentials for IAM authentication
Please be careful while providing credentials that you have selected the right workspace URL. Selecting the wrong Watson Assistant gateway causes connection failure. See the note in the table above for more information on finding the correct workspace URL.
Once you are done with the configuration and the connection test succeded, you can save your configuration by pressing on "Done".
Congratulations! You have completed the configuration of the Watson Assistant bot.