X

The Mobile & Digital Assistant Blog covers the latest in mobile and conversational AI development and engagement

TechExchange Quick-Tip: Extending the Oracle Web SDK Delegate Feature To Execute Code Asynchronously

Frank Nimphius
Master Principal Product Manager

article by Frank Nimphius and Asaf Lev, February 2020

 

This article explains how you can extend the Oracle Web SDK's delegate feature to execute code asynchronously. For example, when triggering navigation on the website or web application hosting the web messenger, there is no need to wait for navigation to complete to continue with the conversation. 

About the Oracle Web SDK and its Delegate Feature

The Oracle Digital Assistant Oracle Web SDK is both, an SDK and a complete web messenger. With the Oracle SDK you can integrate Oracle Digital Assistant as an embedded web widget or in a popup to your website or web application. However, you can also build your own messenger user interface using the JavaScript framework of your choice and only leverage the SDK programming interface to connect and communicate with the Oracle chat server. 

The delegate feature in Oracle Web SDK allows you to register callback functions with the Web messenger. The callbacks are invoked before bot responses get rendered, before a user message is sent to the bot, or before postback messages (actions that send complex payload structures) are send.

As a client developer you can use callback functions to access and modify the message payload, suppress the display or sending of a messages and to access custom metadata contained in a message.  Especially the latter, sending custom metadata in a bot response, allows deep integration of the Oracle Digital Assistant conversation with the hosting web site or application. Custom metadata may contain hints about APIs to call as well as payloads to pass to those APIs. Because custom metadata can be sent specific for a channel ("websdk" for th Oracle Web SDK), it wont be passed to all channels. 

A simple delegate object, as documented in the Oracle Digital Assistant product documentation looks as shown below. Note that each function defined in the object is optional. If provided, the functions must return the message at the end of their processing. 

const delegate = {
  beforeDisplay(message) { <your custom code here>; return message; },
  beforeSend(message) { <your custom code here>;<your custom code here>; return message; },
  beforePostbackSend(postback) { <your custom code here>;<your custom code here>; return postback; }

The delegate object reference can be configured as a property on the chat widget configuration object, added calling Bots.setDelegate(delegate) or passed as an argument when initiating the bot SDK (new Bots(delegate)). See the Oracle Digital Assistant product documentation for more information. 

beforeDisplay

The beforeDisplay delegate allows a skill's message to be modified before it is displayed in the conversation. The message returned by the delegate is used to display the message. If it returns a falsy value, like null, undefined, or false, then no message is sent.

beforeSend

The beforeSend delegate allows a user message to be modified before it is sent to the Oracle Chat Server. The message returned by the delegate is sent to the skill. If it returns a falsy value, like null, undefined, or false, then no message is sent.

beforePostbackSend

The beforePostbackSend delegate is similar to beforeSend, just applied to postback messages from the user. The postback returned by the delegate is sent to the skill. If it returns a falsy value, like null, undefined, or false, then no message is sent.

Implementing Asynchronous Code Execution

To execute code asynchronous when the Oracle Web SDK calls a callback function, you setup and trigger event listeners. The following code can be added to the website or web application or set to an external JavaScript file referenced from the website or web application. 

Delegate object

const delegate = {
   beforeDisplay: function (msg)
   {                
       $.when($(window).trigger("beforeDisplayEvent",[msg]));
       console.log("beforeDisplayEvent completed sending");
       <optional: custom code>;
       return msg;
   },
    beforeSend: function(msg) {<add similar code as shown above>; return msg;},
    beforePostbackSend: function(msg){<add similar code as shown above>; return msg;}
  };

The code in the beforeDisplay callback function uses JQuery to trigger a custom event beforeDisplayEvent. The "beforeDisplayEvent" name can be changed by you and works for as long as the registration of listeners use the same name. 

When the event is triggered, the sample prints a console message, which in your case could be code you add to work with the message sent from the bot or typed by the user. 

Event listener

For the code that you want t execute asynchronously, you can define listeners. Below you find two listener definitions for the beforeDisplayEvent: One that immediately executes a print statement, and a second that does the same with a small delay. 

//Add event listeners
$(window).on("beforeDisplayEvent", function(event, message)
{
   setTimeout(function(){ console.log("Done async handler 1: "+JSON.stringify(message.messagePayload)); }, 2000);      
});

$(window).on("beforeDisplayEvent", function(event, message)
{    
   console.log("Done async handler 2: "+JSON.stringify(message.messagePayload));   
});

Note: JSON.stringify(message) is used to display the content of the message object. The message payload in this example is a simple JSON object. The payload 

Adding JQuery

Because the code uses JQuery, you need to make sure JQuery is added to the hosting website. For this you use code as shown below in the website markup

 <script src="https://code.jquery.com/jquery-3.4.1.min.js"
             integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo="
              crossorigin="anonymous">

</script>

If the delegate and the listeners are defined in a separate JS file (e.g. settings.js) then you also need to add the following markup to the page

 <script src="scripts/settings.js"></script>

 

Example

The image below shows the print messages of the two listeners and the console.log statement in the delegate function. Notice how the first listener prints its message delayed and after the console.log statement in the delegate function.

Conclusion

This article showed how to execute code asynchronously from the Oracle Bots Web SDK delegate object's call back functions. 

Related Content

Product documentation about Oracle Web SDK (a must read!)

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

TechExchange Quick-Tip: How To Use Custom Channel Properties With Oracle Web SDK Messenger To Add Custom Metadata To Bot Responses

TechExchange Quick-Tip: How to Embed YouTube Videos In Oracle Digital Assistant Web SDK (Web Messenger)

TechExchange Quick-Tip: Using RAW Message Payloads in Custom Components to Leverage Channel Specific UI Extensions (MS TEAMS Example)

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

 

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.