42 Legacy JavaScript SDK

Note:

This describes the legacy JavaScript SDK, which only works with versions of Digital Assistant up through 19.4.1. If you are on a later version of Digital Assistant, use the Oracle Native Web SDK.

The Digital Assistant Client SDK for JavaScript enables you to embed a skill into any web page. It includes a client library that enables the client to communicate with the chat server that stands in between Digital Assistant and the client and manages the channel-specific communications and payloads between the two.

Description of client_sdks-web.png follows
Description of the illustration client_sdks-web.png

The SDK also provides a customizable messaging widget that you can add to any web page where you want to surface your skill.

Typically, you deploy the SDK’s library files to a web server, which also hosts the web page. The basic steps for adding your bot to a web page are:

Tip:

This video describes the chat server-client relationship in further detail and steps you through configuring the files, setting up a server, and embedding the widget.

Configure the Library

The Digital Assistant SDK library is composed of multiple assets that get fetched at runtime for better performance. For that reason, the public path (the URL where the static files are hosted) is hardcoded in multiple places.

To configure the library for your environment, run:
./configure 
The script generates a folder with the configured project in it.

Setup Examples

Local Testing Setup

If the static files are hosted at http://localhost:8000/static/ and you run the following script from the /home/your-name/ folder:
./configure http://localhost:8000/static/
then the files will be available at /home/your-name/http:__localhost:8000_static_/.

Production Setup

If the static files are hosted at https://cdn.acme.org/ and you run the following script from the /home/your-name/ folder:
./configure https://cdn.acme.org/
then the files will be available at /home/your-name/https:__cdn.acme.org_/.

Deploy the SDK Files

After you’ve configured the library, you need to deploy the SDK to a web server.
  1. Download the Client SDK for JavaScript module from the Oracle Technology Network’s ODA and OMC download page.

  2. Put all of the files from the generated folder at the root of the storage within https://placeholder.public.path/. For example, if your files are hosted at http://localhost:8000/static/, copy all the files to the static folder on your local server.

  3. If your storage is behind a CDN (Content Delivery Network), issue a cache invalidation for https://placeholder.public.path/loader.json.

  4. Make sure your server allows CORS requests.

  5. Test your deployment by initializing the SDK as described in Add the Client SDK to Your Site.

Add the Client SDK to Your Site

You can include the Client SDK for JavaScript by editing the <script> tag. You need an App Id to do this, so if don’t have one already for the Web channel, start off by clicking Add Channel. In the Create Channel dialog, add a name for the channel and then choose Web as the channel type. When you click Create, IDigital Assistant generates the App Id. You then substitute this value for <app-id> in the code.

Update the Script Tag

  1. Include the Client SDK for JavaScript in your web page by adding the following code towards the end of the head section on your page and replacing <sdk-folder-url> with the URL where the SDK is hosted.
    <script> 
      !function(e,t,n,r){ 
        function s(){
         try{
           var e;
            if((e="string"==typeof this.response?JSON.parse(this.response):this.response).url){
            var n=t.getElementsByTagName("script")[0],r=t.createElement("script");
            r.async=!0,r.src=e.url,n.parentNode.insertBefore(r,n)
          }
         }
         catch(e){}}var o,p,a,i=[],c=[];e[n]={init:function(){o=arguments;
          var e={then:function(t){
            return c.push({type:"t",next:t}),e
            } ,catch:function(t){return c.push({type:"c",next:t}),e}};
            return e},on:function(){
             i.push(arguments)},render:function(){p=arguments},destroy:function(){a=arguments}
            } ,e.__onWebMessengerHostReady__=function(t){
             if(delete e.__onWebMessengerHostReady__,e[n]=t,o)for(var r=t.init.apply(t,o),s=0;s<c.length;s++){
              var u=c[s];
               r="t"===u.type?r.then(u.next):r.catch(u.next)
               } p&&t.render.apply(t,p),a&&t.destroy.apply(t,a);
             for(s=0;s<i.length;s++)t.on.apply(t,i[s])};
             var u=new XMLHttpRequest;u.addEventListener("load",s),u.open("GET",r+"/loader.json",!0),u.responseType="json",u.send() 
            }
         (window,document,"Bots", "<sdk-folder-url>"); 
    </script>
  2. Initialize the Client SDK for JavaScript with your new App ID by adding the following snippet near the end of the body section of your page and replacing <app-id> with your App Id for the Web channel found in your app settings page.
    <script>
        Bots.init({appId:'<app-id>'});
    </script>

Embedded Mode

To embed the widget in your existing markup, you need to pass embedded: true when calling Bots.init. By doing so, you are disabling the auto-rendering mechanism and you will need to call Bots.render manually. This method accepts a DOM element which will be used as the container where the widget will be rendered.
Bots.init({
    appId: '<app-id>',
    embedded: true
});


Bots.render(document.getElementById('chat-container'));

Note:

The embedded widget will take full width and height of the container. You must give it a height, otherwise, the widget will collapse.

Strings Customization

Digital Assistant lets you customize any strings it displays by overwriting its keys. To do this, add the customText key in your Bots.init() call and specify new values for the keys shown in the following sample. If any text is within {}, or if there is an HTML tag such as <a>, it needs to remain in the customized text.

For example:
Bots.init({
    appId: '<app-id>',
    customText: {
        actionPostbackError: 'An error occurred while processing your action. Please try again.',
        clickToRetry: 'Message not delivered. Click to retry.',
        conversationTimestampHeaderFormat: 'MMMM D YYYY, h:mm A',
        fetchHistory: 'Load more',
        fetchingHistory: 'Retrieving history...',
        headerText: 'How can we help?',
        inputPlaceholder: 'Type a message...',
        invalidFileError: 'Only images are supported. Choose a file with a supported extension (jpg, jpeg, png, gif, or bmp).',
        introductionText: 'We\'re here to talk, so ask us anything!',
        locationNotSupported: 'Your browser does not support location services or it’s been disabled. Please type your location instead.',
        locationSecurityRestriction: 'This website cannot access your location. Please type your location instead.',
        locationSendingFailed: 'Could not send location',
        locationServicesDenied: 'This website cannot access your location. Allow access in your settings or type your location instead.',
        messageError: 'An error occurred while sending your message. Please try again.',
        messageIndicatorTitlePlural: '({count}) New messages',
        messageIndicatorTitleSingular: '({count}) New message',
        messageRelativeTimeDay: '{value}d ago',
        messageRelativeTimeHour: '{value}h ago',
        messageRelativeTimeJustNow: 'just now',
        messageRelativeTimeMinute: '{value}m ago',
        messageTimestampFormat: 'hh:mm A',
        messageSending: 'Sending...',
        messageDelivered: 'Delivered',
        sendButtonText: 'Send',
        settingsHeaderText: 'Settings',
        tapToRetry: 'Message not delivered. Tap to retry.',
        unsupportedMessageType: 'Unsupported message type.',
        unsupportedActionType: 'Unsupported action type.'
    }
});

Date Localization

When you translate the user interface by customizing strings, you might also want to show the date and time in the target language as well. To do this, pass locale at initialization time. You might also want to override the timestamp format to match your language.
Bots.init({
    appId: '<app-id>',
    locale: 'fr-CA',
    customText: {
        // ...
        conversationTimestampHeaderFormat: 'Do MMMM YYYY, hh:mm',
        // ...
    }
});
The locale options is using the language-COUNTRY format. You can find language codes here and country codes here. The country part is optional, and if a country is either not recognized or not supported, it falls back to using the generic language. If the language isn't supported, it will fallback to en-US.

Note:

The locale option only affects date and time localization, not the strings.

Sound Notification

By default, a sound notification will be played when a new message comes in and the window is not in focus.

To disable this feature, you need add the soundNotificationEnabled option to the Bots.init call, like this:
Bots.init({
    appId: '<app-id>',
    soundNotificationEnabled: false // Add this line to your 'Bots.init' call
});

Browser Storage

By default, the SDK stores the identity of anonymous users in the browser's localStorage object. Both a user's identity and the conversation in the chat window persist even when the user closes and then reopens the browser, when the page reloads, or when the browser restarts.

To clear the user's identity and the conversation from the browser storage, initialize the SDK with browserStorage: 'sessionStorage' option (illustrated in the following snippet). By adding this to the Bots.init call, you limit the storage of the user's identity and conversation to just the duration of the session: they're gone when users close the browser tab or the browser itself.
Bots.init({
    appId: '<app-id>',
    browserStorage: 'sessionStorage' // Add this line to your 'Bots.init' call
})
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Menu Items

By default, the Web client SDK displays the Menu Items option (located in the lower left of the widget) that allows users to send non-text messages, such as shared locations or uploaded images and files.
Description of menu.png follows
Description of the illustration menu.png

You can either hide or show the individual message options within the menu, or hide the menu itself by initializing the SDK with the menuItems option. The following snippet shows how a boolean controls the display of these options.
Bots.init({
    appId: '<app-id>',
    menuItems: {
        imageUpload: false,   //set to true to enable the image upload menu item 
        fileUpload: false,    //set to true to enable the file upload menu item
        shareLocation: false  //set to true to enable the share location menu item
    },
})
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );


Custom User Interfaces

While the SDK’s widget provides a rich, prebuilt UI, you can create your own using the SDK’s APIs for sending messages and the callback event interface for receiving messages.

To get started, use the following custom UI starter code for a UI that outputs simple text messages. By updating its <body> and <script> elements, you can create a chat widget that can do the following: You can reference this code snippet, which incorporates these functions. At runtime, it looks something like this.

Custom UI Starter Code

You need to update SDK_FOLDER_URL with the URL where the SDK is hosted.

<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <title>Document</title>
 </head>
 <body>
   <script>
     !function(e,t,n,r){
         function s(){try{var e;if((e="string"==typeof this.response?JSON.parse(this.response):this.response).url){var n=t.getElementsByTagName("script")[0],r=t.createElement("script");r.async=!0,r.src=e.url,n.parentNode.insertBefore(r,n)}}catch(e){}}var o,p,a,i=[],c=[];e[n]={init:function(){o=arguments;var e={then:function(t){return c.push({type:"t",next:t}),e},catch:function(t){return c.push({type:"c",next:t}),e}};return e},on:function(){i.push(arguments)},render:function(){p=arguments},destroy:function(){a=arguments}},e.__onWebMessengerHostReady__=function(t){if(delete e.__onWebMessengerHostReady__,e[n]=t,o)for(var r=t.init.apply(t,o),s=0;s<c.length;s++){var u=c[s];r="t"===u.type?r.then(u.next):r.catch(u.next)}p&&t.render.apply(t,p),a&&t.destroy.apply(t,a);for(s=0;s<i.length;s++)t.on.apply(t,i[s])};var u=new XMLHttpRequest;u.addEventListener("load",s),u.open("GET",r+"/loader.json",!0),u.responseType="json",u.send()
     }
(window,document,"Bots", "<SDK_FOLDER_URL>");
 </script>
 </body>
 </html>

Initialize the Client SDK for JavaScript in Embedded Mode

To initialize the SDK but prevent the default UI from displaying:
  1. Create a container that prevents the widget from displaying. In the <body> element, define the <div> tag that hides the default widget.
    <div id="no-display" style="display:none;"></div>
  2. In the <script> element, initialize the Client SDK for JavaScript in embedded mode and render the “no-display” element:
    Bots.init({ appId: appId, embedded: true });
    Bots.render(document.getElementById('no-display'));

Fetch the Initial Data

To determine the initial state of the UI, use the SDK’s Bots.getConversation method. This method provides access to things like the unread message count and the conversation history.
  1. Display the conversation by adding the following tag in the <body>:
    <ul id="conversation"></ul>
  2. Within the <script> tag, define a function that when called, displays a message in the custom UI.
    function displayMessage(message) {
      var conversationElement = document.getElementById('conversation');
      var messageElement = document.createElement('li');
      messageElement.innerText = message.name + ' says "' + message.text + '"';
      conversationElement.appendChild(messageElement);
    }
    
  3. To display the initial conversation state after the initialization of the SDK, replace the Bots.init call with the following:
    Bots.init({ appId: appId, embedded: true }).then(function() {
      // displays initial messages
      var conversation = Bots.getConversation();
      conversation.messages.forEach(displayMessage);
    });

Send Messages

To enable the widget to send messages:
  1. Create a text input element in the <body> that allows the widget to accept plain text messages:
    <input type="text" id="text-input" placeholder="text"
  2. In the <script> tag, add an element that calls the Bots.sendMessage function right after the Bots.init call. When the text input element is active, this function, which enables users to send plain text or structured messages, gets called whenever a user taps Enter.

    Here's an example of the element for sending plain text messages:
    var inputElement = document.getElementById('text-input');
     
    inputElement.onkeyup = function(e) {
      if (e.key === 'Enter') {
        Bots.sendMessage(inputElement.value)
          .then(function() {
            inputElement.value = '';
          });
      }
    }

Send Structured Messages

You can also pass structured messages through Bots.sendMessage. If you do that, you first need to construct an object in the message format, which is:

{
  type:'text',
  text:'Hello, world!',
  metadata:{}// optional object
}

For example:

var messageBody = {
  text: inputElement.value,
  type: 'text',
  metadata: {
    currentCustomer: true,
    additionalInfo: 'thin crust'
  }
};

And then you send the object (in this case messageBody as the parameter sendMessage().

Receive Messages

To update the UI with the new message content, use the SDK’s Bots.on event interface to bind the message:received event (inbound messages) and the message:sent event (outbound messages) to the displayMessage function. To call this function whenever these message events occur, add the following somewhere after the Bots.init call.
Bots.on('message:sent', displayMessage);
Bots.on('message:received', displayMessage);

Add Postback Actions

You can add actions to the bot’s reply message by updating the displayMessage function.
function displayMessage(message) {
    var conversationElement = document.getElementById('conversation');
    var messageElement = document.createElement('li');
    messageElement.innerText = message.name + ' says "' + message.text + '"';
 
    if(message.actions && message.actions.length > 0){
        var wrapperElement = document.createElement('div');
        for(var i = 0; i < message.actions.length; i++){
            var action = message.actions[i];
            var btnElement = createButtonElement(action);
            wrapperElement.appendChild(btnElement);
        }
        messageElement.appendChild(wrapperElement);
    }
    conversationElement.appendChild(messageElement);
}
 
function createButtonElement(action) {
    var btnElement = document.createElement('button');
    var btnTitle = document.createTextNode(action.text);
    btnElement.appendChild(btnTitle);
    btnElement.onclick = function(e){Bots.triggerPostback(action._id);};
    return btnElement;
}

Calling Other Functions

You can call other functions after the SDK has been initialized successfully. For example, you can update a user profile by calling updateUser.
<script>
    Bots.init({ appId: '5b1014820c9940062e39108' })
        .then(function (res){
            Bots.updateUser(
                {
                    "givenName”:"John", 
                    "surname”:"Smith", 
                    "email": “john@example.com", 
                    "properties": { 
                        “botsCustomVariable1”:"beer", 
                        “botsCustomVariable2”:”code”,
                        “botsCustomVariable3”:”repeat"
                    }
                }
            );
        })
        .catch(function (err) {
            console.error(err);
        });
  </script>

Sample Code for the Custom UI

<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <title>Document</title>
 </head>
 <body>
   <div id="no-display" style="display:none;"></div>
   <p>User ID: <span id="user-id"></span></p>
   <ul id="conversation"></ul>
   <input type="text" id="text-input" placeholder="text">

  <script>
        var appId = '<APP_ID>';
     !function(e,t,n,r){
          function s(){try{var e;if((e="string"==typeof this.response?JSON.parse(this.response):this.response).url){var n=t.getElementsByTagName("script")[0],r=t.createElement("script");r.async=!0,r.src=e.url,n.parentNode.insertBefore(r,n)}}catch(e){}}var o,p,a,i=[],c=[];e[n]={init:function(){o=arguments;var e={then:function(t){return c.push({type:"t",next:t}),e},catch:function(t){return c.push({type:"c",next:t}),e}};return e},on:function(){i.push(arguments)},render:function(){p=arguments},destroy:function(){a=arguments}},e.__onWebMessengerHostReady__=function(t){if(delete e.__onWebMessengerHostReady__,e[n]=t,o)for(var r=t.init.apply(t,o),s=0;s<c.length;s++){var u=c[s];r="t"===u.type?r.then(u.next):r.catch(u.next)}p&&t.render.apply(t,p),a&&t.destroy.apply(t,a);for(s=0;s<i.length;s++)t.on.apply(t,i[s])};var u=new XMLHttpRequest;u.addEventListener("load",s),u.open("GET",r+"/loader.json",!0),u.responseType="json",u.send()
     }
(window,document,"Bots", "<SDK_FOLDER_URL>");

  inputElement.onkeyup = function(e) {
  if (e.key === 'Enter') {
  Bots.sendMessage(inputElement.value)
  .then(function() {
  inputElement.value = '';
  });
  }
  }
  // display new messages
  Bots.on('message:sent', displayMessage);
  Bots.on('message:received', displayMessage);

  // initialize Bots and render the UI in a hidden element
  Bots.init({ appId: appId, embedded: true })
  .then(function () {

  // displays initial messages
  var conversation = Bots.getConversation();
  conversation.messages.forEach(displayMessage);

  Bots.render(document.getElementById('no-display'));

  function displayMessage(message) {
  var conversationElement = document.getElementById('conversation');
  var messageElement = document.createElement('li');
  messageElement.innerText = message.name + ' says "' + message.text + '"';
  conversationElement.appendChild(messageElement);
  }
    </script>
 </body>
 </html>

Message Types

Text Message

A text type message is sent with text and/or actions.

{
    /**
     * The text content of the message. Optional only if actions are provided.
     */
    text?: string,
    /**
     * Message type
     */
    type: 'text',
    /**
     * Message role can be 'appUser' or 'appMaker'
     * Added by SDK when send through the sendMessage method
     */
    role?: 'appMaker',
    /**
     * Array of action buttons.
     */
    actions?: MessageAction[],
    /**
     * Url to the avatar for this message sender
     */
    avatarUrl?: string
}
Carousel Message

Carousel messages are a horizontally scrollable set of items, each of which can contain combinations of text, images, and action buttons.

{
    /**
     * Message type
     */
    type: 'carousel',
    /**
     * Message role can be 'appUser' or 'appMaker'
     * Added by SDK when send through the sendMessage method
     */
    role?: 'appMaker',
    /**
     * Url to the avatar for this message sender
     */
    avatarUrl?: string,
    /**
    * Array of message items. The array is limited to 10 items.
    */
    items: Item[],
    /**
    * Settings to adjust the carousel layout.
    */
    displaySettings?: {
        imageAspectRatio: 'horizontal' | 'square'
    }
}
Image Message
An image type message is a message that is sent with an image, and, optionally, text and/or actions.
{
    /**
     * Message type
     */
    type: 'image',
    /**
     * Message role can be 'appUser' or 'appMaker'
     * Added by SDK when send through the sendMessage method
     */
    role?: 'appMaker',
    /**
     * Url to the avatar for this message sender
     */
    avatarUrl?: string,
    /**
    * The text content of the message. Optional only if actions are provided.
    */
    text?: string,
    /**
    * The media type is defined here, for example image/jpeg. If mediaType is not specified, the media type will be resolved with the mediaUrl.
    */
    mediaType?: string;
    /**
    * The image URL used for the image message.
    */
    mediaUrl: string;
    /**
    * Array of action buttons.
    */
    actions?: MessageAction[]
}
File Message
A file type message is a message that is sent with a file attachment.
{
    /**
     * Message type
     */
    type: 'file',
    /**
     * Message role can be 'appUser' or 'appMaker'
     * Added by SDK when send through the sendMessage method
     */
    role?: 'appMaker',
    /**
     * Url to the avatar for this message sender
     */
    avatarUrl?: string,
    /**
    * The text content of the message. Optional only if actions are provided.
    */
    text?: string,
    /**
    * The media type is defined here, for example application/pdf. If mediaType is not specified, the media type will be resolved with the mediaUrl.
    */
    mediaType?: string;
    /**
    * The URL of the file attachment.
    */
    mediaUrl: string;
}
Location Message
A location type message includes the location coordinates (latitude and longitude). Typically, these messages are sent in response to a location request.
{
    /**
     * Message type
     */
    type: 'location',
    /**
     * Message role can be 'appUser' or 'appMaker'
     * Added by SDK when send through the sendMessage method
     */
    role?: 'appMaker',
    /**
     * Url to the avatar for this message sender
     */
    avatarUrl?: string,
    /**
    * The coordinates of the location.
    */
    coordinates?: {
        /**
        * A floating point value representing the latitude of the location
        */
        lat: number,
        /**
        * A floating point value representing the longitude of the location
        */
        long: number
    }
}

Message Actions

Postback Action
A postback action posts the action payload when tapped.
{
    _id: string,
    /**
     * The button text.
     */
    text: string,
    /**
     * Type of the action
     */
    type: 'postback',
    /**
     * Value indicating whether the action is the default action for a message item.
     */
    default: boolean,
    /**
     * Flat object containing any custom properties associated with the action.
     */
    metadata?: any,
    /**
    * A string payload to help you identify the action context. You can also use metadata for more complex needs.
    */
    payload: string
} 
Link Action
A link action opens the provided URI when tapped.
{
    /**
     * The button text.
     */
    text: string,
    /**
     * Type of the action
     */
    type: 'link',
    /**
     * Value indicating whether the action is the default action for a message item.
     */
    default: boolean,
    /**
     * Flat object containing any custom properties associated with the action.
     */
    metadata?: any,
    /**
    * The action URI. This is the link that will be used in the clients when clicking the button.
    */
    uri: string
    /**
    * Extra options to pass directly to the channel API.
    */
    extraChannelOptions?: any
} 
Location Request Action
A location request action prompts users to share their location.
{
    /**
     * The button text.
     */
    text: string,
    /**
     * Type of the action
     */
    type: 'locationRequest',
    /**
     * Value indicating whether the action is the default action for a message item.
     */
    default: boolean,
    /**
     * Flat object containing any custom properties associated with the action.
     */
    metadata?: any,
} 
Reply Action
A reply action echoes the user’s choice as a message.

Tip:

You can also specify an iconURL which renders as an icon for each option.
{
    /**
     * The button text.
     */
    text: string,
    /**
     * Type of the action
     */
    type: 'reply',
    /**
     * Value indicating whether the action is the default action for a message item.
     */
    default: boolean,
    /**
     * Flat object containing any custom properties associated with the action.
     */
    metadata?: any,
    /**
    * A string payload to help you identify the action context. Used when posting the reply. You can also use metadata for more complex needs.
    */
    payload: string,
    /**
    * An icon to render next to the reply option
    */
    iconUrl?: string
} 
Webview Action
When a user taps or clicks a webview action, the URL is loaded in the webview.
{
    /**
     * The button text.
     */
    text: string,
    /**
     * Type of the action
     */
    type: 'webview',
    /**
     * Value indicating whether the action is the default action for a message item.
     */
    default: boolean,
    /**
     * Flat object containing any custom properties associated with the action.
     */
    metadata?: any,
    /**
    * The webview URI. This is the URI that will open in the webview when clicking the button.
    */
    uri: string,
    /**
    * The webview fallback URI. This is the link that will be opened when not support webviews.
    */
    fallback: string,
    /**
    * Controls the webview height.
    */
    size?: 'compact' | 'tall' | 'full',
    /**
    * Extra options to pass directly to the channel API.
    */
    extraChannelOptions?: any
} 
Share Action
A share button.
{
    /**
     * The button text.
     */
    text: string,
    /**
     * Type of the action
     */
    type: 'share',
    /**
     * Value indicating whether the action is the default action for a message item.
     */
    default: boolean,
    /**
     * Flat object containing any custom properties associated with the action.
     */
    metadata?: any
} 

Message Item

{
    /**
     * The image URL to be shown in the carousel/list item.
     */
    mediaUrl?: string,
    /**
     * The text description, or subtitle.
     */
    description?: string,
    /**
     * The title of the carousel item.
     */
    title: string,
    /**
     * If a mediaUrl was specified, the media type is defined here, for example image/jpeg. If mediaType is not specified, the media type will be resolved with the mediaUrl.
     */
    mediaType: string,
    /**
     * Array of action buttons. At least 1 is required, a maximum of 3 are allowed. link and postback and share actions are supported.
     */
    actions: IBotsSDKMessageAction[],
    /**
     * The size of the image to be shown in the carousel/list item
     */
    size: 'compact' | 'large'
}

Display Style Options

You can style the UI by adding these options after Bots.init.
Option Description Default Value Required
displayStyle

How the messenger widget appears on your website. This is defined as either a button or tab. You can style the button’s size and icon:

  • buttonIconUrl

  • buttonWidth

  • buttonHeight

For example:
Bots.init({ appId: appId, embedded: true });
    // ...

displayStyle: "button",
buttonIconUrl: https://myimage.png,
buttonWidth: '90',
buttonHeight: '90'
...
}).then(function() {
    // Your code after init is complete
});
button No
buttonIconUrl

The URL that points to the button icon. The icon image must be:

  • At least 200 x 200 pixels

  • JPG, PNG, or GIF format

  No
buttonWidth The button width, in pixels. 8px No
buttonHeight The button height, in pixels. 58px No
businessName The business name. For example: businessName: “Oracle”   No
businessIconUrl

The URL that points to the business’ icon image. This image must be:

  • At least 200 x 200 pixels

  • JPG, PNG, or GIF format

For example:
Bots.init({ appId: appId, embedded: true });
    //...
    businessName: "Acme Corporation",
    businessIconUrl: "https://example.com/image/thumb/thatimage.jpg/1200x630bb.jpg"
    //...
}).then(function() {
    // Your code after init is complete
});
  No
backgroundImageUrl

The URL that points to the image that appears in the background of the conversation. This image is tiled to fit the chat window.

For example:
Bots.init({ appId: appId, embedded: true });
    // ...
    backgroundImageUrl: "https://a-nice-texture.png"
    // ...
}).then(function() {
    // Your code after init is complete
});

  No
integrationOrder

An array of integration IDs. When set, only integrations from this list will be displayed. If the array is empty, then , no integrations will be displayed.

Note: Listing an integration in the array doesn't guarantee that it will be displayed in the widget.

  No
customColors

The colors used in the Web Messenger UI.

The three-to-six character hexadecimal colors used for the brandColor, conversationColor, and actionColor options. No
brandColor The color used in the messenger header and for the button or tab in idle state 65758e No
conversationColor This color used for customer messages, quick replies and actions in the footer. 0099ff No
actionColor

The color used to change the appears of selected actions inside your messages, like tapped buttons or links.

This color is also used for the Send button when it is in active state.

0099ff No

Supported Capabilities

Web channels (based on the JavaScript SDK) in Digital Assistant support the following capabilities:

  • text (both sending and receiving)
  • images (both sending and receiving)
  • files (both sending and receiving)
  • emojis (both sending and receiving)
  • location (no support for sending, full support for receiving)
  • links
  • postbacks
  • location requests
  • custom properties
  • carousel components
  • list components

Message Constraints

Web channels (based on the JavaScript SDK) in Digital Assistant have the following message constraints:

  • Text Messages
    • Maximum length of text action label: 128 characters
    • Types of text actions allowed: Postback, URL
    • Maximum number of text actions: 6. If there are more text actions, the message is converted to multiple horizontal cards, with the same text used as the title on each card, and each card containing up to 6 actions.
  • Horizontal Cards
    • Maximum length of title: 30 characters
    • Maximum length of description: 128 characters
    • Maximum length of card action label: 25 characters
    • Maximum number of cards: 10
    • Maximum number of card actions: 3. If the number of card actions exceeds 3, the card is duplicated to render remaining card actions.
    • Minimum number of card actions: 1
    • At least one description, image or action required?: No
    • Types of card actions allowed: Postback, URL
    • Types of card list actions allowed: Postback, URL
  • Vertical Cards
    • Supported?: No. The card is layout is converted to horizontal.
  • Attachment Messages
    • Supported?: Yes
    • Types of attachment actions allowed: Postback, URL
  • Action Buttons
    • Maximum length of global action label: 128 characters
    • Types of global actions allowed: Postback, Location

Web Channel Extensions

For web channels, you can extend the functionality of System.CommonResponse components with capabilities that are specific to the JavaScript SDK.

You access the extensions by using the channelCustomProperties element in the System.CommonResponse component and setting the appropriate properties. The code has the following format:

...
            channelCustomProperties:
            - channel: "web"
              properties:
                PROPERTY_NAME: "PROPERTY_VALUE"
...

Here are the available custom properties for web channels:

Name Allowed Values Applies To... Description
mediaType
  • A valid media type
  • Response items with the following attributes:
    • type: "attachment"
    • attachmentType: "file"or attachmentType: "image"
  • Cards with imageUrl specified
The media type of the attachment. For example, image/jpeg. If not specified, the media type will be resolved from the attachment URL.

For more general information on channelCustomProperties, see Channel-Specific Extensions.