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.
If you don't have an Azure account, create a free account 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
Tip
This step is only needed if your bot requires access to protected user resources.
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:
Go to the Azure portal.
If you don't already have a bot resource, create an Azure Bot resource.
Go to the Microsoft Entra ID service.
Go to the App registrations pane.
Select the application associated with your bot.
Go to the Expose an API pane.
Select Add a scope.
On the Add a scope pane, we recommend that you keep the autogenerated Application ID URI. Select Save and continue.
Enter a Scope name.
For Who can consent?, Admins and users is preferred, but both options will work.
Enter an Admin consent display name and an Admin consent description.
Optionally, enter a User consent display name and a User consent description.
Verify that State is set to Enabled.
Select Add scope.
Select Add a client application.
In the Add a client application pane, set Client ID to 81473081-50b9-469a-b9d8-303109583ecb, the Search platform's client ID.
Under Authorized scopes, select the scope URI you created in the previous step.
Select Add application.
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.
Update any Bot Framework and Adaptive Cards packages in your project to the latest version.
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.
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.
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.
The following instructions show you how to connect a bot to Search.
Tip
We recommend that you enable the search provider in a test tenant before you enable it in production.
Go to the Azure portal.
Open your bot resource.
Open the Channels (Preview) pane.
Select Search.
In the Search Settings tab, enter information for your bot.
Under Search Provider Metadata, enter the name to display in the search UI.
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.
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.
Select Next.
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.
In the Tenant Publishing tab, review your settings and add publishing information.
Review the search provider name and sample queries. Go back to the previous tabs to change this information, if necessary.
Enter a description of your search provider.
Enter a support contact email. Use the email of a developer or developer group who has access to the search provider.
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.
In the Azure portal, go to the bot resource that contains the search provider you want to edit.
Go to the Channels (Preview) pane.
Select the Search channel, and select Edit.
Azure displays the Search Channel pane. In this pane, you can edit your settings.
To modify the triggering phrases, download the file, edit it locally, and upload the file.
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:
In the Azure portal, go to your bot resource.
Go to the Channels (Preview) pane.
Select the Search channel.
At the top of the Search Channel pane, select Delete channel.
Select Yes to confirm the operation.
To delete your bot resource:
In the Azure portal, go to your bot resource.
If you haven't already done so, remove the Search channel from your bot.
At the top of the Overview pane, select Delete.
Select OK to confirm the operation.
Additional information
The search channel uses federated search and the Adaptive Cards schema:
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.
Tip
If more than one search provider is available, federated search chooses only one, based on the trigger phrases provided and the user's query.
As an example, think of a bot that manages flight schedules and status.
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".
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.
You can author each card directly as JSON, or you can use the AdaptiveCards NuGet package.
Federated search doesn't support HTML
Important
Federated search won't render Adaptive Card text that contains 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:
Remove <span> and <u> elements.
Replace <div> and <br> elements with paragraph (<p>) elements.
Explore how Microsoft Graph and federated connectors can help bring more of your organization's data to Microsoft Search. Use custom verticals, results clusters, and other customizations to enhance the search experience for your users.
Learn how to embed bots in websites by using a web control. See how the backchannel mechanism facilitates private communication between web pages and bots.
Microsoft MVPs Anthony Chu and Shaun Luttin sit down and build a natural language chat bot from scratch using the new Azure Bot Service and Microsoft Cognitive Services' LUIS (Language Understanding Intelligent Service). Overview of Azure Bot Service Creating a bot from scratch Training LUIS Connecting the bot to Slack Links from the video Azure Bot Service LUIS Azure Functions Microsoft Bot Framework Build a Chat Bot in 30 Minutes (slides) .ai - Wikipedia Languages supported by LUIS Connect on Twitter
A channel connects a communication application to a bot. Learn how to configure a bot to run a channel using the Azure portal, Direct Line, or a custom adapter.