Oracle Cloud Infrastructure Documentation

Microsoft Teams

When you set up a Microsoft Teams channel, users can chat with your digital assistant (or a standalone skill) through the Microsoft Teams Chat window.

Here's the process for setting up a channel:

  1. Using the Microsoft Bot Framework or the Microsoft Azure Bot Service, create a bot registration in 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 Microsoft Teams.

Step 1: Create a Bot Channels Registration with Microsoft

To make your digital assistant (or standalone skill) available in Microsoft Teams, you need to have it registered with either of the following:

Azure Bot Channels Registration

To create a bot channel registration through Azure:

  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 name you want to use when accessing your digital assistant through Microsoft Teams.

  4. Fill in the rest of the required fields.

  5. Scroll down to the Microsoft App ID and password section, expand it, and click Create New.

    A new browser tab will open, and you will be redirected to the Azure portal's App registrations blade.

  6. Click New Registration.

  7. In the Supported account types section, select the Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) radio button.

  8. Fill in the rest of the required fields and click Register.

    In a few moments, the app registration should be completed.

  9. In the Overview blade, copy the value of the Application (client) ID and save it to a safe place on your system.

  10. Select the Certificates and Secrets blade.

  11. Click + New Client Secret, fill in a description, select when it should expire, and click Add.

  12. Copy the client secret and save it in a safe place on your system.

  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.

Now skip ahead to Step 2: Create a Channel in Digital Assistant.

Bot Framework Channels Registration

To create the registration through the Microsoft Bot Framework:

  1. Go to https://dev.botframework.com/bots/new and log in with an Office 365 user account. The account must be part of an E1 plan or higher.

  2. Upload an icon to represent your digital assistant in Microsoft Teams.

  3. Fill in the Display name, Bot handle, and Long description fields.

    Note

    The bot handle is unique across all global metadata, so you'll probably want incorporate both the digital assistant name and the Microsoft Teams tenant in the value.
  4. Don’t enable the Streaming Endpoint checkbox.

  5. Click Create Microsoft App ID and password.

    A new browser tab will open, and you will be redirected to the Azure portal's App registrations blade.

    Note

    Though you generate the app ID through Azure, the bot registration itself is still managed through the Microsoft Bot Framework.
  6. Click New Registration.

  7. In the Supported account types section, select the Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) radio button.

  8. Fill in the rest of the required fields and click Register.

    In a few moments, the app registration should be completed.

  9. In the Overview blade, copy the value of the Application (client) ID and save it to a safe place on your system.

  10. Select the Certificates and Secrets blade.

  11. Click + New Client Secret, fill in a description, select when it should expire, and click Add.

  12. Copy the client secret and save it in a safe place on your system.

  13. Return to the previous browser tab.
  14. In the Microsoft App ID from the Microsoft App registration portal field, paste the application ID that you copied from the app registration.
  15. Leave the Bot Framework page 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 a separate browser window or tab, open Digital Assistant, click Channels in the left menu, and choose Users.

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

  3. Give your channel a name.

  4. Choose Microsoft Teams 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 or the Microsoft Bot Framework portal.

  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 for Microsoft Teams

  1. If you registered the bot with Azure:

    1. In the browser tab where you have set up your bot registration, 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. Within Bot Service in the left navigation bar, scroll down to the Bot Management section and click Channels.

    5. Click the icon for Microsoft Teams and then click Save.

  2. If you have registered the bot with the Microsoft Bot Framework:

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

    2. Don’t enable analytics.

    3. Check the Agree box, and click Register.

    4. Select the bot you just registered.

    5. Within the Channels tab, click the icon for Microsoft Teams to add Microsoft Teams as a channel.

    6. Click Save to exit the Configure Microsoft Teams dialog.

Step 4: Enable Apps in Your Office 365 Tenant

You next need to have your Office 365 administrator configure your tenant to:

  • Allow external apps in Microsoft Teams.
  • Allow sideloading of external apps.
  • Enable new external apps by default.

For the concrete steps, see https://docs.microsoft.com/en-us/microsoftteams/platform/get-started/get-started-tenant.

Step 5: Test Your Bot in Microsoft Teams

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

  1. Open Microsoft Teams and select the Chat window.

  2. Select the bot channel and start communicating in the message field.

    If you don't see an entry for the bot channel, you can paste the Microsoft App Id of your bot channel registration in the To section of the Chat screen. For further details see https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/bots/bots-test#adding-a-bot-for-personal-chat.

Supported Capabilities

Microsoft Teams channels in Digital Assistant support the following capabilities:

  • text (both sending and receiving)
  • images (both sending and receiving)
  • files (both sending and receiving)
  • emojis (both sending and receiving)
  • links
  • postbacks
  • custom properties
  • carousel components
  • list components

Message Constraints

Microsoft Teams 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

Microsoft Teams Extensions

For Microsoft Teams channels, you can extend the System.CommonResponse component to use card types and other metadata that are specific to Microsoft Teams. The following content types are available:

  • application/vnd.microsoft.card.thumbnail
  • application/vnd.microsoft.card.hero
  • application/vnd.microsoft.teams.card.list
  • application/vnd.microsoft.card.adaptive
  • application/vnd.microsoft.teams.card.o365connector
  • application/vnd.microsoft.teams.file.download.info
  • application/vnd.microsoft.com.card.receipt
  • application/vnd.microsoft.com.card.signin

You declare the card type by using the channelCustomProperties element in the System.CommonResponse component and setting the contentType property to the card type. The code has the following format:

...
          cards:
            ...
            channelCustomProperties:
            - channel: "msteams"
              properties:
                contentType: "contentTypeValue"
...

For example, you could configure a thumbnail card with the following code:

...
          cards:
          - title: "${ateam.firstName} ${ateam.lastName}"
            description: "${ateam.title}"
            imageUrl: "${ateam.photo}"
            cardUrl: "${ateam.linkedin}"
            name: "PersonCard"
            iteratorVariable: "ateam"
            channelCustomProperties:
            - channel: "msteams"
              properties:
                contentType: "application/vnd.microsoft.card.thumbnail"
            actions:
...

For thumbnail and hero cards, you just need to set the contentType property to get the card to work. For other content types, you also need to set other metadata.