Cortana

When you set up a Cortana channel, users can chat with your digital assistant (or standalone skill) through the Cortana user interface.

Here's the process for setting up a channel:

  1. Create a bot registration in Azure to integrate with your digital assistant.
  2. Using the app ID and password from the bot registration, create a channel in Digital Assistant .
  3. Copy the webhook URL that is generated when you create the channel and add it to the bot registration.
  4. Test your digital assistant through the Chat window in the Cortana user interface.

Step 1: Create a Bot Channels Registration in Azure

To make your digital assistant (or standalone skill) available in Cortana, you need to have it registered through Azure Bot Service.

Before you create that registration, you need to have a Microsoft account.

To create the registration:

  1. Go to https://portal.azure.com/ and log in with your Microsoft account.

  2. In the Search field, search for and select Bot Channels Registration .

  3. On the Bot Channels Registration page, fill in the Bot Name field with the text that you want to use as the invocation name when accessing your digital assistant through the Cortana channel.

  4. Fill in the rest of the required fields.

  5. Scroll down and select Auto create App ID and password and then click the button for Auto create App ID and password in the panel that opens up.

  6. Click Create.

  7. Wait a minute or two for the bot registration to be created and deployed.

    When it completes, you will get a notification that the deployment succeeded.

  8. In the notification, click Go to resource.

    If the notification disappears before you can click on it, you can open it up again by clicking the Notifications icon at the top of the page.
    Description of azure-notification.png follows

  9. In the left navigation bar, under Bot Management, select Settings.
  10. Copy the value of the Microsoft App ID and save it in a safe place.

  11. Generate and save a client secret. You can do this by:
    1. Clicking the Manage button that is next to the app ID.

      This takes you to the Microsoft Bot Framework console.

    2. Clicking View this app in the Azure portal.

      This returns you to Azure.

    3. In the left navigation, clicking Certificates & secrets.
    4. Clicking + New Client Secret.
    5. Clicking Add.
    6. Copying the client secret and saving it to a safe place on your system.

    You'll need both the app ID and client secret to configure the channel in Digital Assistant.

  12. Now that you have the client secret copied, close the Certificates & secrets dialog.
  13. Leave the Azure Portal open in your browser.

    You'll later complete the registration with a webhook URL that you get when you create the channel in Digital Assistant.

Step 2: Create a Channel in Digital Assistant

  1. In Digital Assistant, click Channels in the left menu and then choose Users.

  2. Click + Channel to open the Create Channel dialog.

  3. Give your channel a name.

  4. Choose Cortana as the channel type.

  5. Fill in Microsoft Application Id with the Microsoft App ID that you obtained when you created your bot registration in Azure.

  6. Fill in Microsoft Application Password with the client secret that you obtained from your bot registration.

  7. Click Create.

  8. In the Channels page, copy the WebHook URL and paste it somewhere convenient on your system.

  9. Click icon for the Route To ... dropdown and select the digital assistant or skill that you want to associate with the channel.

  10. Switch on the Channel Enabled control.

Step 3: Configure the Webhook URL and Deploy to Cortana

  1. In the browser tab where you have Azure Portal open, use the Search field to navigate back your bot registration.

  2. In the left navigation bar, select Settings.

  3. In the Messaging endpoint field, paste the webhook URL that you obtained when creating the channel in Digital Assistant.

  4. Save your changes.
  5. Within Bot Service in the left navigation bar, scroll down to the Bot Management section and click Channels.

  6. Click the icon for Cortana.

  7. After configuring the channel, click Deploy on Cortana.

Step 4: Test Your Bot in Cortana

With the Cortana channel and messaging configuration complete, you can test your bot (digital assistant or skill) in Cortana.

You can test using either of following options:

  • Within the Azure Portal, with the Test in Web Chat feature (under Bot Management).
  • Through the Cortana app (either desktop or mobile), using the same user ID that you used when setting up the bot registration in Azure.

    When you test using this method, you need to include the bot name (as registered in the Azure Portal) every time you input something into the chat window. Otherwise, Cortana will not necessarily recognize that you are trying to speak with the Oracle digital assistant.

Supported Capabilities

Cortana channels in Digital Assistant support the following capabilities:

  • text (both sending and receiving)
  • images (full support for sending, no support for receiving)
  • files (full support for sending, no support for receiving)
  • emojis (full support for sending, no support for receiving)
  • links
  • custom components
  • carousel components
  • list components
  • typing indicator

Message Constraints

Cortana channels in Digital Assistant have the following message constraints:

  • Text Messages
    • Maximum length of text action label: 1 line (about 50 characters)
    • Types of text actions allowed: Postback, Call, URL
  • Horizontal Cards
    • Maximum length of title: 2 lines (about 80 characters)
    • Maximum length of description: 25,000 characters
    • Maximum length of card action label: 1 line (about 50 characters)
    • Maximum number of cards: 10
    • Maximum number of card actions: 6. If the number of card actions exceeds 6, the card is duplicated to render remaining card actions.
    • Minimum number of card actions: 0
    • Maximum number of card list actions: 6
    • At least one description, image or action required?: No
    • Types of card actions allowed: Postback, Call, URL
    • Types of card list actions allowed: Postback, Call,URL
  • Vertical Cards
    • Maximum length of title: 2 lines (about 80 characters)
    • Maximum length of description: 25,000 characters
    • Maximum length of card action label: 1 line (about 50 characters)
    • Maximum number of cards: 10
    • Maximum number of card actions: 3
    • Minimum number of card actions: 0
    • Maximum number of card list actions: 6
    • At least one description, image or action required?: No
    • Types of card actions allowed: Postback, Call, URL
    • Types of card list actions allowed: Postback, Call, URL
  • Attachment Messages
    • Supported?: Yes
    • Types of actions allowed: Postback, Call, URL
  • Action Buttons
    • Maximum length of global action label: 1 line (about 50 characters)
    • Maximum number of global actions: 6
    • Types of global actions allowed: Postback, Call, URL

Cortana Channel Extensions

For Cortana channels, you can extend the functionality of Common Response components with capabilities that are specific to Cortana.

You access the extensions by using the channelCustomProperties element in the component and setting the appropriate properties. The code has the following format:

...
            channelCustomProperties:
            - channel: "cortana"
              properties:
                PROPERTY_NAME: "PROPERTY_VALUE"
...

Here are the available custom properties for Cortana channels:

Name Allowed Values Applies To... Description
speak
  • free text
  • SSML (Speech Synthesis Markup Language)
Response items of type text. The text or SSML that Cortana reads to the user. See https://docs.microsoft.com/en-us/azure/bot-service/nodejs/bot-builder-nodejs-cortana-skill?view=azure-bot-service-3.0.

For more information on using channelCustomProperties, see Channel-Specific Extensions.