Connect a bot to Search (preview)

This article describes how to create a custom federated search provider (power by your bot) and connect it to the Search channel. Once the tenant administrator enables your provider in their tenant, enterprise user searches, from Office.com, SharePoint.com, and Bing.com, can include results from your custom search provider.

The Azure Federated Search Platform enables you to build custom federated search providers to allow your information to participate in Azure Search's Answers & Vertical experiences without the need for merging that information with your Microsoft 365 index. For more information, see Announcing developer preview of the Azure Federated Search Platform and Dynamics 365 federation search (preview).

The following steps are required to connect your bot to the Search channel. These steps are described in more detail later in this article.

1. Implement your bot to work as a search provider.
2. If your bot will require users to be signed in:
   1. In the Azure portal, expose the bot API to the search platform.
   2. In your bot code, use the generated scope URI to generate a user token.
3. Deploy your bot to Azure.
4. Add the Search channel to your bot.
5. Ask your IT administrator to review your bot registration and publish your bot in the tenant.

Prerequisites

• Knowledge of Basics of the Bot Framework Service and how to Create a bot with the Bot Framework SDK.
• The bot to connect to the channel.
• If you don't have an Azure account, create a trial subscription before you begin.

You can implement your bot in any of the languages supported by the Bot Framework SDK. This article uses the C# federated search bot as an example.

Expose the bot API to Search

In some business workflows, a bot might require user credentials to perform an action on the user's behalf. To create a single sign-on (SSO) experience for your bot in the Search channel, you must allow the search platform to secure an access token from Microsoft Entra ID on behalf of the user.

To generate a scope URI and application ID for your bot:

1. Go to the Azure portal.
2. If you don't already have a bot resource, create an Azure Bot resource.
3. Go to the Microsoft Entra ID service.
4. Go to the App registrations pane.
5. Select the application associated with your bot.
6. Go to the Expose an API pane.
7. Select Add a scope.
   1. On the Add a scope pane, we recommend that you keep the autogenerated Application ID URI. Select Save and continue.
   2. Enter a Scope name.
   3. For Who can consent?, Admins and users is preferred, but both options will work.
   4. Enter an Admin consent display name and an Admin consent description.
   5. Optionally, enter a User consent display name and a User consent description.
   6. Verify that State is set to Enabled.
   7. Select Add scope.
8. Select Add a client application.
   1. In the Add a client application pane, set Client ID to 81473081-50b9-469a-b9d8-303109583ecb, the Search platform's client ID.
   2. Under Authorized scopes, select the scope URI you created in the previous step.
   3. Select Add application.
9. Go to the Overview pane. Copy the Application ID URI. You'll need this when you register your bot in the Search channel.

Implement your bot

The Search channel sends each user query to your bot as an invoke activity with a name of "application/search". Your bot returns the query results in the invoke response. Use the Adaptive Card format for the query results sent back to the Search channel.

1. Update any Bot Framework and Adaptive Cards packages in your project to the latest version.
2. Optionally, add authentication code to generate a user token.
3. Implement a data search method for each data source to include.
4. Generate the Adaptive Card to display the results.

Get the Search platform trace ID

The Search platform assigns a unique trace ID to each query it sends to your bot. The platform adds this to the invoke activity's channel data. You might decide to log the trace ID of the request. Use the channel data's traceId property to get the trace ID.

In the federated search sample, the SearchHelper.GetSearchTraceId method demonstrates how to get the trace ID from the invoke activity.

Add authentication

If you exposed your bot API to Search and you requested authentication when you connected your bot to Search, you can get the user authentication token from the activity's channel data.

The channel data's authorizations property can contain a list of authentication tokens. If you expose your bot API to Search, the list will contain the on-behalf-of token. The token in the list will have the following structure:

Property Name	Type	Description
authType	integer	The authentication token type: 0 for unknown or default, or 2 for on-behalf-of token.
token	string	The authentication token itself.

In the federated search sample:

• The SearchBotAuthenticationToken class and the AuthenticationTypes enumeration represent this information.
• The SearchHelper.GetSearchOboToken method demonstrates how to get the token from the invoke activity.

Once you have the token, you can use it when you request any protected resources for the user. For information on using on-behalf-of tokens, see Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow.

Query each data store

The Search channel sends a query to the bot as an invoke activity, with the query details in the activity's value property, which represents a JSON object with the following structure:

Property Name	Type	Description
queryText	string	The query text.
kind	string	The kind of query: "search" when results will be displayed in a custom vertical tab, or "searchAnswer" when a result will be displayed as an answer in the All tab.
queryOptions	object	Additional query options used for pagination.
queryOptions.skip	integer	The index of the first result to send.
queryOptions.top	integer	The maximum number of results to send.

You return the search results in the invoke response:

• Always set the invoke response object's Status property to 200, which indicates that the network connection is okay. The object's Body property has a separate status code.

• The Body property represents a JSON object with the following structure:

  Property Name	Type	Description
  statusCode	integer	An HTTP status code used to indicate whether the bot was able to successfully run the query.
  type	string	The type of the invoke response, defining the format of the value field. Use "application/vnd.microsoft.search.searchResponse" for search results, or "application/vnd.microsoft.error" for an error message.
  value	object	A value that corresponds to the value type.

  For error messages, the value object contains:

  Property Name	Type	Description
  code	string	An error code defined by the bot, or null if not specified.
  message	string	An error message, or null if not specified.

  For search results, the value object contains:

  Property Name	Type	Description
  results	array of search result objects	The results, or null if none.
  displayLayouts	array of display layout objects	The display layouts, or null if none.
  totalResultCount	integer	The total results available, if pagination is supported; otherwise, null.
  moreResultsAvailable	Boolean	Indicates whether more results are available.

  Search result objects contain:

  Property Name	Type	Description
  value	string	A unique identifier or value for this search result.
  layoutId	string	The ID of the display layout to use for this result.
  data.searchResultText	string	The text for this result.

  Display layout objects contain:

  Property Name	Type	Description
  layoutId	string	The layout ID.
  layoutBody	string	The layout body as an Adaptive Cards JSON object.

In the federated search sample, the SearchHelper.RunFederatedSearch method demonstrates how to get the query information from the invoke activity and how to format the invoke response.

Display the search results

You can create search verticals and result types to customize the search results that users see when they search in SharePoint, Office, and Bing. Verticals make it easier for users to find the information that they have permission to see. For more information, see the Supported Adaptive Card elements section.

If your bot receives a query for which it has no response, its reply should contain an empty response.

Register your bot in Azure

To connect your bot to the Search channel, you must have a bot resource provisioned in Azure. For more information, see how to Register a bot with Azure or how to Deploy your bot in Azure.

Connect your bot to Search

The following instructions show you how to connect a bot to Search.

1. Go to the Azure portal.

2. Open your bot resource.

3. Open the Channels (Preview) pane.

4. Select Search.

5. In the Search Settings tab, enter information for your bot.

   

   1. Under Search Provider Metadata, enter the name to display in the search UI.

   2. Under Trigger Phrases, define the phrases that represent the queries your bot can answer.

      Note

      For initial releases, only English (en-US) is available.

      • Upload a .csv file that contains the phrases. The file should contain one column of data, with no headers.
      • From the Language preference list, select the language in which the trigger phrases are written.

   3. Under Authentication, indicate whether your search provider requires user authentication.

      • If authentication is required, enter the authentication URL. Use the Application ID URI you copied when you exposed the API for your bot.

   4. Select Next.

6. In the Verticals tab, if you want the results from your search provider to show up in its own custom vertical in the search results page, then input the vertical name in the field; otherwise, leave this field empty. Then, select Next.
   The search results page is for Office.com, SharePoint.com, and Bing.com.

7. In the Tenant Publishing tab, review your settings and add publishing information.

   1. Review the search provider name and sample queries. Go back to the previous tabs to change this information, if necessary.
   2. Enter a description of your search provider.
   3. Enter a support contact email. Use the email of a developer or developer group who has access to the search provider.

8. Select Add to request approval from your IT administrator.

Approve a search provider in a tenant

The search provider approval in the tenant is made by an IT administrator in the Search & Intelligence page in the Microsoft 365 admin center.

Test the connection

We recommend that you enable the search provider in a test tenant before you enable it in production.

Modify a search provider

You can edit the search provider before you submit it for review by the IT administrator. You might need to do so if your initial request is rejected or your service is deactivated.

1. In the Azure portal, go to the bot resource that contains the search provider you want to edit.
2. Go to the Channels (Preview) pane.
3. Select the Search channel, and select Edit.
   1. Azure displays the Search Channel pane. In this pane, you can edit your settings.
   2. To modify the triggering phrases, download the file, edit it locally, and upload the file.
   3. Once you finish your edits, select Add again to submit search provider for review by the IT administrator.

Delete a search provider

Your search provider will be deleted if you remove the Search channel from the bot resource.

To remove the Search channel from your bot:

1. In the Azure portal, go to your bot resource.
2. Go to the Channels (Preview) pane.
3. Select the Search channel.
4. At the top of the Search Channel pane, select Delete channel.
5. Select Yes to confirm the operation.

To delete your bot resource:

1. In the Azure portal, go to your bot resource.
2. If you haven't already done so, remove the Search channel from your bot.
3. At the top of the Overview pane, select Delete.
4. Select OK to confirm the operation.

Additional information

The search channel uses federated search and the Adaptive Cards schema:

For more information about the Adaptive Card schema, see Adaptive Cards for bot developers.

About trigger phrases

A trigger phrase is a phrase that the search platform uses to route a query to your custom search provider powered by your bot. Federated search forwards a user's utterance to your search provider when the utterance is a close match to one of the trigger phrases.

As an example, think of a bot that manages flight schedules and status.

1. Think of a few common ways a user would refer to or make use of your bot. Be sure to distinguish your bot from others.

   Instead of a generic term, such as "timetable" that can apply to schools and TV programs, use more specific phrases, such as "flight time table" and "flight schedule".

2. Include diverse phrases that cover the scope of your bot's features, such as departure time and current status.

   For example, include queries about: arrival or departure times and airports.

The trigger phrases for such a flight schedule and status bot might include:

• Flight timetable
• Flight status
• Flight 675 departure time
• When will my flight depart
• Flight 468 arrival time
• Seattle Tacoma flight status
• Heathrow flight status

As another example, the trigger phrases for a weather forecast bot might include:

• Local weather forecast
• Weather info
• Tomorrow's weather
• 10-day weather forecast
• Today's high
• Today's chance of rain
• Will it snow tomorrow
• Wind speed tomorrow
• Is it windy outside
• London weather

Supported Adaptive Card elements

A subset of the Adaptive Card schema is supported in federated search. For information about formatting your search results, see Customize the search results page.

Support includes the following Adaptive Card elements: TextBlock, RichTextBlock, Image, ColumnSet, ImageSet, and FactSet. For more information, see Microsoft Search's Manage search result layouts and the Adaptive Cards Schema Explorer.

You can author each card directly as JSON, or you can use the AdaptiveCards NuGet package.

Federated search doesn't support HTML

The Search platform doesn't include an HTML parser. However, you can eliminate some of the tags and use the Html2Markdown NuGet package to convert HTML to Markdown:

1. Remove <span> and <u> elements.
2. Replace <div> and <br> elements with paragraph (<p>) elements.
3. Convert the remaining HTML to Markdown.

Next steps

• For information about channel support in the Bot Connector Service, see Connect a bot to channels.
• For information about building bots, see How bots work and the Create a bot with the Bot Framework SDK quickstart.
• For information about deploying bots, see Deploy your bot and Set up continuous deployment.