article by Frank Nimphius, January 2020
updated, May 2020 for Oracle Web SDK 20.5.1 and later
In Oracle Digital Assistant, bot responses and user messages are typically sent as JSON payloads that contain the message content and metadata information for the messenger client to render a message.
The metadata is dependent on the messenger client and includes instructions for the UI component (usually a template reference) to render the content and postback content that is returned when a user performs an action such as pressing a button or making a selection in a list. Channels in Oracle Digital Assistant are responsible for converting Oracle Digital Assistant internal metadata into a format that is understood by the target messenger.
Messenger however may support features that are not available for all messengers. In this case, using the System.CommonResponse component, you can use the channelCustomProperties property to send channel-specific instructions that are then sent to the client as is. In a previous article, I explained the property by example fo Microsoft Teams adaptive cards. The Oracle Digital Assistant product documentation provides detailed overview of channel specific extensions you can use with different messengers. Please see:
The Oracle Web SDK is a new SDK and web messenger available in the OCI versions of Oracle Digital Assistant (version 19.10 and later). The messenger is written in JavaScript and can be added to your website and web applications. It exposes events that you can use to intercept bot responses before they are displayed, and a headless model that lets you write your own messenger web client. In both cases, you may want additional metadata information to be added to the bot response, which is exactly what you can use the customChannelProperties of the System.CommonResponse component for. This article explains how to add custom channel properties to a bot response, how to restrict the information to be added only to responses that are passed to the web messenger and how to deal with the information in a web application.
The use case
The use case for this article came in as a question from Geertjan Wielenga from the Oracle JET product management team. Geertjan worked on a 2-minute TechTip video about integrating Oracle Digital Assistant with Oracle JET for the Oracle Groundbreaker YouTube channel and did look for a way to pass information in a bot response back to Oracle JET without parsing the full bot message. The image below shows a simplified solution to Geertjan's question.
As you can see, the bot response is a quite long text message that contains a product name as well as a price. Both information is what Geertjan wanted to send back to Oracle JET. On the right side of the image, you see the console log with this information. The sample I built for this article doesn't use Oracle JET and so, to simulate Geertjan's requirement, I used a log message instead of a call back into Oracle JET to handle the metadata information.
About Channel specific extensions
As mentioned earlier, you can use the System.CommonResponse component in Oracle Digital Assistant to render all sorts of user interfaces and to pass channel specific extras. The image below is a description I copied from our product documentation:
———————————————————————————————————————————————————————
———————————————————————————————————————————————————————
The image also shows how the channelCustomProperties is used for a specific channel. The CHANNEL_NAME placeholder in the image can be replaced with a channel name like facebook, slack, twilio, websdk (for the new Oracle Web channel) and other.
Oracle Web Messenger Customization Example
The code snippet shown below is from the sample I created for this article. As you can see, the dialog flow state uses the System.CommonResponse component to render the bot response as a text message. The use of the channelCustomProperties is highlighted. Notice the use of the channel name "websdk" and the list of properties. I added a state property to allow the client developer (the programmer who implements the messenger event handling) to distinguish between text responses. I then added a property order and price with the information that you would want to e.g. pass to the containing website or web application like Oracle JET.
Note: You can freely choose the name of the properties as well as the number of properties you add to the bot response. Unlike 3rd party messengers like Facebook, you can change the messenger client to "listen" for the added properties and implement the code handling them.
After downloading the Oracle Web SDK, you find a developer guide in the downloaded ZIP file. The developer guide, which is also part of the Oracle Digital Assistant product documentation, explains how you can create and register a delegate object that allows you to intercept user and bot messages before they are sent or displayed. The URL below is a pointer to the chapter in the product documentation.
The screen shot below shows the part n the documentation that explains the delegate object. As you can see, the JavaScript function in the object received a message object, which is a JSON payload of the message to display or send.
The code shown in the image below is from the sample I built for this article. As you can see, I used the beforeDisplay function to first check that the message type is "text". I then looked for the "state" property that I passed within the System.CommonResponse component channelCustomProperties property. If the state name matched to "displaySelectedProduct", I used a console log statement to print the order and price information. In Geertjan's Oracle JET requirement, this is where you would pass the price and order back to the Oracle JET application.
Update May 2020: The "message" object argument structure has changed in Oracle Web SDK 20.5.1 and later. To access the channelExtensions object you now use message.messagePayload.channelExtensions. Same for all other attributes that can be accessed through the message argument,
Example for Oracle Web SDK before 20.5.1
Example for Oracle Web SDK 20.5.1 and later
Note: If you are curious of what the format of a message is, then, beside of reading the developer guide or product documentation, you could put a console.log statement into one of the delegate functions to print the JSON.stringify(message.messagePayload) string. For the confirmation message in the example, the message payload looks as shown below:
{
"text":"For only 12.50 USD, you ordered\n\nBacon Pasta\n\nCreamy carbonara-style tagliatelle with cream and pancetta.\n\ncarbs: 75g\nkcal: 500\nprotein: 21g\nsalt: 0.8g \n\nYou chose \"cream\" for your extras",
"type":"text",
"channelExtensions":{"price":"12.50 USD","state":"displaySelectedProduct","order":"Bacon Pasta"}
}
Note: Notice the channelExtension object added to the bot response. The content of the channelExtension object is not displayed in the messenger. However, you could change the message object passed into the function and return the changed content for display in the messenger.
To use the delegate object, you need to change the initSdk function that initializes the web messenger for your web site or web application. Line 64 in the image below contains the code that passes the delegate object to the messenger.
Error handling: What if you see this?
If you see a bot response as shown in the image below, then you messed up. The bot prints the JSON format of a message e.g. when the delegate object function contains invalid JavaScript syntax, command that don't exist in JavaScript or access objects that don't exist (without wrapping the access is a try-catch block).
Error messages like this don't mean the end of the world and, as you can see, also happened to me. To fully understand what the problem is, I recommend opening a debugging window in your browser. If you use Chrome, then you access such a tool from More Tools –> Developer Tools in the browser menu.
Summary
When working with the Oracle Web Messenger, you should use the System.CommonResponse component to render bot user interface. The System.CommonResponse component allows you to use the channelCustomProperties property to pass additional information to the Oracle web messenger that you can use within the SDK code to customize the rendering of content or to pass information to the web application or website that host the messenger without needing to parse the display text. Being able to sent custom properties with bot responses, cards and actions is a powerful mechanism and useful for a wide range of customizations. Most importantly, it is very useful for customers who use the web messenger SDK in headless mode to implement their own messenger UI.
Related Content
TechExchange: Integrating Oracle Digital Assistant Web Messenger in Oracle JET Web applications
TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube
TechExchange Quick-Tip: Optimize Bot Responses for a specific Channel in Oracle Digital Assistant
