Azure Bot Services: Using Adaptive Cards

Adaptive Cards enables you to render rich content that the user can interact with channels like Microsoft Teams. When the user interacts with an action on an Adaptive Card, their input will be sent to your Flow and it is accessible in ci.data.request.value

Triggering NLU for Card Actions

If you for instance ask the user to pick a date, then you might want the selected date to be parsed using Cognigy NLU so that you can use our DATE Slot. To enable NLU parsing of certain fields in an Adaptive Card, you need to prefix the id of the field with cognigy_.

Example:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Default text input"
    },
    {
      "type": "Input.Text",
      "id": "cognigy_input1",
      "placeholder": "enter comment",
      "maxLength": 500
    },
    {
      "type": "TextBlock",
      "text": "Multiline text input"
    },
    {
      "type": "Input.Text",
      "id": "cognigy_input2",
      "placeholder": "enter comment",
      "maxLength": 500,
      "isMultiline": true
    },
    {
      "type": "TextBlock",
      "text": "Pre-filled value"
    },
    {
      "type": "Input.Text",
      "id": "input3",
      "placeholder": "enter comment",
      "maxLength": 500,
      "isMultiline": true,
      "value": "This value was pre-filled"
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "OK"
    }
  ]
}

In the example above, a card with three text fields will be rendered. Since the ids of the first two text field is set to cognigy_input1and cognigy_input2 the value of these fields will be added to ci.text in your Flow and will therefore be parsed with our NLU. You can therefore e.g. trigger an intent or slots based on the value of the two first input fields in the Adaptive Card above.

Using Postbacks with Adaptive cards

You can also use postback buttons on your Adaptive Cards and have them send pre-configured data to your Flow, which can even be parsed by our NLU. In the example below, an Adaptive Card to create a user in Hubspot with two buttons is created - one button to confirm creating an account for the user and one button to decline. In order to send the information of which button the user clicked to your Flow, you can add the key cognigy_postback to the data object of the Action.Submit with an appropriate value. In the example below, clicking on the confirm button will send the text "yes" to your flow, and clicking the decline button will send the text "no" to your Flow. You can combine this functionality with the Trigger Intent to manually trigger an intent in your Flow after a postback button is clicked on an Adaptive Card.

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "Image",
      "style": "default",
      "url": "https://sharpspring.com/wp-content/uploads/2017/12/hubspot-400x200.png",
      "size": "Large"
    },
    {
      "type": "ColumnSet",
      "columns": [
        {
          "type": "Column",
          "items": [
            {
              "type": "TextBlock",
              "text": "We found a user matching the email address {{cc.user.email}} in Hubspot CRM!\n\n",
              "wrap": true
            },
            {
              "type": "FactSet",
              "facts": [
                {
                  "title": "Firstname:",
                  "value": "{{cc.hubspot.properties.firstname.value}}"
                },
                {
                  "title": "Lastname:",
                  "value": "{{cc.hubspot.properties.lastname.value}}"
                },
                {
                  "title": "Company:",
                  "value": "{{cc.hubspot.properties.company.value}}"
                }
              ]
            },
            {
              "type": "TextBlock",
              "text": "Do you want to create an account for this user?\n\n",
              "wrap": true
            }
          ],
          "width": "stretch"
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "Yes please",
      "data": {
        "id": "_qkQW8dJlUeLVi7ZMEzYVw",
        "cognigy_postback": "yes"
      }
    },
    {
      "type": "Action.Submit",
      "title": "No, a different user",
      "data": {
        "id": "_qkQW8dJlUeLVi7ZMEzYVw",
        "cognigy_postback": "no"
      }
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.0"
}

Link: Adaptive Card Designer

Limitations

• Different implementations are required depending on endpoint

  • In Cognigy's Agent space the containers for the Adaptive Card JSON differs slightly and requires slightly different implementations.  This means when creating nodes to house the adaptive card content you may need to add separate channels.
    

• Response handling may differ based on endpoint.

  • Responses vary slightly when a user submits a card depending on endpoint so handling responses requires slight adjustments per endpoint.

    Teams response comes through in the object input.data.request.value

    Web response comes through in the object input.data.adaptivecards

• Styling and features may be limited depending on the endpoint

  • As an example button types may show different colors depending on how the endpoint renders the json. If a brand wants strict control over looks Adaptive Cards might not be for them.

Debugging

• Check for invalid elements like extra commas, Teams unlike some other endpoints will fail to render invalid Adaptive Card JSON.
• Adding backgroundImage attributes like the following will cause Teams to fail to render an Adaptive Card
  
  "backgroundImage": { "verticalAlignment": "Bottom"}
• Using the wrong container for the wrong endpoint can cause issues.  For instance mixing the web and teams container json can cause issues.