article by Frank Nimphius. December 2019

 

Connectors in Oracle Digital Assistant ensure that the bot response is rendered best for different messengers. The foundation of this rendering is the conversation message model (CMM) that is the metadata used by Oracle Digital Assistant built-in components to define the bot user interface. The metadata is then transformed by connectors to the format expected by messengers like Facebook, Slack, MS Teams and many more. Custom components integrate with CMM through the MessageModel class in the Oracle custom component SDK. 

Like when using the System.CommonResponse component channelCustomProperties component (as explained in another Oracle TechExchange article*), you can return a message payload from custom components that are messenger specific and that allow you to use layout extensions available on a specific messenger channel. By doing so, you bypass the payload format transformation in the channel connectors and instead post the payload "as is" to the messenger client. 

In this article, I explain how you use the MessageModel's RAW message format to send a channel specific layout. The example used is Microsoft Teams' adaptive card layout. 

*) Tech-Exchange Quick-Tip: Adding Channel Specific UI Extensions Using the System.CommonResponse Component ChannelCustomProperties Property (MS Teams Example)

Example

The image below shows the the output rendered by the custom component that you can download for this article. The custom component uses multiple text messages and an attachment message to print a confirmation for a pasta order. 

If the channel type that the bot runs on is detected as "msteams" then the custom component changes the confirmation rendering using Microsoft's Adaptive Card layout. Note that similar customization can be applied for other channels like Slack or Facebook as well. However, note that only Microsoft supports Adaptive Cards, as it is an extension of the Microsoft platform. 

 

Code Example

The complete custom component code can be downloaded from a link at the end of this article. The image below shows the part in the code that determines the channel type. If the channel type is "msteams", then the custom component applies the JSON format for an adaptive card to a variable (the image below does not show the full JSON code)

The component then creates a Raw message using the custom component MessageModel class. The raw message takes the JSON payload object as an input and passes it to the Microsoft Teams channel in a call to conversation.reply(…). 

Because the rawConverterMessage call is not transformed by the channel specific connector, it gets passed "as is" to the Microsoft Team channel. In response the channel renders the adaptive card as shown in an image shown earlier. 

MS Teams Adaptive Card Design

Microsoft provides a browser based visual design time that you can use to compose your bespoke layout. Once you are happy with the design, you can copy the JSON code and add it to the custom component to put out when the channel is detected as "msteams". Have a look at the sample custom component to understand where to put the code. 

https://adaptivecards.io/designer/

As mentioned, other channels like Facebook also support JSON based templates. You can adapt the sample code in this article to support other channel specific layouts as well. 

Sample Source Downloads

1. Sample Skill

  1. Import the skill to Oracle Digital Assistant 19.12 or later
  2. Train the skill
  3. Create a channel configuration for MS Teams 
    See: https://docs.cloud.oracle.com/iaas/digital-assistant/doc/microsoft-teams.html#GUID-7E688AA4-6C63-4F1E-99CB-06773BD0A878 
  4. Run the bot on the MS Teams messenger
  5. As a message, type "I like to order pasta".
  6. Then follow the conversation until you see the final confirmation message, which is an adaptive card rendered by the custom component

2. Custom Component Source Code

Read the source code to lean about sending RAW message payloads from a custom component. The custom component uses MS Teams specific payload to render an adaptive card. Similar approaches can be used to render specific layouts on other messengers like e.g. Facebook

Related Content

TechExchange: How-to Build Card Layout Responses from Custom Components

Tech-Exchange Quick-Tip: Adding Channel Specific UI Extensions Using the System.CommonResponse Component ChannelCustomProperties Property (MS Teams Example)

TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube

 

Author