\(Legacy\) Integrating Virtual Agent with IBM Watson Assistant for Assistant V2 API

task australia Updated Sep 10, 2026 6 min read configure-watson-assistant-topicV2.md
Raw file servicenow.com

Configure the IBM Watson Assistant Chat Integration to run a dialog skill (conversation) created in IBM Watson Assistant with the Assistant V2 API. The V2 API enables the Virtual Agent chat widget to run a topic that uses Watson Assistant's intent disambiguation feature to improve topic discovery.

Before you begin

Note: An updated Assistant Designer Asset library user interface is available when you install ServiceNow Otto for Virtual Agent. This content assumes that you can see the list view. If ServiceNow Otto for Virtual Agent is not installed, you see the legacy UI and topics page. For more information, see Virtual Agent Designer legacy topics page.

With the IBM Watson Assistant v2 API chat integration, the chat widget communicates with an assistant instead of with a workspace. Workspaces are referred to as dialog skills. For information on IBM Watson Assistant, see Migrating to the v2 API in the IBM Watson Assistant documentation.

Role required: virtual_agent_admin or admin

About this task

This integration runs an IBM Watson Assistant dialog as a Virtual Agent topic in the chat widget. It doesn't require enabling Natural Language Understanding (NLU) or setting IBM Watson Assistant NLU as the NLU service provider for Virtual Agent.

The IBM Watson Assistant V2 API enables the chat widget to use the Watson Assistant intent disambiguation feature, which can potentially reduce false-positive intent predictions. If a user's utterance is ambiguous, IBM Watson Assistant suggests additional intents that might better match the user's true intention. For example, if the user utterance is restaurant, IBM Watson Assistant can suggest other possible intents, such as book a restaurant or restaurant reviews.

Procedure

  1. Configure IBM Watson Assistant.

    1. Create your assistant, then add a dialog skill.

      For details, see Creating an assistant in the IBM Watson Assistant documentation.

    2. On the Resource list page, locate and record your API key and URL, which you need to set up the chat integration:

      [Omitted image "Watson-Resource-list.png"] Alt text: Resource list page in IBM Watson Assistant, which shows the API key and URL values for the assistant.

    3. Select the three vertical dots icon [Omitted image "kebab-menu.png"] Alt text: More actions icon. and select Settings.

      • Select the API Details tab.
      • On the Assistant Settings page, find the Assistant ID key. [Omitted image "WatsonAssistantSettings.png"] Alt text: IBM Watson Assistant Settings for the dialog skill to be used. API Details and Assistant ID are highlighted here.

  2. Enable the disambiguation feature in IBM Watson Assistant (for premium and plus users only).

    You can enable (or disable) disambiguation for each skill, and also specify a disambiguation message and the number of suggestions to be displayed to the end user.

    1. Access your skill by selecting the skill tree icon [Omitted image "IBM-watson-skilltree.png"] Alt text: Skill tree icon. in the panel.

      [Omitted image "AccessSkillTree.png"] Alt text: Assistants list in IBM Watson Assistant with skill tree icon highlighted.

    2. Navigate to Options > Disambiguation to enable disambiguation and set the disambiguation features.

      The following example shows the disambiguation features that can be set, such as the disambiguation message and the number of suggested intents to be displayed to the end user.

      [Omitted image "WatsonDisambiguation.png"] Alt text: Disambiguation form in IBM Watson Assistant. Disambiguation tab, on-off toggle, disambiguation message, anything else message, and suggestion maximum are highlighted.

  3. Navigate to Dialog, select a node to which the disambiguation feature will apply, and provide a summary of the node that will be displayed to users if it's one of the intent suggestions.

    [Omitted image "WatsonDialogNodeSummary.png"] Alt text: Dialog node with a node purpose summary displayed to users as an alternate intent choice for disambiguation. Optional node summary is highlighted.

  4. In your ServiceNow instance, activate these plugins:

    • Glide Virtual Agent (com.glide.cs.chatbot), if not already activated (requires a subscription)
    • IBM Watson Assistant Integration V2 plugin (com.glide.cs.ibm.watson.assistant.topicV2)

  5. In Virtual Agent Designer, publish the IBM Watson Assistant V2 topic:

    1. Navigate to Conversational Interfaces > Assistant Designer.

    2. Select the Asset library tab.

    3. Set the topic discovery type toggle switch to NLU/Keyword.

    4. In the Virtual Agent Designer home page, select the IBM Watson Assistant V2 topic to open the Topic Properties page.

      Notice that the Keyword for this topic is IBM Watson Assistant V2.

    5. In the Topic Properties page, select Publish to deploy the topic to your Virtual Agent chat widget.

  6. Navigate to All, and then enter sys_properties.list in the filter.

  7. Update the following properties.

    • watson_assistant.v2.assistantID — In the Value field, enter the Watson Assistant ID for your assistant and select Update.

      [Omitted image "WatsonAssistantIDprop.png"] Alt text: System Property form for the watson_assistant.v2.assistantID property. Example Watson Assistant ID value and Update button are highlighted.

    • watson_assistant.v2.service_endpoint — In the Value field, replace the existing value with your Watson Assistant URL and select Update.

      [Omitted image "WatsonAssistant-endpoint-prop.png"] Alt text: Form for the watson_assistant.v2.service_endpoint property. with example URL value and Update button highlighted.

      Note: You can specify just the location portion of the service instance URL in the Value field. For example, if the base URL for the IBM Watson service endpoint is https://gateway.watsonplatform.net/assistant/api, you can enter just the location of the service instance, gateway.watsonplatform.net in the Value field.

      If your Watson Assistant is hosted in a data center other than Dallas, such as Washington DC, your base URL is https://gateway-wdc.watsonplatform.net/assistant/api. You would enter gateway-wdc.watston.platform.net in the Value field.

  8. Set the Watson Assistant API key as the password in the IBM Watson Assistant Profile.

    1. Navigate to All, and then enter sys_auth_profile_basic.list in the filter.

    2. Open the IBM Watson Assistant Profile record.

    3. In the Basic Auth Configuration form, enter the Watson Assistant API key in the Password field and select Update.

      [Omitted image "WatsonAssistantAuthProfile.png"] Alt text: Basic auth configuration for the IBM Watson Assistant Profile, with Password field and Update button highlighted.

  9. Add the Virtual Agent (web chat) client to the Service Portal.

    1. Navigate to Service Portal > Service Portal Configuration.

    2. Select Designer, and then select the Service Portal landing page.

    3. Search for the Virtual Agent widget and drag the widget into the outlined area.

      The purple chat icon appears in the bottom right corner.

      [Omitted image "ServicePortal-WatsonChat.png"] Alt text: Service Portal designer page with Virtual Agent Service Portal Widget, design canvas, and chat icon highlighted.

  10. Configure the Virtual Agent widget by selecting the edit icon [Omitted image "edit-icon.png"] Alt text: Edit icon. in the upper right corner to set the URL parameters passed to the chat client and change the color of the floating chat button.

    1. In the Virtual Agent Client URL Parameters field, enter the sysparm_skip_load_history=true parameter so that the topic history doesn't display in the chat client and the sysparm_topic parameter with the sys_id of the published IBM Watson Assistant V2 topic to be run.

      You can find the sys_id of a topic in the Topics [sys_cs_topic] table.

      If you don't configure the instance behavior in Service Portal, you can specify your instance URL with the sysparm_topic and sysparm_skip_load_history parameters when you open the chat chat widget. For example: https://<Your instance URL>$sn-va-web-client-app.do?sysparm_skip_load_history=true&sysparm_topic=*&lt;sys\_id&gt;* where <sys_id> is the sys_id of the published IBM Watson Assistant V2 topic to be run.

      Important:

      Use the sysparm_topic parameter only to load the given topic in the Service Portal chat client or when using the IBM Watson Assistant chat integrations (com.glide.cs.ibm.watson.assistant.topic and com.glide.cs.ibm.watson.assistant.topicV2 plugins). This parameter doesn’t allow users to start a new conversation or transfer to a live agent. It also disables the context menu and doesn’t support other third-party chat clients.

    2. To change the floating button color, enter the new color (RGB hex format) in the Floating Button Color field.

    3. Select Save.

      [Omitted image "ServicePortal-sysparm-url-example.png"] Alt text: Service Portal designer page with open Instance dialog box. Virtual Agent Client URL Parameters field is highlighted.

  11. Test that the disambiguation feature is working for your topic.

    Be sure that disambiguation is enabled for your Watson Assistant skill and at least two dialog nodes. In the following example, the virtual agent provides four additional intents that the user can select.

    [Omitted image "ExampleDisambiguationTopic.png"] Alt text: Virtual Agent conversation showing additional intents discovered through the disambiguation feature.

Parent Topic:(Legacy) Integrating IBM Watson Assistant conversations

Keywords IBM Watson AssistantVirtual AgentAPI
Search documentation
Search document titles and file paths on the australia branch