Sonoma Partners Microsoft CRM and Salesforce Blog

Hey Cortana, Say Hello to CRM

Today's blog post was written by Angel Shishkov, Principal Developer at Sonoma Partners.

Cortana integration for CRM has been available for preview since the 2016 Update. Here are some commands you can ask it to do. This feature was geared towards mobile phones, but it also works on a Windows PC or laptop.

As the Cortana integration becomes more developed and users explore its possibilities, we expect to see some requests for custom Cortana integrations with CRM as well.

In this post, I will give a brief, high-level introduction to the steps necessary to set up a custom integration between Cortana and CRM and the possibilities it offers us. In this example, there will be no user authentication, and we will hardcode our CRM connection string. I will assume you have an Azure subscription, Visual Studio 2015+, and some knowledge of C#.


Here are the steps we will go through:

  1. Environment Setup
  2. Implementation
  3. Register the Bot
  4. Test the Bot
  5. Deploy the Bot to Azure
  6. Talk to Cortana

Environment Setup

First, let’s set up our development environment. Visual Studio is free, and Azure has a free trial.

  1. You should have access to Visual Studio IDE, as well as an Azure subscription to deploy the bot.

  2. Download and install the Azure SDK for Visual Studio here.

  3. Download and install Cortana Skill template here.


We will implement a Cortana bot in C# .NET and connect to CRM through the CRM SDK. Our bot will be very simple – it will only respond to a couple of phrases and will only perform one query into CRM. For the scenario, I have used an entity from our internal Sonoma CRM system. We use CRM to track our work in records called Items. The items are assigned to people and have Due Dates. The bot we are going to build will respond to two questions regarding Items in CRM: “How many items are due this week?” and “How many items are due next week?”

1. Create VS project with the “Bot Application – Cortana Skill” template we installed earlier. I called mine, HelloCRM.


2. Restore NuGet packages and run a build to make sure everything is good. The template creates a sample bot with a controller and dialog.

3. Add CRM SDK NuGet packages: Microsoft.CrmSdk.CoreAssemblies and Microsoft.CrmSdk.XrmTooling.CoreAssembly. These are necessary so we can connect our bot to CRM.


 4. Open RootDialog.cs and replace it with the code below. The code does the following:

  1. RootDialog is an implementation of a dialog between Cortana and our bot.

  2. The StartAsync method is called one when a new dialog starts.

  3. The MessageReceivedAsync method is called each time a message is received from Cortana. That is, whenever the user speaks a phrase.

  4. The spoken message passes in with the result parameter, as a text string.

  5. First, we create a connection to CRM. We are using the Xrm.Tooling.Connector library, which makes it as easy as passing a connection string to a constructor. You will need to modify this connection string to point to your instance of CRM, with your credentials.

  6. Next, we extract the spoken message into a text string.

  7. Then, we use Regex to match the spoken message to a question our bot can handle. Note that the text string is a representation of what Cortana thinks the user said, so we have built in some fuzzy matching of like-sounding terms. For example, the words “week” and “weak” sound the same, so we’re matching on both.

  8. We check for two questions; “how many items this week?” and “how many items next week?” They will both trigger the same query in CRM, but the filter will be different based on which week we are looking at.

  9. Within each match, we first call the CountCRMItemsDue method. This does a simple FetchXML and returns a count of the results. Then, we send back a response using the SayAsync method. This method takes a parameter for the text to display, the text to speak and whether to listen for further questions, or end the conversation. We are passing the AcceptingInput hint, so Cortana will expect further questions in the conversations, after speaking the answer.

5. Rebuild again to make sure everything is good.

Register the Bot

We haven’t deployed the bot to Azure yet, but we can already register it on our Microsoft account. This is necessary if we want to test It locally first. We are going to register a new bot and connect it to the Cortana channel, so it can receive messages from Cortana.

1. Log in to with your Microsoft account.

2. Go to My Bots and click Register.

3. Type in your bot display name, handle and description.

4. Click on Generate App ID and password and generate both. Copy and save both, we will need them later!


5. Agree to the terms at the bottom and click Register.

6. You should now be on the Hello CRM bot page, in the Channels tab. Under “Add a channel”, click the Cortana image.


7. Keep the defaults and click Save

Test the Bot

We can test our bot locally, before we deploy it to Azure. To do this, we need to complete the bot registration above and install the Bot Framework Emulator.

1. Install the Bot Framework Emulator here.

2. In Visual Studio, open the Web.config file for your bot and near the top, fill in the App ID and password we copied earlier.


3. Run the bot in Visual Studio with the green Run button. It should be set to open in your default browser.


4. Take note of the URL and port number in the address bar of the browser that popped up. Now, start the Bot Framework Emulator.

5. At the top, click the blue bar, update the URL and port to match what is in your browser and enter the App ID and password you configured in your Web.config.


6. If everything is good, on the bottom right the Log should show a POST 200 message.


7. Now you can use the textbox on the bottom to send test messages to your bot, or click the microphone icon to speak to it. It will reply by text message, as well as speech (although it is not Cortana speaking).

Deploy the Bot to Azure

Now that we’ve tested the bot, it is ready to deploy to the cloud. We will be deploying it as an Azure App Service.

  1. Make sure the App ID and password have been added to your Web.config file.

  2. If you have a WebApp already set up in Azure, you can publish directly into it. Otherwise you can create a new WebApp as part of the publish process:

    1. In Visual Studio, right-click the project and select Publish.

    2. Select “Microsoft Azure App Service” as the publish target.

    3. On the App Service page, you can either select an existing WebApp to deploy into, or click New to create a new one.

    4. On the Connection page, keep the defaults, but copy the Destination URL; we will need it later.

    5. Click Next through the rest of the dialog and click Publish at the end. Visual Studio will deploy the bot to the WebApp location and open a browser window to it.

  3. Log in to with your Microsoft account.

  4. Go to My Bots, open the “Hello CRM” bot and click Settings on the top right.

  5. In the Configuration section, fill in the “Messaging endpoint” with the URL of your bot copied earlier, with /api/messages appended to the end.


  6. Click Save Changes at the bottom. Now the bot is deployed to the Azure cloud, instead of the local machine, and its registration has been updated with the URL, so Cortana knows where to find it.

  7. By default, the bot is only registered on your Microsoft account, and will only be available to Cortana running on your account. It is possible to deploy it to groups of users, or to make it fully public. On the bot page under My Bots, you can click on the “Manage in Cortana dashboard" link next to the Cortana channel to explore these options.

Talk to Cortana

Now we’re all set to have Cortana use our bot. To invoke custom bots, you need to use the phrase “Hey Cortana, ask <botname> <question>”.

  1. You can activate Cortana by saying “Hey Cortana” (if you have that setting turned on), or clicking the Cortana circle icon in the taskbar.

  2. In our case, we can say “Hey Cortana, ask Hello CRM how many items are due next week?”

  3. The first time Cortana connects to the custom bot, it will ask your permission to send your request to the bot.

  4. Click Yes, and you can now converse with the bot.


  5. Yay, no items!

I am excited to see the interesting use cases our customers will come up with for custom Cortana integrations. While controlling a system with your voice might seem awkward at first, it will become easier and more natural as voice assistants become more popular in homes.

I hope this was useful, thanks for reading!

Topics: Microsoft Dynamics 365