Oracle Digital Assistant: Access a Skill from Your Website

Before You Begin

This 45-minute tutorial shows you how to use the Oracle Native SDK for Web/JavaScript (also known as Oracle Web SDK) to add to your web site a chat window that communicates with an Oracle Digital Assistant skill. You'll start with a basic web interface and then learn how to use the SDK to customize and enhance the behavior and look and feel.

This is the first tutorial in a series:

Access a Skill from Your Website
Secure Your Web App Chat with Client Authentication

Note: This tutorial won't work if you're using Oracle Digital Assistant Release 19.4.1, because the version of the SDK that this tutorial requires is available only for instances of Digital Assistant that have been provisioned on Oracle Cloud Infrastructure (Gen 2). For information on setting up a web channel on Digital Assistant 19.4.1, see Expose Your Digital Assistant through a Web Channel.

Background

While your customers can access your skills through many platforms, such as Android apps, Twilio SMS, Facebook Messenger, WeChat, and Slack, they also can access skills directly from your website through the Oracle Web SDK. This feature gives your customers the opportunity to ask questions, complete transactions, resolve problems, and so on, as they browse your web pages.

The SDK's features include:

Configurable components, such as
- Timestamp display
- Chat bubble size and padding
- Font color and size
- Custom buttons and icons
- Chat widget size
Autocompletion of text
JWT client authentication

The SDK connects to the Oracle Chat Server, which stands between Oracle Digital Assistant and the skill (or digital assistant). The chat server then passes messages to the skill for processing and delivers the skill's response to the client.

Illustration of the Web SDK interface with Oracle Digital Assistant

What Do You Need?

Oracle Digital Assistant 20.01 or later.
Oracle Web SDK 20.8.2 or later unziped into a folder of your choice. You can download this SDK from your Digital Assistant instance by opening the side menu and then clicking Downloads.
One of the following supported browsers:
- Firefox
- Chrome
- Safari
- Edge

Set Up the Folders

Let's start by creating a folder and adding the necessary artifacts.

Create a folder, such as chat-page.
This tutorial provides starter files for the web page that you'll build. Download chat-page.zip into the folder, and then unzip it.
Your folder should now contain index.html and the css, images, and scripts subfolders.
Copy native-client-sdk-js/web-sdk.js from your Oracle Web SDK folder and put it in the scripts subfolder.
(Optional) Open index.html from a browser to see the initial version of the web page.

Set Up Your Skill

We've provided a pizza ordering skill that you'll use for this tutorial. Follow these steps to create and train your skill.

In your Oracle Digital Assistant instance, click the hamburger icon to open the side menu, and then click Development > Skills.
Search for Web SDK Order Pizza.
If your instance doesn't have this skill, then do these steps:
- Download web-sdk-order-pizza-skill-1.2.zip to your system.
- On the Skills page in your Digital Assistant instance, click Import Skill and import the downloaded ZIP file.
  If you don't see the imported skill, try reloading the page.
On the Web SDK Order Pizza card, click Options and then click Clone.
Give the cloned skill a unique Name. For example, prepend WebSDKOrderPizza with your initials, such as ABWebSDKOrderPizza.
Note: The name must begin with a letter and may contain only letters, numbers, periods, and underscores. It can't exceed 100 characters.
Provide a Display Name, such as AB Web SDK Order Pizza, and leave all other values as is.
Select Open cloned skill afterwards.
Click Clone.
Click Train, ensure that Trainer Ht is selected, and then click Submit to train the skill.
Note that you use HT training in this tutorial, which is quick but superficial. For production work, you should use Tm training, which results in better intent resolution.
Optionally, click Skill Tester , select the Oracle Web channel, and then enter hi to try out the skill.
When you are done, close the tester.

Create an Oracle Web Channel

You use an Oracle Web channel to enable an Oracle Web chat widget to connect to your skill.

For the purposes of this tutorial, you won't restrict the allowed domains, nor will you enable client authentication. For production work, you should do both, as described in Secure Your Web App Chat with Client Authentication.

In the left Navigation menu, click Channels, and then click Users.
Click + Channel.
Set these values:
- Name: A unique name for the channel, such as ABOracleWebChannel
- Description: Channel for the Web SDK tutorial.
Channel Type: Oracle Web
Allowed Domains: * (asterisk)
Client Authentication Enabled: Switch to Off
Session Expiration (minutes): Use the default value
Click Create
Select the channel that you just created. Then, in the Route To drop-down list, choose the skill that you just created.
Switch Channel Enabled to On.
Make a note of the Channel ID, which you need to configure your chat widget.
Also make a note of the Oracle Digital Assistant host and domain name from the instance's URL, which appears in the browers's address field. Don't include https://.
For example: xxxx.xxx.digitalassistant.xxx.xxx.com

Your instance is now set up for you to connect the pizza ordering skill to a web page's chat bot.

Add a Chat Widget to the Web Page

To get started, you'll create settings.js, add add a chat widget to the file, and set some essential configurations.

In the scripts folder (chat-page/scripts in our example), create a file named settings.js, and open it in an editor.

Click Copy Copy in the following code box to copy the code, and then paste the copied code into the settings.js file.

'use strict';

// Set client auth mode - true to enable client auth, false to disable it
const isClientAuthEnabled = false;

/**
 * Initializes the SDK and sets a global field with passed name for which
 * it can be referred to later.
 *
 * @param {string} name Name by which the chat widget should be referred
 */
const initSdk = (name) => {
    if (!name) {
        name = 'Bots';          // Set default reference name to 'Bots'
    }
    let Bots;

    setTimeout(() => {
        /**
            * SDK configuration settings
            * Other than URI, all fields are optional with two exceptions for auth modes
            * In client auth disabled mode, 'channelId' must be passed, 'userId' is optional
            * In client auth enabled mode, 'clientAuthEnabled: true' must be passed
            */
        let chatWidgetSettings = {
            URI: '<URI>',
            clientAuthEnabled: isClientAuthEnabled,
            channelId: '<channelID>' 
        };

        // Initialize SDK
        if (isClientAuthEnabled) {
            Bots = new WebSDK(chatWidgetSettings, generateToken);
        } else {
            Bots = new WebSDK(chatWidgetSettings);
        }

        // Connect to the ODA
        Bots.connect();

        // Create global object to refer Bots
        window[name] = Bots;
    }, 0);
};

Set these chatWidgetSettings properties:
- URI: This is the host and domain name that you noted when you created the Oracle Web channel. For example: xxxx.xxx.digitalassistant.xxx.xxx.com.
  Don't include https://.
- ChannelId: This is the channel ID that you noted when you created the Oracle Web channel. For example: 12a45b92-2c85-88aa-810d-1dc0d1cfe472.
For example:
```
        let chatWidgetSettings = {
            URI: 'xxxx.xxx.digitalassistant.xxx.xxx.com',
            clientAuthEnabled: isClientAuthEnabled,
            channelId: '12a45b92-2c85-88aa-810d-1dc0d1cfe472'
        };
```
Save your changes.
In an editor, open the index.html file that's in the top folder.

Add this code just before the </head> tag.

    <script src="scripts/settings.js"></script>
    <script src="scripts/web-sdk.js" onload="initSdk('Bots')"></script>

Save your changes.
Let's try out the chat widget. Open your index.html file in a browser.
Click the chat-widget icon to open the chat window.
Type hi to start a conversation with the Web SDK Order Pizza skill.
Type order pizza to verify that you get a response.
(Optional) Continue the conversation until you complete the order.

Modify the Widget's Behavior

Now that you've seen the widget's default behavior, let's modify settings.js to make some minor customizations, such as:

Showing the connection status
Positioning the messages at the bottom of the chat window
Automatically opening the chat window
Repositioning the window
Showing choices in a different format

You'll also modify the behavior so that the user doesn't have to type anything to initiate the conversation.

To show the connection status in the chat window, add this property to settings.js just before the URI property in the chatWidgetSettings object:
```
            showConnectionStatus: true,
```
To display the initial messages at the bottom instead of the top, add this property just before the URI property:
```
            conversationBeginPosition: 'bottom',
```
Put these properties just before the URI property to automatically open the chat window and to position the bottom right corner of the chat window 2 pixels from the bottom and 2 pixels from the right side of the browser window:
```
            openChatOnLoad: true,
            position: {bottom: '2px', right: '2px'},
```
By default, the chat window displays choices like this:

To display the choices as pills, as shown here, add this property just before the URI property:
```
            displayActionsAsPills: true,
```

The user has to type something to initiate the conversation with the skill. You can avoid that by passing a hidden message to the skill. Add this property just before the URI property:

            initUserHiddenMessage: 'Hello',

After this change, your chatWidgetSettings object should look like this (with your own URL and channel ID):

    var chatWidgetSettings = {            
        showConnectionStatus: true,
        conversationBeginPosition: 'bottom',
        openChatOnLoad: true,
        position: {bottom: '2px', right: '2px'},
        displayActionsAsPills: true,
        initUserHiddenMessage: 'Hello',
        URI: 'xxxx.xxx.digitalassistant.xxx.xxx.com',
        clientAuthEnabled: isClientAuthEnabled,
        channelId: '12a45b92-2c85-88aa-810d-1dc0d1cfe472'
    }

Save your changes.
To see your changes, Shift+Reload index.html in your browser.
Notice that the chat window opens and displays the skill's first response automatically. Also notice that it shows the connected status.

Embed the Widget in an HTML Container

By default, the chat window appears as a fixed position element on the bottom-right corner of the page. To have more control over how the chat window appears, you'll activate the embedded mode and place the widget in a DOM element that serves as the container.

By default, the embedded widget occupies the full width and height of the container. You'll need to specify the container's height and width so that the widget doesn't collapse.

You'll also learn how to display the contents of a container at the top of the chat window.

Let's start by adding the container for your widget. In your index.html file, insert this HTML just before <footer class="footer">:

        <div id="chat-container" class="chatbox" 
            style="height: 600px; width: 400px; padding: 0;
            text-align: initial">
        </div>

To add containers for your custom header and the text that you want to display at the top of the chat, insert this HTML just below the <body> tag:

    <div id="custom-header" style="padding: 0; text-align: initial">
        <h1>Pizzabot</h1>
    </div>
    <div id="top-text" style="padding: 0; text-align: initial">
        <p>Talk to Pizzabot to order your pizza.</p>
    </div>

Save your changes.
Open scripts/settings.js if it isn't already open.

Insert this code just above the URI property to activate the embedded mode and to tell the widget which containers to put the embedded widget, the custom header, and the top text in.

            embedded: true,
            targetElement: 'chat-container',    
            embedTopStickyId: 'top-text',
            customHeaderElementId: 'custom-header',

Save your file, and then Shift+Reload index.html in your browser.
As shown here, the chat window now appears within the beige box. The window has a title and has text at the top of the chat.
Complete a pizza order. Notice how Talk to Pizzabot to order your pizza doesn't scroll up. You'll change this in the next step.
Your customers don't need to keep seeing the Talk to Pizzabot... message, so rename the embedTopStickyId property to embedTopScrollId as shown here.
```
    embedTopScrollId: 'top-text',
```
Save your file, and then Shift+Reload index.html in your browser.
Now, when you converse with the skill, the text scrolls up.

See embedded-widget.html for the completed HTML for this section.

Customize the Look and Feel of the Chat Window

Typically, you'll want to add your own branding to the chat window, and change the fonts and colors to match your web site. We'll show you some of the ways that you can do that.

We'll start by changing the icons. Insert these properties just above the URI property:

            botButtonIcon: 'images/bot-button.png', 
            logoIcon: 'images/bot-white.png', 
            botIcon: 'images/bot-green.png',        
            personIcon: 'images/user-icon.png',

To change the text for the widget's chat title, connected text, input placeholder, and send icon, insert these properties just above the URI property.
```
            i18n: {
                en: {
                    chatTitle: 'Order from',       // Replaces Chat
                    connected: 'Ready',            // Replaces Connected
                    inputPlaceholder: 'Type here', // Replaces Type a message
                    send: 'Send (Enter)'           // Replaces Send tool tip
                }
            },
```
The text properties must be wrapped in sub-objects within an i18n object, and there must be a sub-object for the locale that's specified by the locale property, which is en by default.

The chat widget first looks for text for the locale that's specified by the locale property (the default is en). If there isn't any, it then looks for text for the browser's locale. If that text doesn't exist, it then uses the en text. You can add sub-objects for additional languages, such as es, fr, and zh-cn in the sub-object for the browser's default locale.
To change the font size and type for the messages, insert this property just above the URI property.
```
            font: '14px Verdana, Geneva, sans-serif',
```
Save your changes.
To see your changes, Shift+Reload index.html in your browser.
Your chat window should look like this.
(Optional) By default, the chat widget users a dark blue theme. To change it to a light blue theme, insert this property just above the URI property.
```
            theme: 'classic',
```
Save your changes and reload index.html to see the new theme. Then try the redwood-dark theme.

Remove the theme property when done.

Add Autocompletion, Profile Values, and Audio Response

In this section, your'll learn about these advanced features:

Autocompletion: In your skill, you can enter some suggested utterances for each intent. Then, you can configure the widget to display autocompletion suggestions when the user starts typing one of those utterances.
Profile information settings: You can configure the widget to pass profile values to the skill.
Audio response: You can configure the widget to read the skill's responses aloud.

Note that for audio response, you'll need to use a Chrome, Edge, Firefox, or Safari browser.

To get started, you'll need to make some changes to your skill to test the passing of profile values. In your Digital Assistant instance, open your clone of the Web SDK Order Pizza skill.
Click Flows and scroll down to the welcome state (the state appears after # TUTORIAL START).

Replace the text property with the following:

      text: "Hello ${profile.firstName}. You last ordered ${profile.properties.value.lastOrderedItems}. Say 'order pizza' to start an order."

These profile values will be set by the initUserProfile property that you'll soon add to the index.html file.

Click Intents , select the Order Pizza intent, and then scroll down to the Auto-Complete Suggestions section.
Click Advanced input mode that's next to the Suggestions to Add field.
A multi-line text box appears.
Copy these suggestions, paste them into the text box, and then click + Create:
```
can I get a pizza
I want pizza
order pizza
what kinds of pizza do you have
```
The Auto-Complete Suggestions section should look like this:
Click Train to add the autocompletion suggestions to the natural language parser.
If you forget to retrain the skill, you won't see the suggestions when you next test the chat widget.

In your scripts/settings.js file, insert these properties just above the URI property to set the profile values and to turn on autocompletion and audio response:

            initUserProfile: {
                profile: {
                    firstName: 'First',
                    lastName: 'Last',
                    email: 'first.last@example.com',
                    properties: {
                        lastOrderedItems: '1 medium pepperoni'
                    }
                }
            },
            enableAutocomplete: true,
            enableAutocompleteClientCache: true, // Minimizes server calls when user uses autocomplete feature
            enableBotAudioResponse: true,

Note that while you can use either the initUserProfile property or the Bots.updateUser function to set profile values, you must use the initUserProfile property whenever you use initUserHiddenMessage. Otherwise, the profile values aren't set until after the welcome message displays.

In the en sub-object in the i18n property, insert these properties just above the chatTitle property:


                    audioResponseOff: 'Click to turn audio response on', // Tool tip for the speaker off button
                    audioResponseOn: 'Click to turn audio response off',  // Tool tip for the speaker on button

To populate the message box with the most typically used utterance, modify the bots.connect() call from:

        Bots.connect();

to:

        Bots.connect().then(() => {
            Bots.setUserInputMessage("Order pizza");
        })

Your code should look similar to this:

'use strict';

    // Set client auth mode - true to enable client auth, false to disable it
    const isClientAuthEnabled = false;
    
    /**
     * Initializes the SDK and sets a global field with passed name for which
     * it can be referred to later.
     *
     * @param {string} name Name by which the chat widget should be referred
     */
    const initSdk = (name) => {
        if (!name) {
            name = 'Bots';          // Set default reference name to 'Bots'
        }
        let Bots;
    
        setTimeout(() => {
            /**
                * SDK configuration settings
                * Other than URI, all fields are optional with two exceptions for auth modes
                * In client auth disabled mode, 'channelId' must be passed, 'userId' is optional
                * In client auth enabled mode, 'clientAuthEnabled: true' must be passed
                */
            let chatWidgetSettings = {
                showConnectionStatus: true,
                conversationBeginPosition: 'bottom',
                openChatOnLoad: true,
                position: {bottom: '2px', right: '2px'},
                displayActionsAsPills: true,
                initUserHiddenMessage: 'Hello',
                embedded: true,
                targetElement: 'chat-container',    
                embedTopScrollId: 'top-text',
                customHeaderElementId: 'custom-header',
                botButtonIcon: 'images/bot-button.png', 
                logoIcon: 'images/bot-white.png', 
                botIcon: 'images/bot-green.png',        
                personIcon: 'images/user-icon.png', 
                i18n: {
                    en: {
                        audioResponseOff: 'Click to turn audio response on', // Tool tip for the speaker off button
                        audioResponseOn: 'Click to turn audio response off',  // Tool tip for the speaker on button   
                        chatTitle: 'Order from',       // Replaces Ask
                        connected: 'Ready',            // Replaces Connected
                        inputPlaceholder: 'Type here', // Replaces Type a message
                        send: 'Send (Enter)'           // Replaces Send tool tip
                    }
                },
                font: '14px Verdana, Geneva, sans-serif',
                initUserProfile: {
                    profile: {
                        firstName: 'First',
                        lastName: 'Last',
                        email: 'first.last@example.com',
                        properties: {
                            lastOrderedItems: '1 medium pepperoni'
                        }
                    }
                },
                enableAutocomplete: true,
                enableAutocompleteClientCache: true, // Minimizes server calls when user uses autocomplete feature
                enableBotAudioResponse: true,
                URI: 'xxxx.xxx.digitalassistant.xxx.xxx.com',
                clientAuthEnabled: isClientAuthEnabled,
                channelId: '12a45b92-2c85-88aa-810d-1dc0d1cfe472'
            };
    
            // Initialize SDK
            if (isClientAuthEnabled) {
                Bots = new WebSDK(chatWidgetSettings, generateToken);
            } else {
                Bots = new WebSDK(chatWidgetSettings);
            }
    
            // Connect to the ODA
            Bots.connect().then(() => {
                Bots.setUserInputMessage("Order pizza");
            })
    
            // Create global object to refer Bots
            window[name] = Bots;
        }, 0);
    };

Save your changes.
To see your changes, Shift+Reload index.html in your browser.
Notice that the welcome message now displays some of the values that you set in the initUserProfile property. Also notice that it seeds the message box with Order pizza.
Click the speaker icon to turn audio response on.
Clear the message box, and then type I want and see the autocomplete suggestions that pop up.
Complete an order. The chat bot speaks its responses.
Note: When the widget is expanded by default and initUserHiddenMessage is set, some browsers don't utter the first response.

You've completed the Oracle Web SDK tutorial, which gives you an idea of the things that you can do with the SDK. We encourage you to review the resources that are listed in the next section to learn about additional SDK features.

Want to Learn More?

See the user-guide.html file in the folder in which you unzipped the Oracle Web SDK ZIP file.

Also, see Oracle Web.

Next Tutorial

Secure Your Web App Chat with Client Authentication

Access a Skill from Your Website