45 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 user interface.

Here's the process for setting up a channel:

  1. In Microsoft Teams' Developer Portal, create an app and add a bot to that app. (Alternatively, you can use the Microsoft Bot Framework or the Microsoft Azure Bot Service to create a bot registration.)
  2. Using the app ID and password from the bot, 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.
  4. Test your digital assistant in Microsoft Teams.

Note:

Skills and digital assistants that you expose through Microsoft Teams channels can also be included in group chats. See Group Chats.

Step 1: Create a Bot

To make your digital assistant (or standalone skill) available in Microsoft Teams, you need to create a Microsoft bot in one of the following ways:

Developer Portal Channels Registration

To set up a bot through the Teams Developer Portal, you create the following:

  • A Microsoft Teams app. This app is the container for the bot that you create and is how you access the bot in Teams.
  • A bot. This is the artifact within the app that communicates with Oracle Digital Assistant

Here are the steps:

  1. Go to https://dev.teams.microsoft.com/home and log in with your Microsoft account.

  2. In the left navigation, click Apps.

  3. Click + New app.

  4. In the Add App dialog, fill in the name you want to use for the app as it will appear in Microsoft Teams and then click Add.

    (This app will encapsulate the bot, which you will create later.)

  5. On the Basic Information page, fill in the remaining required fields except for Application (client) ID and click Save.

    Note:

    This field is only needed if you configure the bot for single sign-on. See SSO Configuration for Microsoft Teams Channels.
  6. In the left navigation of the page, under the Configure section, select App features.

  7. Click Bot.

  8. Click the Create a new bot link.

  9. On the Bot Management page click + New Bot.

  10. In the Add bot dialog, enter a name for the bot.

  11. After the bot is created, select the Client secrets tab.

  12. In the Client Secrets section of the page, right-click the Azure link to open the App Registrations page of Azure Active Directory in a separate browser tab.

  13. In the App Registrations page, select the bot resource that you created.

  14. Click Add a certificate or secret.

  15. With the Client Secrets tab selected, click + New Client Secret.

  16. In the Add a client secret dialog, fill in a description, select its expiration period, and click Add.

  17. Copy the value of the generated client secret and save it in a safe place on your system.

  18. Return to the tab where you have the Developer Portal open in your browser.

  19. In the left navigation, click Apps and then select your app.

  20. In the left navigation for the app, select App features.

  21. Click the Bot tile.

  22. In dropdown below the Select an existing bot, select the bot that you just created.

  23. Once again, in the left navigation for the app, select App features.

  24. In the Bot title, copy the bot ID and save it in a text file.

    Note:

    You may have to manually transcribe the bot ID.

    You'll need this ID when you create the channel in Digital Assistant.

  25. Click Save.

  26. Optionally, in the left navigation of the page, under the Configure section, select Domains and add any domains that the bot's users may be coming from.

  27. Leave the Developer 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.

Azure Bot Channels Resource

To create a bot channel resource through Azure:

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

  2. In the Azure Services section of the page, click Create a resource.

  3. In the Search Services and Marketplace field (not the Search resources, services, and docs field at the top of the page), type bot and press Enter.

  4. Select the Azure Bot card and then select Create > Azure Bot.

    The Azure Bot page should display.

  5. On the Azure Bot page, click Create.

  6. On the Create an Azure Bot page,

    • Fill in the Bot handle field with the name you want to use when accessing your digital assistant through Microsoft Teams.
    • Select a subscription.
    • Create a resource group.
    • In the Microsoft App ID section:
      1. Make sure that the Type of App is Multi Tenant.
      2. Create New Microsoft App ID is selected.
    • Click Review + create.
  7. Once validation passes, click Create.

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

  8. Once the creation completes, click Go to resource.

  9. In the left navigation, click Configuration.

  10. Copy the value of the Microsoft App ID to your clipboard and save it to a safe place on your system.

  11. In the Azure portal's main menu, select Azure Active Directory.

  12. In the Manage section of the left navigation, select App registrations.

  13. In the App Registrations page, select the bot resource that you created.

  14. In the left navigation, select Certificates and Secrets.

  15. Select the Client Secrets tab and click + New Client Secret.

  16. In the Add a client secret dialog, fill in a description, select its expiration period, and click Add.

  17. Copy the value of the generated client secret and save it in a safe place on your system.

  18. 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 ID of the Microsoft bot that you created.

  6. Fill in Microsoft Application Password with the password or the client secret value (not to be confused with the client secret ID) that was generated for the bot.

  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

Now you need to circle back and complete the configuration in Microsoft Teams.

  • If you set up the bot with the Team Development Portal:

    1. Return to the browser tab where you have the Teams Developer Portal open.

    2. In the far left navigation of the page, select the Tools icon and then click Bot Management.

    3. Select the bot you created.

    4. On the bot's page, select the Configure tab.
    5. In the Bot endpoint address field, paste the webhook URL that you obtained when creating the channel in Digital Assistant and then click Save.

  • If you registered the bot with Azure:

    1. In the browser tab where you have set up your bot resource, navigate back to your bot resource.

    2. In the left navigation bar, select Configuration.

    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.

  • 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/concepts/build-and-test/prepare-your-o365-tenant.

Step 5: Test in Microsoft Teams

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

  • If you created the app with the Developer Portal, you can test the bot by clicking the Preview in Teams button on the page for the app.
  • If you created the app through Azure or the Microsoft Bot Framework:
    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.

SSO Configuration for Microsoft Teams Channels

If you want a digital assistant or skill to require the same authentication that you have configured for Microsoft Teams, you can set up single sign-on (SSO) authentication for that digital assistant or skill within Microsoft Teams.

Once this SSO authentication is set up, users will be able to log in to Teams with their Azure Active Directory (Azure AD) credentials and then seamlessly interact with the digital assistant, without having to sign in again.

Note:

Any backend applications accessed through the digital assistant need to support Azure AD access tokens directly.

Here are the general steps for configuring SSO for a Microsoft Teams channel:

  1. (If you haven't already done so) create a Microsoft Teams channel as described in the preceding topics.
  2. Create an Azure AD application in the Azure Portal.
  3. Update the Microsoft bot registration with with SSO details.
  4. In Oracle Digital Assistant, register the Azure AD app as a Microsoft Identity Platform authentication service.
  5. Enable authentication in your skill(s) through the authentication service you have registered.

Create an Azure AD Application

To set up SSO for a skill or digital assistant within Microsoft Teams, you need to create an Azure AD application. This application is in addition to the Azure AD application you have already created as part of setting up the Microsoft Teams channel.

Before getting started, make sure that you have the following:

  • An Azure account with an active subscription.
  • The Microsoft App ID for the bot that you have set up with your Microsoft Teams channel.
  • Admin access to the Azure portal.

Here are the steps for creating an Azure AD application for SSO:

  1. Create a new application registration:
    1. Navigate to https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade in the Azure portal.
    2. Click New Registration.
    3. Fill in the Name field.
    4. 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.
    5. Click Register.

      Once the application is created, you will land in the Overview section. The Application (client) ID and Directory (tenant) ID should be created for your app.

  2. Add a web platform configuration:
    1. In the left navigation, select Authentication.
    2. Under Platform configurations, click Add a platform.
    3. Add a redirect URI using the following format:
      <YOUR_Oracle-Digital-Assistant_URL>/connectors/v2/callback
    4. Click Configure.
  3. Create a client secret:
    1. In the left navigation, select Certificates and secrets.
    2. Click + New client secret, fill in the required fields, and click Add.
    3. Copy the client secret value and store in a secure place. You'll need this value later.
  4. Configure the token:
    1. In the left navigation, select Token configuration.
    2. Click + Add optional claim.
    3. For Token type, select Access.
    4. Select these claims:
      • given_name
      • upn
      • email
    5. Click Add.
    6. Select the Turn on the Microsoft Graph email, profile permission (required for claims to appear in token) option and click Add.
    7. In the left navigation, select API permissions.

      There you can see that three permissions are created.

    8. Click + Add a Permission and add User.ReadBasic.All.

      You will need this to access profile information.

  5. Set the application ID URI:
    1. In the left navigation, select Expose an API.
    2. Click the Application ID URI field.
    3. Update the value in the format:
      api://botid-<Microsoft_App_ID_for_your_bot>
    4. Click + Add a scope.
    5. In the panel that opens:
      • Set access_as_user as the Scope name.
      • Set Who can consent? to Admins and users.
    6. Fill in the fields for configuring the admin and user consent prompts with values that are appropriate for the access_as_user scope.

      Here are some suggestions:

      • Admin consent title: Teams can access the user’s profile.
      • Admin consent description: Allows Teams to call the app’s web APIs as the current user.
      • User consent title: Teams can access your user profile and make requests on your behalf.
      • User consent description: Enable Teams to call this app’s APIs with the same rights that you have
    7. Ensure that State is set to Enabled.
    8. Select Add scope.

      Note:

      The domain part of the scope name displayed just below the text field should automatically match the Application ID URI set in the previous step, with /access_as_user added to the end.
    9. In the Authorized client applications section, click + Add a client application.
    10. Enter the following IDs:
      • 1fec8e78-bce4-4aaf-ab1b-5451cc387264

        This is the Teams mobile and desktop application.

      • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346

        This is the Teams web application.

  6. Update the manifest:
    1. In the left navigation, select Manifest.
    2. Set "acceptMappedClaims" to true.
    3. Click Save.
  7. Grant tenant admin permissions to the Azure AD application.
    1. In the left navigation, select Overview.
    2. Copy the Application (client) ID, the Directory (tenant) ID and the Application ID URI and save them in a convenient place.
    3. In a private browser window, log in to the Microsoft admin account.
      The URL takes the following form:
       https://login.microsoftonline.com/<tenant-id>/adminconsent?client_id=<client-id>
      where you replace <tenant-id> with the Directory (tenant) ID that you just copied and you replace <client-id> with the Application (client) ID that you just copied.
  8. In the Permissions requested dialog, review and accept the permissions.

Update the Bot Registration with the SSO Details

Update your Microsoft bot with the SSO details you have configured:

  1. Open the bot in the Teams Developer Portal and open the Manifest Editor.
  2. Select the Basic information tab.
  3. Scroll down to the Application (client) ID field and insert the application (client) ID.
  4. Select the Single-Sign-On tab.
  5. In the Application ID URI, add the application ID URI that you copied earlier.
  6. In the left navigation, select Publish to org.

Register the Azure AD App as an Authentication Service in Digital Assistant

Now you'll register the Azure AD app as an authentication service in Oracle Digital Assistant.

  1. In a separate browser window or tab, open Digital Assistant, expand Settings in the left menu, and select Authentication Services.

  2. Click + Service.
  3. In the New Authentication Service dialog, enter these values:
    • Identity Provider: Microsoft Identify Platform
    • Name: A name to identify the authentication service.
    • Token Endpoint URL: The identity provider's URL for requesting access tokens. Use:
      https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/token
    • Authorization Endpoint: The IDP's URL for the page that users authenticate with by entering their user name and password. Use:
      https://login.microsoftonline.com/<Azure-Active-Directory-TenantID>/oauth2/v2.0/authorize
    • Client ID and Client Secret: The client ID and secret for the Azure AD application (OAuth Client) that was registered. Use the application ID and secret.
    • Scope: <Microsoft_App_ID_for_your_bot>/access_as_user

Reference the Authentication Service from Your Skills

In skills that need SSO authentication, incorporate the System.OAuth2AccountLink component in the dialog flow to handle authentication through the authentication service. In that component, be sure to set the enableSingleSignOn property to true.

Tip:

If you don't want to hard-code the name of the authenticate servie in the component, you can create a custom parameter that you pass to the component. See Custom Parameters.

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

If you are targeting your skill to multiple channels with different formatting capabilities and syntax, you can use basic HTML markup in your messages. If you do so, that markup will be automatically converted to the Microsoft Teams markdown format when the message is transmitted to the channel. This is particularly useful if you are targeting your skills to other channels in addition to Microsoft Teams. See Rich Text Formatting in Channels.

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

Adaptive Cards in Microsoft Teams

For skills that you expose through Microsoft Teams channels in Oracle Digital Assistant, you can use Adaptive Cards.

To do so, you use the channelCustomProperties element in a System.CommonResponse component and set the type property to "AdaptiveCard".

You can use this element at the following levels in the System.CommonResponse component:

  • At the level of a card element within a cards response item. This allows you to define a single adaptive card structure that will be stamped out multiple times when an iteratorVariable has been specified for the card element.
  • At the level of a text response item, typically to create a single adaptive card. ( Multiple cards can be defined but the iteratorVariable property is not supported here.)

Note:

Microsoft Teams currently does not support a carousel with adaptive cards. In System.CustomResponse component metadata terms, this means that the card layout property is ignored. The cards will always be laid out vertically because horizontal layout (carousel) is simply not supported.

A second limitation to be aware of is that when a user taps on a button that is included with the adaptive card, the button label will not be printed out as user message in the conversation history. In other words, the user does not get a visual confirmation of which button she selected. This can lead to an inconsistent user experience, because buttons displayed with simple text messages, or buttons displayed with standard System.CustomResponse component cards (using the Microsoft Hero card) do print out the button label.

Example: Adaptive Card in Cards Response Item

To stamp out multiple cards, you can use the iteratorVariable with the card element within a response item of type cards. Here is an example to use an adaptive card to stamp out multiple pizza cards:

responseItems:
  - type: "cards"
    headerText: "Here are our pizzas you can order today:"
    cardLayout: "horizontal"
    cards:
      - title: "${pizzas.name}"
        description: "${pizzas.description}"
        imageUrl: "${pizzas.image}"
        iteratorVariable: "pizzas"
        actions:
          - label: "Order Now"
            type: "postback"
            payload:
              action: "order"
              variables:
                orderedPizza: "${pizzas.name}"
                orderedPizzaImage: "${pizzas.image}"
        channelCustomProperties:
        - channel: "msteams"
          properties:
            adaptiveCard:
              type: "AdaptiveCard"
              version: "1.0"
              fallbackText: "Adaptive card version not supported"
              body:
              - type: "TextBlock"
                text: "${pizzas.name}"
                weight: "bolder"
              - type: "TextBlock"
                text: "${pizzas.description}"
                wrap: true
              - type: "Image"
                url: "${pizzas.image}"
                horizontalAlignment: "center"
              actions:
              - type: "Action.Submit"
                title: "Order"
                data: 
                  action: "order" 
                  variables:
                    orderedPizza: "${pizzas.name}"
                    orderedPizzaImage: "${pizzas.image}"

Example: Adaptive Card in Text Response Item

You can define an adaptive card with a text response item as follows:

responseItems:
  - type: "text"
    text: "This text is replaced with adaptive card defined in custom property"
    footerText: "Is that correct?"
    visible:
      expression: "${system.channelType=='msteams' && system.entityToResolve.value.name=='Confirmed'}"
    channelCustomProperties:
      - channel: "msteams"
        properties:
          adaptiveCard:
            type: "AdaptiveCard"
            version: '1.0'          
            fallbackText: "Adaptive card version not supported"                                             
            body:
            - type: TextBlock
              text: 'I have all information needed to create your expense. Just to verify my understanding, here is an overview of your expense:'
              wrap: true
            - type: FactSet
              facts:
              - title: Expense Type
                value: "${expense.value.Type}"
              - title: Amount
                value: "${expense.value.Amount.totalCurrency}"
              - title: Date
                value: "${expense.value.Date.date?number_to_date}"
              - title: Receipt URL
                value: "${expense.value.Receipt?has_content?then(expense.value.Receipt.url,'N/A')}"
 
            actions:
            - type: Action.ShowCard
              title: Edit
              id: edit
              card:
                type: AdaptiveCard             
                version: '1.0'
                body:
                - type: TextBlock
                  size: Medium
                  weight: Bolder
                  text: Edit Expense
                - type: TextBlock
                  text: Expense Type
                  weight: Bolder
                - type: Input.ChoiceSet
                  choices:
                  - title: Metro, bus, train
                    value: Public transport
                  - title: Taxi
                    value: Taxi
                  - title: Breakfast, lunch, dinner
                    value: dinner
                  id: Type
                  value: "${expense.value.Type!''}"
                  spacing: None
                - type: TextBlock
                  text: Amount
                  weight: Bolder
                - type: Input.Text
                  id: amount
                  spacing: None
                  value: "${expense.value.Amount?has_content?then(expense.value.Amount.totalCurrency,'')}"
                - type: TextBlock
                  text: Date
                  weight: Bolder
                - type: Input.Date
                  id: Date
                  value: "${expense.value.Date?has_content?then(expense.value.Date.date?number_to_date,'')}"
                  spacing: None
                actions:
                - type: Action.Submit
                  title: Submit
                  id: submit

You can also define multiple adaptive cards in this custom property. To do so, you prefix the type property with a hypen (-) to indicate a YAML list rather than a map:

channelCustomProperties:
  - channel: "msteams"
    properties:
      adaptiveCard:
      - type: AdaptiveCard
        body: ...
      - type: AdaptiveCard
        body: ...

This can be convenient if you need to stamp out multiple static cards, but it will be more common to stamp out multiple cards using the iteratorVariable property.

Submit Actions

Adaptive Cards has a submit action (Action.Submit), which you can use to gather user input and send it to the skill.

You define the action's payload in the data property of the submit action. If you want the System.CommonResponse component to transition after the button is selected or set some variables, you can use the standard action and variables properties:

actions:
- type: "Action.Submit"
  title: "Order"
  data: 
    action: "order" 
    variables:
      orderedPizza: "${pizzas.name}"
      orderedPizzaImage: "${pizzas.image}"

If you're using input fields in your card, the name and value of these fields will be added as key-value pairs to the data JSON object. The example above with the Edit Expense card includes three fields to modify the expense type, amount, and date. When the user taps the Submit button in this case, a JSON object like the following will be sent:

{
  "Type" : "Taxi",
  "Amount" : "10.0 dollar"
  "Date" : "2019-09-02"
}

The System.CommonResponse component doesn't know how to process this information, as it does not follow the common payload structure with action and variables properties. To solve this, you have these options:

  • Convert the JSON payload to a string, which will then be matched for entities. If any matches are found, the variable set with the System.CommonResponse component will be updated with the corresponding entity value or entity values (in case of a composite bag entity).

    To configure this option, you add the boolean system.convertToString property to the data property of the submit action:

    actions:
    - type: Action.Submit
      title: Submit
      id: submit                   
      data:
        system.convertToString: true
  • Have the skill update variables with the same name as the input fields. In the above example, the "Type", "Amount" and "Date" context variables would be updated.

    To configure this option, you add the boolean system.setVariables property to the data property of the submit action:

    actions:
    - type: Action.Submit
      title: Submit
      id: submit                   
      data:
        system.setVariables: true

If you don't configure any of these options, the submitted values will simply be ignored.

When using a System.CommonResponse component with a composite bag entity, you will typically use the first option, which will populate all the matched entities in the bag based on the stringified JSON payload.

Note:

You need to set the System.CommonResponse component processUserMessage property to true for these submit actions to work.

Echo Text of Selected Button in Adaptive Card

When a user selects a button in an Adaptive Card, the conversation isn't updated to show that the user selected that option unless you include a messageBack action for the card.

To set up a messageBack action, see https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-actions#adaptive-cards-with-messageback-action.

Disable Buttons and Fields in Adaptive Cards

Though you can't technically disable buttons and fields in Adaptive Cards, you can create a similar effect by replacing the card when a submit action is invoked. You do so using the Boolean replaceMessage property that is specific to Microsoft Teams in the System.CommonResponse component.

To enable the card to be re-rendered in this way, add this property within the channelCustomProperties section of the custom response component:

        ...
           - type: "text"
             text: "This text is replaced with the adaptive card defined in custom property"
             channelCustomProperties:
               - channel: "msteams"
                 properties:
                   replaceMessage: "true"
                   adaptiveCard:
                     ...

You can also use an Apache FreeMarker expression to set the property's value.

Tips for Creating Adaptive Cards Definitions

The adaptive cards JSON schema is relatively complex with many different constructs supported. As such, it is error prone when you try to define the adaptive card content by hand directly inside the System.CommonResponse component. You may find it easier to use the following process to create the adaptive cards:

  1. With the visual tools in Microsoft's Adaptive Cards Designer, create the adaptive card definition.
  2. Click Copy Card JSON to get the definition in JSON format.
  3. Use an online converter (such as https://jsonformatter.org/json-to-yaml) to convert the definition to YAML.
  4. Copy the result into a text editor and insert the indentation that is required for where it will appear in the the dialog flow definition.
  5. Paste the resulting text into the dialog flow.

Note:

To keep up to date on the version of Adaptive Cards supported by Teams, see https://docs.microsoft.com/en-us/adaptive-cards/resources/partners. You can visit https://adaptivecards.io/explorer/ for a list of all elements and properties and the version they were introduced.

Keep in mind that the adaptive card designer does not check on the combination of the elements used and the version number of adaptive cards. For example, the ActionSet element was introduced in version 1.2, but the designer doesn't present you from adding this element, even if you have specified 1.0 as the version number in the designer.

If you want to use actions with 1.0, you can use the separate actions property below the body property. This actions element can't be added using the visual designer, so you'd need to do it by hand.

Customize the Welcome Behavior

When a user connects to a digital assistant through a Microsoft Teams channel, an internal message is sent to the digital assistant to initiate a conversation. By default, that message is the word "help", which then triggers the digital assistant's help system intent, which leads to the display of a welcome message and cards for the digital assistant's skills.

If you would like to change the digital assistant's behavior when a user connects through a Microsoft Teams channel, you can change the internal message that is sent to initiate the conversation (and thus trigger a different intent). The internal message that is set to the digital assistant is set in the digital assistant's Internal Welcome Message property. You can change the value for that property in the digital assistant's resource bundle.

To change the internal message that is set to the digital assistant when the user connects with a Teams, channel:

  1. Click icon to open the side menu to open the side menu, select Development > Digital Assistants, and open your digital assistant.
  2. In the left navigation for the digital assistant, click Resource Bundles icon, and select the Configuration tab.
  3. In the Filter field, type internal to quickly to narrow down the list of resource bundle keys.
  4. Select the Other - internalWelcomeMessage key.
  5. Mouse over the value for the key and select the Editicon that appears.
  6. Replace the value with the one you would like to use and click Update Entry.

Note:

If your digital assistant is on a platform version earlier than 21.04, resource bundle keys aren't automatically defined for the configuration properties. In that case, you may just wish to update the value of the property on the digital assistants Settings page (which you can open by clicking the Settings icon).