Bring your own search to IBM Watson Assistant

We’ve introduced a new feature called “bring your own search” to Watson Assistant. Enterprises can now use their existing search technology to help customers find information via virtual assistants.

Authors: J. William Murdock and Arnesh Batlaw

Penguins (some of whom appear to be searching for something)

Consumers increasingly expect to be able to resolve issues themselves. IBM Watson Assistant is an enterprise solution that allows companies to build more effective paths to self service. We’re happy to share a new path that we call bring your own search.

Typically, virtual assistants are oriented around conversational flows that help customers through known issues. Watson Assistant provides an exceptionally accurate and market-leading mechanism to match user queries to topics and specific conversational flows.

Of course, sometimes users will ask something that the creator did not anticipate. Often the right solution in that case is to escalate to a human agent. However, human agents are usually very busy dealing with the most challenging cases.

If a virtual assistant can keep simple, information-seeking requests from escalating to an agent, it can provide a faster resolution for those requests. It can also lead to shorter wait times for the challenging requests that do require a human agent because those agents are not busy dealing with simple requests.

For those reasons, it can be very useful for a virtual assistant to search through documents like web pages or help center articles whenever it receives a query that doesn’t match to a known conversational flow. Many websites already have a search capability that they use to power their site search or knowledge center search.

Rather than making a new/different search for the virtual assistant, Watson Assistant allows you to reuse the one that is already powering the support search that you already have. In this article, we describe how to connect an existing search capability to Watson Assistant in order to provide search results to user queries.

We call this capability bring your own search.

How search results appear to the end user

Comparison with the built-in search integration

For users who are familiar with Watson Assistant, you might know that we offer a built-in-search integration to IBM Watson Discovery. This integration is designed to be easy to set up and sufficiently capable to handle typical search use cases.

In contrast, the bring-your-own-search capability can be used for more complex needs and removes two significant limitations of the built-in integration:

1. Bring your own search lets you use any search API that can work with the Watson Assistant custom extensions capability. This lets you leverage the site search, knowledge base search, or content management system search that you have already invested in. Rather than invest in a new tool and move all your content over, simply bring in whatever search tools you have already invested in.
2. Bring your own search gives you full control over every parameter of your search API and access to every part of its response. Whether you are using IBM Watson Discovery or another search product, if you have a complex use case and want access to advanced features, bring your own search might be the right fit for you. It gives you ownership over how search results are shown to the end user, and lets you enable advanced filtering so customers only see results personalized for them and their issue.

You can think of the built-in integration as a “TV dinner”: a frozen meal that you microwave and eat. It is extremely convenient but also simple and limited. In contrast, you can think of bring your own search as more like a farmers’ market full of fresh, raw ingredients. You can put those ingredients together however you want if you are willing to do the work.

Bring-your-own-search starter kits

We have built five bring-your-own-search (BYOS) starter kits. These enable you to quickly launch with any of these five products. They also let you understand how the integration and capabilities work, so you can adapt them for your own particular search tool.

• BYOS Google custom search starter kit: This kit invokes the Google custom search JSON API, which allows you to search over a restricted subset of the world wide web (e.g., a set of specific websites or even parts of specific websites) and also allows you to search the full web. The kit also includes examples of interactive filtered search, in which a multi-turn dialog allows users to more precisely specify search filters (e.g., how recent a document must be to be included in the results).
• BYOS Zendesk Guide starter kit: This kit invokes the Zendesk Guide API for searching knowledge articles. It includes some examples of filtering search results based on what was asked in the original query (unlike the Google custom search kit, in which the filtering is all controlled by the end user). The Zendesk Guide kit also includes a sample Javascript web page that displays search results in a card format.
• BYOS Coveo search starter kit: This kit invokes the Coveo search query API. This is a relatively simple starter kit that does not include any filtering or Javascript for card rendering. Those things should also be feasible with Coveo, so if you use Coveo as your search and want to do these things, you may want to look at how they are done in other kits and apply the same mechanisms.
• BYOS Magnolia search starter kit: This kit invokes the Magnolia search API. As with Coveo, it does basic search only, so advanced users may want to pull in advanced features from one of the more complex kits. Getting started with this kit can be a little more challenging than the others; because Magnolia is not a cloud product, you need to set up Magnolia first on your own servers or on the cloud of your choice.
• BYOS IBM Watson Discovery starter kit: This kit integrates with Watson Discovery and includes the answer-finding feature that identifies concise answers within passages. The kit includes a sample Javascript web page that extends the Watson Assistant web chat interface to display search results in a card format. The kit uses the confidence values that Watson Discovery assigns to concise answers to determine whether to emphasize them in the text. It also shows how to personalize the search behavior based on a user profile and based on the user utterance. This is done by restricting search queries to a subset of the content.
• BYOS NeuralSeek starter kit: This kit invokes NeuralSeek by Cerebral Blue, a combined search and natural-language generation system that invokes Watson Discovery to search for multiple relevant documents and then generates a single coherent natural-language answer using the contents of those documents.

If you have your documents available for searching in a system that is not listed above, the bring-your-own-search approach might still be a good fit for you. You will need to build your own specification and actions for that search. We recommend starting by familiarizing yourself with one or more of the existing kits first to see how it is done. Then you can apply what you learned to the search system of your choice.

Basics of bring your own search

Each of the starter kits come with everything that you’ll need to integrate the search system into Watson Assistant:

1. Each kit provides a README.md file that explains how to use it.
2. Each kit provides an OpenAPI specification that you can use to create the Watson Assistant custom extension. This is how we integrate with the search API.
3. Each kit provides a sample Actions file that you can upload to Watson Assistant to create conversational flows that invoke an extension to get search results and then show those results to users.

In the next section we will describe some advanced features that give you more control over how the search results are shown to end users. Here you can see what the simple, basic search results look like:

Search results with simple, basic text formatting

Showing results in search cards

The Watson Discovery and Zendesk Guide kits each include a sample HTML web page that shows how to present search results in a card format. The image at the end of this section shows what the format provided in the starter kit looks like. If you like this format, you can use it as is. All the code that generates this format is in the sample HTML file in the starter kit.

You can further customize the look and behavior of these cards as much as you want by modifying that code. For example, you could pull results from multiple fields of a complex schema and arrange them how you want. You could use metadata to control card color or insert different icons for different metadata values. You could add 3D or animation effects. You could even arrange cards so that they scroll left and right in a carousel.

This flexibility in how outputs are rendered is one of the biggest benefits of using bring your own search instead of the built-in search integration. Here is what we have in the starter kits, and you can use this to get started and change it as much as you want:

Search results formatted in clickable cards with icons indicating that you click to open a new tab

Filtering and Personalization

As noted in the list of starter kits earlier, some of the kits include examples of how to filter search results to just a subset of your documents. This can be a useful tool for personalizing content based on background information you have about a user or based on specific requests from the user.

The Watson Discovery starter kit has one example in which the calling application indicates a specific topic that the user is interested in (which it could do based on a user profile or on details about where the user is on the site). It also has another example in which there is a trained intent that triggers a specific filtered query for a specific information need.

The advanced configurations of the Zendesk Guide and Google Custom Search starter kits show other examples of uses of filtering in search. You may want to take a look at how and why those kits do filtering, even if you are not planning to use any of those specific search systems.

Camels bringing people across the desert (possibly on some type of search)

Bring your own!

If you have documents that you want to search in one of the systems for which we have a starter kit, then using that starter kit can get you connected quickly and easily. However, if your documents are in some other search system, then you may still be able to bring your own search.

Take a look at one or more of the starter kits that seem relevant to you. If you are planning a complex application with a lot of customization, you may want to start with the Watson Discovery starter kit, which is one of the most full-featured kits. Alternatively, if you want something simpler that is easier to get started with, you might want to consider starting with the Coveo starter kit.

Regardless of where you start, you can make an OpenAPI specification for the search system of your choice, upload it to build a Watson Assistant custom extension, and add actions that invoke that extension and present the search results to a user.

Bring your own search to IBM Watson Assistant to help customers resolve problems themselves using the search system you already have.

Acknowledgements

Special thanks to the Watson Assistant team who made this possible, especially Mary Swift, Sneha Srinivasan, Vishal Manghnani, and Anirudha Bapat for building starter kits. We also thank David Amid, Nicole Black, Clark Bystrom, Jaymin Desai, and Collin Murray for additional guidance and insight.