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 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 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//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//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.
-
Download the Client SDK for JavaScript module from the Oracle Technology Network’s ODA and OMC download page.
-
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 athttp://localhost:8000/static/, copy all the files to thestaticfolder on your local server. -
If your storage is behind a CDN (Content Delivery Network), issue a cache invalidation for
https://placeholder.public.path/loader.json. -
Make sure your server allows CORS requests.
-
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
- Include the Client SDK for JavaScript in your web page by adding the following code towards the end of the
headsection 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> - Initialize the Client SDK for JavaScript with your new App ID by adding the following snippet near the end of the
bodysection 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',
// ...
}
});Note:
Thelocale 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 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:
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:
-
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> -
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.
-
Display the conversation by adding the following tag in the
<body>:<ul id="conversation"></ul> -
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); } -
To display the initial conversation state after the initialization of the SDK, replace the
Bots.initcall 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:
-
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" -
In the
<script>tag, add an element that calls theBots.sendMessagefunction right after theBots.initcall. 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 aniconURL 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:
For example:
|
button |
No |
buttonIconUrl |
The URL that points to the button icon. The icon image must be:
|
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:
For example:
|
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:
|
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 |
|
|
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.