WebChat Adaptive Cards

Adaptive Cards Adaptive Cards are preformatted boilerplate messages that can be selected by an agent to be sent to a client. They are written using an open card exchange format that allows the developers to 'write once' and share with any compliant host application can be used as UI components for WebChat 2. This article describes how Adaptive Cards are used with AnywhereNow's WebChat service.

Building Adaptive Cards

Adaptive cards are portable code snippets that can be used to enhance the UI.

Useful URLs

• Various examples of Adaptive Cards can be found here: https://adaptivecards.io/samples/

• An intuitive designer tool you can use to create your own Adaptive Cards can be found here: https://adaptivecards.io/designer/

  Important

  By default, the Microsoft Adaptive Cards designer site creates version 1.6 adaptive cards. This can be set to version 1.0 by selection the desired version in Target Version, this way you can only select supported features.

Key value pairs

The WebChatDialogueProvider2 will react to specific values, so they will be used as features. Currently the following key value pairs are available:

• standard.customerName = This name will be shown to the Agent

  Tip

  This can also be done using a command, see: Setting User Data

• standard.customerUri = This URI will be used on the conversation. This will value will be visible and used in:

  • Reporting = Conversation will be registered on the entered URI in the database. This information will be used in the PowerBI Template.
  • Queue = Conversation will be visible in the queue on the entered URI.
  • Text Search = Conversation will be search-able in the Text Search with the entered URI.
  • Timeline = Timeline information will be retrieved based on the entered URI.
  • CRM Customer Relationship Management, or CRM, is (usually) a software-based, data management method to deal with interactions with customers and potential customers. Service = If the CRM Service is configured, this URI will be used to look up the contact based on email address.
  • CTI Plugin = If the CTI Plugin is used, this URI will be used to look up the contact based on email address.

  Important

  The standard.customerUri must be in an email address format (e.g., example@domain.com). If the provided URI does not follow this format, it will default to the generic placeholder URI.

  Tip

  This can also be done using a command. Setting User Data

• standard.subject = This value can be used in the PluginFlowSettings (Learn More) to better route the customer.

Building a Response

The response is build up as a JSON, this enabled a lot of flexibility. For example a unique response or Target URI per SubmitID (I.e. Button in the responsive card).

Useful links

• Validate your JSON: https://jsonformatter.curiousconcept.com/

  Warning

  An incorrect JSON will cause the Adaptive Card to not be loaded.

How to build JSON Scripts

Below we have an example of a Response:

{
  "Actions": [
    {
      "Id": "Submit",
      "TargetUris": [
        "https://prod-114.westeurope.logic.azure.com:443/workflows/"
      ],
      "Response": {
        "Content": "One of our Agent will reach out during business hours on {standard.customerUri}",
        "Type": "Message"
      }
    }
  ]
}

• Actions (Object) = In this object the actions are stored that can be performed by the Adaptive Card response

  • Array = In this array one or more actions (object) can be stored.

    Note

    Each object needs to be comma separated

    • Id (name/value pair) = In this string matched the SubmitId that is created in the Adaptive Card

    • TargetUri (Object) = In this object one or more strings can be stored. All the submitted values from the Adaptive Card will be posted to the TargetUri

      Note

      Each object needs to be comma separated

    • Response (Array) = In this array the response can be defined.

      • Content (name/value pair) = In this string will be send as a response to the customer after submitting.

        Tip

        You can use brackets {} to replace content with submitted data.

      • Type (name/value pair) = In this string you can define the response type. For now only  "Message" is used.

Storing Adaptive Cards

Before Adaptive Cards can be loaded into the WebChat 2 they needs to be added to SharePoint first, Learn More

Configuration

An Adaptive Card can be used as the first message (before the chat is initiation) or as a post-conversation (after the webchat session has been completed)

As First Message

This tease message can be configured with the following settings:

interface TeaseMessageSettings {
    message: string,
    showAsMessage: boolean,
    onScrollPercentage: number,
    onTimeout: number
}

These values can be set as follows:

• Adaptive card id = The ID of the Adaptive Card that is configured on SharePoint.

• Adaptive card disable input = If enabled the chat input will be disabled until the Adaptive Card has been submitted. This is to ensure the customer completes the Adaptive Card before starting the conversation.

Example

Below an example script that can be loaded into your website's html. In this example we loaded a webchat with a tease message:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<script type="text/javascript" src="webchat.bootstrap.js"></script>
<script>
window.onload = function() {
    const config = {
        available: {
            state: 'Enabled',
            adaptivecard: {
                id: 'QuestionForm',
                disableInput: false
            }
        },
        away: {
            state: 'ChatInteractionDisabled',
            adaptivecard: {
                id: 'ContactForm',
                disableInput: true
            }
        },
        offline: {
            state: 'Hidden'
        }
    };
WebChat.load(config);
};
</script>

As Post Message

In order to send an Adaptive Card after the dialogue is finished, the WebChat config in the WebChat frontend has to be extended with an Adaptive Card ID, see example below.

postDialogue: {
    adaptivecard: {
        id: 'AdaptiveCardId',
    }
}

An example of the complete file would look something like this:

<script type="text/javascript" src="webchat.bootstrap.js"></script>
<script>
window.onload = function() {
    const config = {
        available: {
            teaseMessageSettings: {
                showAsMessage: true,
                showAsTeaser: true,
                onTimeout: 5000,
                message: {
                    en: ' Hi Can we help you?',
                    nl: ' Hoi Hoe kunnen we u helpen?'
                }
            },
            state: 'Enabled'
        },
        postDialogue: {
            adaptivecard: {
                id: 'AdaptiveCardId'
            }
        }
    };
    WebChat.load(config);
};
</script>

Adaptive Cards Examples

Question Form

This card will ask the customer some questions. The entered fields will be used by the WebChatDialogueProvider2.

Adaptive Card Payload:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0",
    "body": [
        {
            "type": "TextBlock",
            "text": "Question Form",
            "wrap": true,
            "size": "ExtraLarge"
        },
        {
            "type": "TextBlock",
            "text": "Before we start chatting, tell us a bit about yourself.",
            "wrap": true
        },
        {
            "type": "TextBlock",
            "text": "What is your name?",
            "wrap": true
        },
        {
            "type": "Input.Text",
            "id": "standard.customerName",
            "spacing": "None"
        },
        {
            "type": "TextBlock",
            "text": "What is your email?",
            "wrap": true
        },
        {
            "type": "Input.Text",
            "placeholder": "user@domain.com",
            "id": "standard.customerUri",
            "spacing": "None"
        },
        {
            "type": "TextBlock",
            "text": "What is your question about?",
            "wrap": true
        },
        {
            "type": "Input.ChoiceSet",
            "choices": [
                {
                    "title": "Support",
                    "value": "Support"
                },
                {
                    "title": "Sales",
                    "value": "Sales"
                },
                {
                    "title": "Other",
                    "value": "Other"
                }
            ],
            "placeholder": "Placeholder text",
            "id": "standard.subject",
            "spacing": "None"
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Let's get started",
            "id": "submit"
        }
    ]
}

Response:

{
  "Actions": [
    {
      "Id": "submit",
      "TargetUris": [],
      "Response": {
        "Content": "Thanks {standard.customerName} for sharing, let's look for an agent.",
        "Type": "Message"
      }
    }
  ]
}

Contact Form

This card can be used when the WebChat is outside business hours, so the Agent received the request the next work day and can directly call the customer.

Adaptive Card Payload:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0",
    "body": [
        {
            "type": "TextBlock",
            "text": "Contact Form",
            "wrap": true,
            "size": "ExtraLarge",
            "weight": "Bolder"
        },
        {
            "type": "TextBlock",
            "text": "Our chat is currently un-available. Please leave your contact details, so we can reach you back.",
            "wrap": true
        },
        {
            "type": "TextBlock",
            "text": "Phonenumber",
            "wrap": true
        },
        {
            "type": "Input.Text",
            "placeholder": "+3123456789",
            "id": "standard.customerUri",
            "spacing": "None"
        },
        {
            "type": "TextBlock",
            "text": "Subject",
            "wrap": true
        },
        {
            "type": "Input.ChoiceSet",
            "choices": [
                {
                    "title": "Support",
                    "value": "Support"
                },
                {
                    "title": "QuickSupport",
                    "value": "QuickSupport"
                }
            ],
            "id": "Skill",
            "spacing": "None"
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Submit",
            "id": "submit"
        }
    ]
}

Response:

{
  "Actions": [
    {
      "Id": "submit",
      "TargetUris": [
        "https://prod-114.westeurope.logic.azure.com:443/workflows/"
      ],
      "Response": {
        "Content": "One of our Agent will reach out during business hours on {standard.customerUri}",
        "Type": "Message"
      }
    }
  ]
}

WebAgent Transcripts

A transcript can be created by using a PostDialogue Adaptive Card. The Adaptive Card needs to have a button of type Action.Submit and an id standard.transcript. The response object of the Adaptive Card needs to have a Action with the same id as the button standard.transcript. When the customer clicks on the button and the Adaptive Card is sent, the WCDP2 will automatically add a link at the end of the response message to allow the customer to download the transcript.

The agent sends a new PostDialogue Adaptive Card every time the conversation is handled. If the customer decides to continue the conversation after the agent ended it, the transcript will be replaced in the database by the new transcript and will be sent to the customer the same way as the first transcript.

How to enable WebChat Transcripts

The following SharePoint settings are mandatory: (if not set this will cause an exception with the message 'connection string not found')

Example of a PostDialogue Adaptive Card with transcript functionality

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0",
    "body": [
        {
            "type": "TextBlock",
            "text": "Contact Form",
            "wrap": true,
            "size": "ExtraLarge",
            "weight": "Bolder"
        },
        {
            "type": "TextBlock",
            "text": "Would you like the transcript of this conversation?",
            "wrap": true,
            "color": "Dark"
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Yes please",
            "id": "standard.transcript"
        }
    ]
}

Example of Adaptive Card response

{
    "Actions": [{
        "Id": "standard.transcript",
        "TargetUris": [],
        "Response": {
            "Content": "<b>Your transcript is ready!</b>",
            "Type": "Message"
        }
    }]
}