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.

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 thecss
,images
, andscripts
subfolders. - Copy
native-client-sdk-js/web-sdk.js
from your Oracle Web SDK folder and put it in thescripts
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 Optionsand then click Clone.
- Give the cloned skill a unique Name. For example, prepend
WebSDKOrderPizza
with your initials, such asABWebSDKOrderPizza
.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.
- Name: A unique name for the channel, such as
- 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 namedsettings.js
, and open it in an editor. -
Click 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' };
-
URI: This is the host and domain name that you noted when you created
the Oracle Web channel. For example:
-
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 theURI
property in thechatWidgetSettings
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 theembedTopStickyId
property toembedTopScrollId
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: -
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 thelocale
property, which isen
by default.The chat widget first looks for text for the locale that's specified by the
locale
property (the default isen
). If there isn't any, it then looks for text for the browser's locale. If that text doesn't exist, it then uses theen
text. You can add sub-objects for additional languages, such ases
,fr
, andzh-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 theredwood-dark
theme.Remove the
theme
property when done.
botButtonIcon: 'images/bot-button.png',
logoIcon: 'images/bot-white.png',
botIcon: 'images/bot-green.png',
personIcon: 'images/user-icon.png',
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 theinitUserProfile
property that you'll soon add to theindex.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 theURI
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 theBots.updateUser
function to set profile values, you must use theinitUserProfile
property whenever you useinitUserHiddenMessage
. Otherwise, the profile values aren't set until after the welcome message displays. -
In the
en
sub-object in thei18n
property, insert these properties just above thechatTitle
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 withOrder 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.