Oracle Android

51 Oracle Android

Using the Oracle Android SDK for Oracle Digital Assistant, you can integrate your digital assistant with Android apps. The SDK connects to the Oracle Chat Server, the intermediary between the Oracle Android channel configured in Oracle Digital Assistant and the client. The chat server then passes messages to the skill for processing and delivers the skill's response to the client.

Note:

The Oracle Android Channel doesn't store messages when the client has disconnected from the server. It only delivers messages to connected clients. The SDK does not support multi-device login; it supports only one client per user.

What Do You Need?

An Oracle Android Channel. Creating the channel generates the Channel ID and the Secret Key that you need to initialize the chat view.
The URL of the Oracle Chat Server.
The Android SDK. Download it from the ODA and OMC download page and extract it to your local system. This ZIP includes a user guide that describes the SDK's functions a sample app that demonstrates many of its features, and JavaDoc of all the classes.
API Level 33 (Android 13, Tiramisu). API Level 21 (Lollipop) is the lowest version that can support the Digital Assistant Client SDK for Android. If your app needs to support even earlier versions, keep in mind that we haven't tested these and therefore can't guarantee their compatibility.

Note:
Speech recognition has been tested for API level 23 (Marshmallow) and higher. It may not work on API levels below 23

Create the Oracle Android Channel

You can configure the channel to connect to the Oracle Chat Server in two modes: unauthenticated mode and authenticated mode (to protect access to the channel).

Unauthenticated mode – Use the unauthenticated mode when the client can't generate signed JWT tokens, when no authentication mechanism is in place, or when the client app is already secured and visible to authenticated users.
Authenticated mode – Authentication is enforced using JSON Web Tokens (JWT). The customer's backend server generates the JWT token, which is then passed to the Oracle Andriod SDK. This token is used for each request to an ODA speech, text, or attachment server.

Note:
To protect access to the channel, the token must always be generated by a remote server. It must never be generated within by the client app.
When the app needs to connect to an ODA server, it first requests the token from the backend server and then adds it to the Authorization header. The ODA server validates the token, evaluates the claims, and then either opens the socket or rejects the connection.

The JWT Token has the following claims: channelId and userId, and the claim names iat (issued at time), and exp (expiration time). iat signifies the time at which the token was issued. This must be a number that represents the seconds that have elapsed since the UNIX epoch. exp must be a number representing the seconds that have elapsed since the UNIX epoch. We recommend setting the expiration time to at least 30 minutes after the issued at time (iat). The token header looks something like this:

{

 "alg": "HS256",

 "typ": "JWT"

}

An example token body looks something like this:

{

  "iat": 1569828182,

  "exp": 1569831782,

  "channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

  "userId": "John"

}

Note:

The token illustrated by this example is not signed. The actual tokens are signed by channel's Secret Key.

Configure the Oracle Android Channel

To configure the Oracle Android channel:

Choose Development, then Channels from the menu.
Choose Users.
Click Add Channel and then Oracle Android as the channel type.
Complete the dialog:
- Enter the channel name.
- For authenticated connections:
  - Switch on the Client Authentication Enabled toggle to determine whether the SDK is connecting to a client authentication-enabled channel.
  - In the Max. Token Expiration (Minutes) field, set the maximum amount of time for the JWT token.
- For unauthenticated connections:
  - Switch off Client Authentication Enable toggle.
- Set the Session expiration time.
- Click Create. Oracle Digital Assistant will generate the Channel ID and the Secret Key that you need to initialize the SDK. Keep these close at hand.
Route the channel to your skill or digital assistant.
Switch Channel Enabled to On.

Add the Oracle Android Client SDK to the Project

To add the SDK using the Arctic Fox version of Android Studio or higher:

Download the ODA Client SDK for Android and extract it to your local system.
In Android Studio, select your project's app directory.
Select the libs directory.
Add com.oracle.bots.client.sdk.android.core-22.12.aar and com.oracle.bots.client.sdk.android.ui-22.12.aar to the libs folder.

Add the following to the dependencies to the build.gradle (Module: app) file. These dependencies include:

The SDK library dependency

Core and UI dependencies - Used by the SDK library for the smooth functioning of library features.

// SDK
implementation files('libs/com.oracle.bots.client.sdk.android.ui-22.12.aar')
implementation files('libs/com.oracle.bots.client.sdk.android.core-22.12.aar')

// Core dependencies
implementation 'androidx.room:room-runtime:2.4.2'
implementation 'io.socket:socket.io-client:0.8.3'
implementation 'androidx.core:core:1.8.0'

//UI dependencies
implementation 'androidx.appcompat:appcompat:1.4.2'
implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
implementation 'androidx.webkit:webkit:1.4.0'
implementation 'com.google.android.material:material:1.6.1'
implementation 'com.intuit.sdp:sdp-android:1.0.6'
implementation 'com.squareup.picasso:picasso:2.5.2'
implementation 'com.google.android.gms:play-services-location:20.0.0'

For prior versions for Android Studio:

select your project's app directory and then click File > New > New Module.
Choose Import JAR/.AAR Package and then click Next.
Navigate to, and select, com.oracle.bots.client.sdk.android.core-22.12.aar. Click Finish.
Repeat these steps to import com.oracle.bots.client.sdk.android.ui-22.12.aar.

Note:
You don't need to import this package if you're using the SDK in headless mode.

Ensure that these libraries are listed at the top of project's settings.gradle file. For example:

 include ':app', ':com.oracle.bots.client.sdk.android.core-22.12', ':com.oracle.bots.client.sdk.android.ui-22.12'
    rootProject.name = 'ODASDKSample'

Add the following to the dependencies in the

build.gradle
                        (Module: app)

file. These dependencies include:

The SDK library dependency

Core and UI dependencies which are used by the SDK library for the smooth functioning of library features.

// SDK
implementation project(':com.oracle.bots.client.sdk.android.core-22.12')
implementation project(':com.oracle.bots.client.sdk.android.ui-22.12')

// Core dependencies
implementation 'androidx.room:room-runtime:2.4.2'
implementation 'io.socket:socket.io-client:0.8.3'
implementation 'androidx.core:core:1.7.0'

//UI dependencies
implementation 'androidx.appcompat:appcompat:1.4.1'
implementation 'androidx.constraintlayout:constraintlayout:2.1.3'
implementation 'androidx.webkit:webkit:1.4.0'
implementation 'com.google.android.material:material:1.5.0'
implementation 'com.intuit.sdp:sdp-android:1.0.6'
implementation 'com.squareup.picasso:picasso:2.5.2'
implementation 'com.google.android.gms:play-services-location:19.0.1'

For example:

apply plugin: 'com.android.application'
 
android {
    compileSdkVersion 29
    buildToolsVersion "29.0.0"
    defaultConfig {
        applicationId "com.example.odasdksample"
        minSdkVersion 21
        targetSdkVersion 29
        versionCode 1
        versionName "1.0"
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }
    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}
 
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
 
    androidTestImplementation 'androidx.test:runner:1.2.0'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0'
 
    testImplementation 'junit:junit:4.12'
 // SDK
        implementation project(':com.oracle.bots.client.sdk.android.core-22.12')
        implementation project(':com.oracle.bots.client.sdk.android.ui-22.12')

        // Core dependencies
        implementation 'androidx.room:room-runtime:2.4.2'
        implementation 'io.socket:socket.io-client:0.8.3'
        implementation 'androidx.core:core:1.8.0'

        //UI dependencies
        implementation 'androidx.appcompat:appcompat:1.4.2'
        implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
        implementation 'androidx.webkit:webkit:1.4.0'
        implementation 'com.google.android.material:material:1.6.1'
        implementation 'androidx.preference:preference:1.2.0'
        implementation 'com.intuit.sdp:sdp-android:1.0.6'
        implementation 'com.squareup.picasso:picasso:2.5.2'
        implementation 'com.google.android.gms:play-services-location:19.0.1'
        implementation 'com.google.android.gms:play-services-auth:20.1.0'
}

Initialize the Oracle Android Client SDK in Your App

Initialize Oracle Android Client SDK in your Application class. Initialize the SDK describes the different methods that you can use to initialize the SDK. The JavaDoc that's included with the SDK describes all of the available classes.

If you're connecting to a channel with client authentication disabled, pass false as the second parameter to the BotsConfiguration.BotsConfigurationBuilder() constructor function.

import android.app.Application;
import oracle.cloud.bots.mobile.core.Bots;
import oracle.cloud.bots.mobile.core.BotsCallback;
import oracle.cloud.bots.mobile.core.BotsConfiguration;
import oracle.cloud.bots.mobile.core.BotsSDKException;

public class YourApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        try {
                BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<SERVER_URI>, false, getApplicationContext()) // Configuration to initialize the SDK
                    .channelId(<CHANNEL_ID>)
                    .userId(<USER_ID>)
                    .build();

                Bots.init(this, botsConfiguration, new BotsCallback() {  // Initialize the SDK
                    @Override
                    public void onSuccess(Response paramResponse) {
                        // Handle init success
                    }
                    @Override
                    public void onFailure(Response paramResponse) {
                        // Handle init failure
                    }
                });
        } catch (BotsSDKException e) {
           // Handle Exceptions thrown by SDK
        }
    }
}

If you are connecting to a channel with client authentication enabled, you need to make some minor modifications: along with passing true as the second parameter to the BotsConfiguration.BotsConfigurationBuilder() constructor function, you also need to set the authTokenProvider property with the instance of type AuthenticationTokenProvider that can be used to generate and pass the JWT token.

The class should implement the AuthenticationTokenProvider interface, which then overrides the getAuthToken() function to generate and return a JWT token. The function will be used by the SDK to generate a new token whenever it needs to establish a new connection and existing token is expired. The code would look something like this:

import android.app.Application;
import oracle.cloud.bots.mobile.core.AuthenticationTokenProvider;
import oracle.cloud.bots.mobile.core.Bots;
import oracle.cloud.bots.mobile.core.BotsCallback;
import oracle.cloud.bots.mobile.core.BotsConfiguration;
import oracle.cloud.bots.mobile.core.BotsSDKException;

public class YourApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        try {
                BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<SERVER_URI>, true, getApplicationContext()) //  Configuration to initialize the SDK
                    .authTokenProvider(new AuthTokenProvider())
                    .build();

                Bots.init(this, botsConfiguration, new BotsCallback() {  // Initialize the SDK
                    @Override
                    public void onSuccess(Response paramResponse) {
                        // Handle init success
                    }
                    @Override
                    public void onFailure(Response paramResponse) {
                        // Handle init failure
                    }
                });
        } catch (BotsSDKException e) {
           // Handle Exceptions thrown by SDK
        }
    }

    private class AuthTokenProvider implements AuthenticationTokenProvider {
        @Override
        public String getAuthToken() {
            // Generate a new JWT Token and return
        }
    }
}

Display the user interface:

import oracle.cloud.bots.mobile.ui.ConversationActivity;
 
...
 
 
ConversationActivity.show(this);

App Development

Network Configuration

Property Name	Description	Required?	Default Value
`channelId`	The ID of the Oracle Android channel.	Yes	N/A
`userId`	The unique identifier for user. This value gets initialized by the SDK if not provided.	No	A randomly generated value
`authTokenProvider`	An instance of AuthenticationTokenProvider, which is used to generate a new token whenever the SDK needs to establish a new connection using a client authentication-enabled channel and when existing token is expired.	Yes	N/A

Feature Flags

Property	Description	Required?	Default Value
`actionsLayout`	An object of type `ActionsLayout` which sets the layout orientation of local, global, card and form actions.	No	`new ActionsLayout(LayoutOrientation.VERTICAL, LayoutOrientation.VERTICAL, LayoutOrientation.VERTICAL, LayoutOrientation.VERTICAL)`
`disablePastActions`	A field for disabling the button clicks on the messages that a user has already interacted with. The allowed values are `all`, `none`, and `postback`. The behavior enabled by this property is independent of the digital assistant-level configuration for disabling the selection of past actions. You need to set the two separately.	No	`all`
`displayPreviousMessages`	Enables or disables the display of previous messages after the SDK has been re-initialized. When set to `false`, the previous messages are not displayed for the user after re-initialization of SDK.	No	`true`
`enableAgentSneakPreview`	Sends the user-entered text along with the typing status to the agent.	No	`false`
`enableArrowsForHorizontalCards`	Enables navigation arrows for the horizontal card view when set to `true`, but disables them when set to `false`.	No	`false`
`enableAttachment`	Enables attachment sharing in the chat view. When set to `true`, you can restrict items that are available in the share menu popup using `shareMenuItems`. This setting is deprecated in Release 22.02. Use `timeStampType` instead.	No	`true`
`enableAttachmentSecurity`	When set to `true`, extra headers are passed to the attachment upload requests to ensure that they can't be downloaded without passing a valid signed JWT token as an authorization header. Note: Do not enable this setting if the skill connects to an ODA instance that's Version 20.08 or runs on any version prior to 20.08. This property only applies to client auth-enabled connections to Versions 20.12 and higher of the ODA platform.	No	`false`
`enableClearMessage`	Enables the clear message button in the header of the chat view.	No	`false`
`enableDefaultClientResponse`	When set to `true`, the client displays default responses when the skill response has been delayed, or when there's no response from the skill.	No	`false`
`enableEndConversation`	Enables the user to end the conversation and reset the chat session. It also clears the local conversation history, disconnects from the chat server and closes the activity	No	`true`
`enableNotification`	Enables or disables new message notifications from the SDK when the chat application is running in the background. The SDK won't provide any notifications when you set this flag to `false`.	No	`true`
`enableNotificationSound`	Enables the notification sound on new skill messages while the chat view is open. This feature only applies when `enableNotificationSoundSetting` is set to `false`.	No	`true`
`enableNotificationSoundSetting`	Enables the notification sound setting button in the chat view header.	No	`false`
`enableSendTypingStatus`	Sends the typing status of the user to the live agent.	No	`false`
`enableSpeechRecognition`	Enables the speech recognition service to convert user voice to text messages. Set this property to `true` to use the `enableSpeechRecognitionAutoSend` property.	No	`false`
`enableSpeechRecognitionAutoSend`	When `enableSpeechRecognitionAutoSend` is set to `true` (the default), the user's speech response is automatically sent to the chat server (and displays as a sent message in the chat window). When set to `false`, the user's speech response is rendered in the message text field before it's sent to the chat server so that the user can modify it before sending it manually, or delete the message. This functionality is only available when `enableSpeechRecognition` is set to `true`.	No	`true`
`enableSpeechSynthesis`	Enables the skill's audio response button in the header of the chat view. When the button is in the unmute state, the skill's responses are read aloud.	No	`false`
`enableTimestamp`	Enables the timestamp for messages.	No	`true`
`googleMapsApiKey`	The Google Maps API key that’s used to display a location preview image for Location messages.	No	N/A
`initSpeechSynthesisMuted`	This flag, which is only applicable when `enableSpeechSynthesis` is `true`, determines whether the skill's audio response button will be active (unmute) by default initially, or muted. By default, it is set to `true`, where the button is muted.	No	`true`
`initUserHiddenMessage`	A user text message that's used to initiate a conversation. This message, which is sent when chat view is ready, does not actually display in the chat.	No	N/A
`initUserProfile`	Initializes the user profile before the conversation starts. The profile payload must be of type `User`. The profile is updated before sending the value in `initUserHiddenMessage`.	No	N/A
`linkHandler`	A field used to set link handler for opening links, either in a webview or a browser. `WebviewLinkHandlerType` is an enum with two values: `BROWSER` and `WEBVIEW`.	No	`WebviewLinkHandlerType.BROWSER`
`messageModifierDelegate`	An instance of type `MessageModifierDelegate` which is used to receive callbacks before certain events in the conversation.	No	N/A
`multiLangChat`	Enables the chat widget to both detect a user's language and allow the user to select a preferred language from a dropdown menu in the header. Multi-Lingual Chat describes how create this menu.	No
`notificationCustomizer`	An instance of the `NotificationCustomizer` class which is used to customize notifications received from SDK.	No	N/A
`reconnectMaxAttempts`	The number of attempts made by the chat widget to reconnect when the initial connection fails.	No	`5`
`shareMenuItems`	Restricts the items that display in the share menu item and customizes the menu's icons and labels. To configure these items, pass an ArrayList of Objects to `shareMenuItems`. The Arraylist objects can either be `ShareMenuItem` enum values that are mapped to the share menu items or a `ShareMenuCustomItem` object. To use this flag, you must set `enableAttachment` to `true`.	No	N/A
`showBotAvatar`	Enables the display of the skill's avatar icon beside the skill's messages.	No	`false`
`showConnectionStatus`	Enables the connection status to display in the chat view header.	No	`false`
`showPersonAvatar`	Enables the display of the skill’s avatar icon beside the skill’s messages and on the notifications. If your skill has live agent integration, setting this flag to `true` displays agent’s avatar icon beside the agent’s messages and on the notifications.	No	`false`
`showTypingIndicator`	Enables the typing indicator to display while waiting for skill's response.	No	`true`
`showUserAvatar`	Enables the display of a user avatar icon beside a user messages.	No	`false`
`speechLocale`	The expected locale of the user's speech that's used for voice recognition. The supported locales are Australia-English (`en-au`), UK-English (`en-gb`), French (`fr-fr`), German (`de-de`), Indian-Hindi (`hi-in`), Indian-English (`en-in`), Italian (`it-it`), Brazilian Portuguese (`pt-br`), Spanish (`es-es`), and the default, US-English (`en-us`). Call the `Bots.setSpeechLocale(<locale>)` API to set the speech locale dynamically. Voice recognition will not work if an unsupported locale has been passed.	No	`"en-us"`
`speechSynthesisService`	An instance of the SpeechSynthesisService that's used to inject a text to speech (TTS) service. Applicable only if `enableSpeechSynthesis` is set to `true`.	No	N/A
`speechSynthesisVoicePreferences`	Configures the language and voice that read the skill's messages aloud by taking a list of instances that are of type `SpeechSynthesisSetting` as its parameter. If the device does not support the preferred voice, then the default voice for the preferred language is used instead. When neither the preferred voice or language are supported, then the default voice and language are used.	No	N/A
`subtitle`	Sets the `subtitle` of the chat view, which is displayed below the title on the chat view header. If the `subtitle` flag is set and either (or both) the `showConnectionStatus`, `showTypingIndicator` are set to `true`, then the subtitle is displayed instead of either the connection status or the typing indicator.	No	N/A
`timestampFormat`	Formats the timestamps that display in the messages. It can accept a string of format tokens like `'mm:ss:a'`. Refer to the Android documentation for information about valid timestamp patterns	No	N/A
`timestampType`	If you enable timestamps by setting `enableTimestamp` to `true`, you can use set a relative timestamp that appears only on the latest message by setting `timestampType: 'relative'`.	N/A
`title`	Sets the title in the header of the chat view.	No	N/A
`typingIndicatorTimeout`	Sets the number of seconds after which the typing indicator is automatically removed if the chat view has not yet received the response.	No	30
`typingStatusInterval`	Sets the interval, in seconds, to throttle the typing status that's sent to the live agent.	No	`3`
`WebViewConfig`	Sets the attributes of the in-widget webview, such as its size (partial or full) or customizations to the clear button. Customizations to clear button inside the webview can also be done.	No	Sets the configuration settings for of the webview.
`youtubeApiKey`	Supports the streaming of YouTube videos by setting the YouTube API key.	No	N/A

Custom Colors

You can modify the chat view's colors to give it a custom look. To configure these colors, define name attributes for the <color> elements in the res/values/colors.xml file (located in the project's app resources) using the the following keys. The following snippet demonstrates a modifications of the color that's used for the background of the skill's message (odaas_primary) and the text color used in the skill's (odaas_on_primary) message while maintaining the default colors for other resources.

<resources>
    <color name="odaas_primary">#6699FF</color>
    <color name="odaas_on_primary">#000000</color>
</resources>

Note:

Version 20.8.1 of the SDK resets the colors for prior versions. For example, if the background color of the action buttons in the existing implementation is #418980, then this will be changed to the default color of odaas_action_background (introduced in 20.8.1), which is #FFFFFF. For implementations created using versions prior to 20.8.1, you can set custom colors by updating the res/values/colors.xml file in your application. For example:

<resources>
        <color name="odaas_action_background">#418980</color>
    </resources>

Key	Description	Default Value
`odaas_action_background`	The background color of the action and global action buttons.	`#FFFFFF`
`odaas_agent_avatar_background_color`	The background color used for the avatar layout when agent avatar is unavailable and the agent name initials display instead.	`#A890B6`
`odaas_agent_avatar_text_color`	The text color used for the agent name initials that display inside the agent avatar layout.	`#FFFFFF`
`odaas_agent_name_text_color`	The text color used for the agent name that displays above the agent messages.	`#A6161513`
`odaas_background`	The background color for the view.	`#F5F4F2`
`odaas_bot_avatar_background`	The background color used for the skill's avatar.	`#bdbdbd`
`odaas_bot_avatar_background`	The background color of the skill avatar.	`#bdbdbd`
`odaas_card_background`	The background color of the card messages and their action buttons.	`FFFFFF`
`odaas_dialog_accent`	The color that's used for buttons and progress bars on the dialog window that is shown before clearing messages and while uploading attachments.	`161513`
`odaas_dialog_background`	The background color of the dialog window that is shown before clearing messages and while uploading attachments.	`#FFFFFF`
`odaas_dialog_box_negative_button_background`	The background color of the decline button that appears in the alert dialog box.	`@android:color/transparent`
`odaas_dialog_box_negative_button_text_color`	The text color of the decline button that appears in the alert dialog box.	`#161513`
`odaas_dialog_box_positive_button_background`	The background color of the confirm button that appears in the alert dialog box.	`#161513`
`odaas_dialog_box_positive_button_text_color`	The text color of the confirm button that appears in the alert dialog box.	`#FFFFFF`
`odaas_error`	The text color that's used in error messages.	`@android:color/white`
`odaas_footer_accent`	The border and cursor color of the input field in the footer.	`#01579B`
`odaas_footer_attach_button`	The color of the attachment button.	`#161513`
`odaas_footer_background`	The background color of the footer.	`#FFFFFF`
`odaas_footer_buttons`	The background color of the interactive buttons in the footer, except for the send button.	`161513`
`odaas_footer_inline_send_button`	The color of the inline send button that appears within the input field when `enableSpeechRecognitionAutoSend` is set to `true`.	`#161513`
`odaas_footer_input_background`	The background color of the input field in the footer.	`#FFFFFF`
`odaas_footer_mic_button`	The color of the mic button.	#`161513`
`odaas_footer_send_button`	The color of send button.	`#FFFFFF`
`odaas_footer_send_button_background`	The background color of the send button.	`#161513`
`odaas_header_buttons`	The background color of the interactive buttons in the header.	`#FFFFFF`
`odaas_on_action_background`	The text color used with the odaas_action_background color.	`@android:color/black`
`odaas_on_background`	The text color used with the `odaas_background` color.	`@android:color/black`
`odaas_on_card_action_text`	The text color of the action buttons on the card.	`@android:color/black`
`odaas_on_card_description_text`	The text color used for the description of the card.	`@android:color/white`
`odaas_on_card_title_text`	The text color used for the title of the card.	`@android:color/white`
`odaas_on_dialog_background`	The text color used with the `odaas_dialog_background color` on dialog windows.	`@android:color/black`
`odaas_on_footer_input_background`	The text color used with the `odaas_footer_input_background` color in the footer.	`@android:color/black`
`odaas_on_multichat_spinner_background`	The background color of the multi-language chat dropdown menu before the popup window opens.	`#F1EFED`
`odaas_on_multichat_spinner_popup_background`	The background color of the multi-language chat dropdown menu after the popup window opens.	`#FFFFFF`
`odaas_on_multichat_spinner_popup_border`	The border color of the multi-language chat dropdown menu items after the popup window opens.	`#BDBDBD`
`odaas_on_multichat_spinner_popup_text_color`	The text color used for the items in the multi-language chat dropdown menu.	`@android:color/black`
`odaas_on_multichat_spinner_text_color`	The text color for a selected item in the multi-language chat dropdown menu.	`#161513`
`odaas_on_primary`	The text color that's used with the `odaas_primary` color	`#161513`
`odaas_on_primary_variant_dark`	The text color used with the `odaas_primary_variant_dark` color.	`#161513`
`odaas_on_primary_variant_light`	The text color used with the `odaas_primary_variant_light` color.	`@android:color/black`
`odaas_on_secondary`	The text color used with the `odaas_secondary` color.	`#161513`
`odaas_on_secondary_variant_light`	The text color used with the `odaas_secondary_variant_light` color.	`@android:color/black`
`odaas_on_speech_view_background`	The text color used with the `odaas_speech_view_background` color in speech mode.	`@android:color/white`
`odaas_on_status_bar_transparent`	The background color of status bar when the webview is opened.	`@android:color/transparent`
`odaas_on_webview_header_background_redwood`	The background color of the in-widget webview header in the Redwood Theme mode	`#201E1C`
`odaas_person_avatar_background`	The background color of the user avatar.	`#bdbdbd`
`odaas_primary`	The primary branding color that's used for the background of the skill's message and for the background of the interactive buttons in the footer.	`#FFFFFF`
`odaas_primary_status_bar`	The color that's used in the status bar.	`#DCD7D1`
`odaas_primary_variant_dark`	The dark variant of primary color that's used in app bar and in notifications.	`#F1EFED`
`odaas_primary_variant_light`	The light variant of the primary color that's used in the background for the skill's attachment messages.	`#E4E1DD`
`odaas_rating_star`	The color that indicates that a user has not yet selected a rating feedback button.	`@android:color/white`
`odaas_rating_star_fill`	The color that indicates that a user has selected a rating feedback button.	`#DAA520`
`odaas_secondary`	The secondary branding color that's used for the background of the user messages background and for the background of the skill's action buttons.	`#E4E1DD`
`odaas_secondary_variant_dark`	The dark variant of the secondary color that's used for the background of user attachment messages.	`#CCCCCC`
`odaas_secondary_variant_light`	The light variant of the secondary color that's used in background for the actions buttons that have been disabled.	`#BDBDBD`
`odaas_selected_text_highlighted_color`	The color of the text that's highlighted for a copy or share operation.	`#B6AFAF`
`odaas_speech_view_background`	The background color of the footer in speech mode.	`#FFFFFF`
`odaas_speech_view_button`	The color of the cancel button in speech mode.	`#161513`
`odaas_speech_visualizer_background`	The background color of the speech visualizer in speech mode.	`#12000000`
`odaas_speech_visualizer_color`	The bar color of the speech visualizer in speech mode.	`#5C926D`
`odaas_timestamp_font_color`	The text color used with the `odaas_timestamp_header_background` color in the relative timestamp mode.	`#5b5652`
`odaas_timestamp_header_background`	The background color used with the timestamp header in the relative timestamp mode.	`#d3d3d3`

Custom Text

You can customize the default text displayed in the chat view by modifying the following strings. You can configure these strings by defining the name attributes for <string> elements in the app resource's res/value/strings.xml file using the following keys. For example, to change the title of the chat view, define the odaas_bot_chat_title key:

<resources>
    <string name="odaas_bot_chat_title">Support</string>
</resources>

In this example, only the chat title has been changed. The other string resources maintain their default values.

Key	Description	Default Value
`odaas_bot_chat_title`	The title of the chat view that's displayed in the chat view header. This resource is used only when the `title` feature flag is not set.	`Digital Assistant`
`odaas_bot_status_connected`	The status text that displays when the connection between chat view and the Oracle Chat Server has been established.	`Connected`
`odaas_bot_status_connecting`	The status text that displays while the chat view connects to the Oracle Chat Server.	`Connecting`
`odaas_bot_status_disconnected`	The status text that displays when the connection between the chat view and the Oracle Chat Server has closed.	`Disconnected`
`odaas_bot_status_responding`	The status text that displays while the user waits for the skill's response. This string is deprecated in Release 22.06.	`Responding...`
`odaas_button_clear_label`	The text for the clear button in the webview.	`DONE`
`odaas_capture_photo`	The menu item text in the attachment popup that's used for sending photos captured by the device's camera which are to be uploaded to the server as attachments.	`Capture Photo`
`odaas_captured_image_folder`	The name of the folder inside the Pictures directory where images that have been clicked will be saved. If no customizations have been provided, then by default, the clicked images are saved inside the Camera folder of DCIM.	N/A
`odaas_clear_messages_dialog_button_no`	The action text that appears on the Clear Messages popup for a negative action.	`No`
`odaas_clear_messages_dialog_button_yes`	The action text that appears on the Clear Messages popup for a positive action.	`Yes`
`odaas_content_desc_attachment_loaded`	The content description for the attachment message after loading the attachment successfully.	`Open attachment`
`odaas_content_desc_attachment_loading`	The content description for the attachment message while the attachment is loading.	`Loading attachment`
`odaas_content_desc_attachment_loading_error`	The content description for the attachment message when the attachment fails loading.	`Error in loading attachment`
`odaas_content_desc_audio_pause`	The content description for the pause button of the audio player.	`Pause audio`
`odaas_content_desc_audio_play`	The content description for the play button of the audio player.	`Play audio`
`odaas_content_desc_button_attach`	The tooltip that appears when a long press gesture has been detected on the attachment button. Also, the content description for the attachment button.	`Upload Attachment`
`odaas_content_desc_button_audio_response_off`	The tooltip that appears when a long press gesture has been detected on the mute button for the audio response. Also, the content description for the mute button of the audio response.	`Unmute`
`odaas_content_desc_button_audio_response_on`	The tooltip that appears when a long press gesture has been detected on the unmute button for the audio response. Also, the content description for the unmute button of the audio response.	`Mute`
`odaas_content_desc_button_back`	The tooltip that appears when a long press gesture has been detected on the back button on the chat view header. Also, the content description for back button.	`Navigate Up`
`odaas_content_desc_button_cancel`	The tooltip that appears when a long press gesture has been detected on the keyboard button that is shown while user’s voice message is being recorded. Also, the content description for the keyboard button.	`Cancel`
`odaas_content_desc_button_clear`	The tooltip that appears when a long press gesture has been detected on the clear button. Also, the content description for the clear button.	`Clear Chat`
`odaas_content_desc_button_download`	The tooltip that appears when a long press gesture has been detected on the download button. Also, the content description for the download button.	`Download`
`odaas_content_desc_button_end_conversation`	The content description for the end conversation button.	`End Conversation`
`odaas_content_desc_button_notification_sound_off`	The tooltip that appears when a long press gesture has been detected on the mute button for the notification sound. Also, the content description for the mute button of the notification sound.	`Turn On Notification Sound`
`odaas_content_desc_button_notification_sound_on`	The tooltip that appears when a long press gesture has been detected on the unmute button for the notification sound. Also, the content description for the unmute button of the notification sound.	`Turn Off Notification Sound`
`odaas_content_desc_button_send`	The tooltip that appears when a long press gesture has been detected on the Send button. Also, the content description for the send button.	`Send`
`odaas_content_desc_button_speak`	The tooltip that appears when a long press gesture has been detected on the Microphone button. Also, the content description for the microphone button.	`Speak`
`odaas_content_desc_location_loaded`	The content description for the location message after loading the location preview image successfully.	`Open Location in Maps`
`odaas_content_desc_location_loading`	The content description for the location message while the location preview image is loading.	`Loading location preview image`
`odaas_content_desc_location_loading_error`	The content description for the location message when the location preview image loading fails.	`Error in loading location preview image. Tap to reload image.`
`odaas_content_desc_multi_lang_chat`	The text that appears along with the language detection icon in the overflow menu.	`Select Language`
`odaas_content_desc_read_status`	The content description for the tick mark (`'✓'`) for read messages. This string appears only when `enableTimestamp` is set to `true`.	`Read`
`odaas_content_desc_video_pause`	The content description for the pause button of video player.	`Pause video`
`odaas_content_desc_video_play`	The content description for the play button of video player.	`Play video`
`odaas_content_timestamp_a_few_moments_ago`	The relative timestamp that displays ten seconds after the message has been received and before 60 seconds has elapsed since the last message was received.	`a few moments ago`
`odaas_content_timestamp_day`	The relative timestamp that displays every day since the previous message was received. `%1$s` is replaced by the number of days that have passed.	`%1$sd ago`
`odaas_content_timestamp_hour`	The relative timestamp that displays every hour for the first 24 hours after the previous message was received. `%1$s` is replaced by the number of hours that have passed.	`%1$shr ago`
`odaas_content_timestamp_min`	The relative timestamp that displays every minute since the last message was received. `%1$s` is replaced by the number of minutes that have passed.	`%1$smin ago`
`odaas_content_timestamp_month`	The relative timestamp that displays every month since the previous message was received. `%1$s` is replaced by the number of months that have passed.	`%1$smth ago`
`odaas_content_timestamp_now`	The relative timestamp that displays for a new message.	`Now`
`odaas_content_timestamp_year`	The relative timestamp that displays each year after the previous message was received. `%1$s` is replaced by the number of years that have passed.	`%1$syr ago`
`odaas_default_greeting_message`	The default client greeting response that's displayed when the skill response has not received within the number of seconds set by `defaultGreetingTimeout`.	`Hey, Nice to meet you! Allow me a moment to get back to you.`
`odaas_default_greeting_timeout`	The default timeout, in seconds, after which a default greeting message displays.	`5`
`odaas_default_sorry_message`	The default client response when the skill response has not received a message within the number of seconds set by `typingIndicatorTimeout`.	`I\'m sorry, but I can't get the right content right now. Please try again.`
`odaas_default_wait_message`	The default response that displays at the interval when an actual skill response has not received. This interval is set, in seconds, by `defaultWaitMessageInterval`.	`I\'m still working on your request. Thank you for your patience!`
`odaas_default_wait_message_interval`	he default interval, in seconds, that the default wait message displays.	`5`
`odaas_dialog_text_clear_messages`	The text displayed within a popup that prompts the user for confirmation before clearing the messages.	`Clear messages?`
`odaas_download_dialog_message`	The message in the download dialog popup that displays when a user initiates a download from within the in-widget webview.	`Do you want to save`
`odaas_download_dialog_negative_button`	The text for download dialog's negative button that cancels a download that a user has initiated from within the in-widget webview.	`Cancel`
`odaas_download_dialog_positive_button`	The text for download dialog's negative button that confirms a download that a user has initiated from within the in-widget webview.	`Yes`
`odaas_download_dialog_title`	The title of the download dialog popup that displays when a user initiates a download from within the in-widget webview.	`Download`
`odaas_end_conversation_action_yes`	The text for the confirm button in the end session confirmation prompt.	`Yes`
`odaas_end_conversation_alert_message`	The message body of the end conversation confirmation prompt.	`This will also clear your conversation history.`
`odaas_end_conversation_alert_no`	The text for the decline button in the end session confirmation prompt.	`No`
`odaas_end_conversation_alert_title`	The title of the end conversation confirmation prompt.	`Are you sure you want to end the conversation?`
`odaas_error_in_capturing_photo`	The error message that's displayed when an error occurs while capturing a photo from the camera of the device.	`Error in capturing photo.`
`odaas_error_in_recording_audio`	The error message that's displayed when an error occurs while establishing connection to Oracle speech server.	`Error in recording audio. Please try again later.`
`odaas_error_in_speech_recognition`	The error message that's displayed when no input, or too much input, is given in speech.	`Speech Recognition Error.`
`odaas_error_speech_unsupported_locale`	The error message that's displayed when a voice recording has been attempted and an unsupported speech locale has been configured for voice recognition.	`The set speech locale is not supported. Can not start recording.`
`odaas_file_uploading_in_progress`	The text displayed within the popup while uploading a user's attachment to the Oracle Server.	`Uploading file to server.....`
`odaas_hint_edit_text_user_message`	The placeholder text that appears in the user input field.	`Type your message`
`odaas_hint_text_view_speech_mode`	The placeholder text that appears in the text view of speech mode before the user starts speaking.	`Speak your message`
`odaas_no_messages_to_clear`	The message displayed when there are no messages to clear.	`No messages to clear`
`odaas_no_speech_error`	The status text that's displayed when the Chat Server cannot recognize a voice because no user input has been detected.	`Could not detect the voice, no message sent.`
`odaas_notification_attachment_message`	The message that's displayed in the notification for an attachment message that's received from the skill. The text for `%1$s` is set to the `Notification title` that's defined using the `NotificationCustomizer` class, described in the SDK (available from the ODA and OMC download page ).	`%1$s has sent you an Attachment Message.`
`odaas_notification_card_message`	The message that's displayed in the notification for a Card message that's received from the skill. The text for `%1$s` is set to the `Notification title` that's defined using the `NotificationCustomizer` class, described in the SDK (available from the ODA and OMC download page ).	`%1$s has sent you a Card Message.`
`odaas_notification_card_message`	The message that is displayed in the notification for a card message received from the skill.
`odaas_notification_fallback_message`	The fallback message that is displayed in the notification for a message received from the skill. The text for `%1$s` is set to the `Notification title` that's defined using the `NotificationCustomizer` class, described in the SDK (available from the ODA and OMC download page ).	`%1$s has sent you a Message.`
`odaas_notification_fallback_message`	The fallback message that is displayed in the notification for a message received from the skill.
`odaas_notification_intent`	The activity to open, when tapped by the user, on notifications received from the SDK. The text for `%1$s` is set to the `Notification title` that's defined using the `NotificationCustomizer` class, described in the SDK (available from the ODA and OMC download page ).	`oracle.cloud.bots.mobile.ui.ConversationActivity`
`odaas_notification_location_message`	The message that is displayed in the notification for a location message received from the skill. The text for `%1$s` is set to the `Notification title` that's defined using the `NotificationCustomizer` class, described in the SDK (available from the ODA and OMC download page ).	`%1$s has sent you a Location Message.`
`odaas_page_loading`	The text within the popup while a page is loading inside a webview.	`Please Wait...Page is Loading.`
`odaas_require_audio_recording_permission`	The error message that's displayed when users deny permission for recording the audio.	`Audio recording permission is needed to record audio`
`odaas_require_download_to_storage_access_permission`	The error message that's displayed when users deny the storage access permission to save the downloaded file.	`Storage access permission is needed to download file`
`odaas_require_location_permission`	The error message that's displayed when users deny permission to access their locations.	`Location access permission is needed to track location`
`odaas_require_storage_access_permission`	The error message that's displayed when access to storage has been denied.	`Storage access permission is needed to attach files`
`odaas_share_audio`	The menu item text in the attachment popup used for sharing audio file.	`Share Audio`
`odaas_share_file`	The menu item text in the attachment popup used for sharing a generic file.	`Share File`
`odaas_share_message_chooser_title`	The title of the application chooser that's displayed when user clicks the Share action.	`Share using:`
`odaas_share_visual`	The menu item text in the attachment popup used for sharing an image or video file.	`Share Image/Video`
`odaas_skill_message`	The skill message indicator for screen readers. It's spoken by screen readers before the skill response. The text is not displayed in the chat view.	`Skill says:`
`odaas_speech_to_text_dialog_placeholder`	The placeholder text displayed on the speech recognition popup before the user starts speaking. This property is deprecated in Release 20.8.1. From that release onward, the setting for this property will be ignored.	`Listening.....`
`odaas_star_rating`	The message that's read aloud when a user rating button has been clicked while the user is in accessibility mode.	`Rate %1$s star`
`odaas_too_much_speech_error`	The error message that's displayed when a user provides voice message that's too long to be recognized.	`Too much voice input to recognize. Can not generate recognized text.`
`odaas_user_message`	The user message indicator for screen readers. It's spoken by screen readers before the user messages.	`I say:`

Localization

To localize these strings, define the name attributes for the <string> elements in the app resource's res/values-<your-language-code>/strings.xml file with the keys. For example, to localize the title of the chat view in English, define the following in a file called res/value-en/strings.xml:

<resources>
    <string name="odaas_bot_chat_title">Support</string>
</resources>

To localize the title in French, you'd add the following to a file called res/value-fr/strings.xml file:

<resources>
    <string name="odaas_bot_chat_title">Soutien</string>
</resources>

The values for res/value/strings.xml are used by default for the keys that are not found in res/values-<your-language-code>/strings.xml. For these two examples, the default values would be used for the resources that are not defined in either the res/value-fr/strings.xml or res/value-en/strings.xml files.

Custom Icons

Configure drawables by adding the required images or vector assets to the app resource's res/drawable folder that have the following names.

Name	Description
`ic_odaas_agent_avatar`	The avatar icon for the messages from the live agent. This icon displays in notifications only when the `showBotAvatar` feature flag is set to `true`.
`ic_odaas_bot_avatar`	The avatar icon for the skill's messages. This icon displays on notifications only when the `showBotAvatar` feature flag is set to `true`.
`ic_odaas_download`	The download icon that appears on the attachment message that's sent by the skill.
`ic_odaas_image_zoom`	The icon for the zoom control that appears on an image attachment message that's sent by the skill.
`ic_odaas_notification_app_icon`	The app icon displayed in the status bar and on notifications received from SDK library.
`ic_odaas_person_avatar`	The avatar icon for user messages.
`ic_odaas_rating`	The icon used for the feedback rating button.

Set Feature Flags

Use the BotsConfiguration.BotsConfigurationBuilder class to initialize the BotsConfiguration class.

Use these constructors:

BotsConfiguration.BotsConfigurationBuilder(String chatServerUrl, boolean clientAuthEnabled, Context context)
Parameters:
- chatServerUrl – The URL to the Oracle Chat and Attachment Server. This cannot be null.
- clientAuthEnabled - Determines whether the channel's client authentication settings are enabled or disabled.
- context – The application context. This cannot be null.
```
BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<SERVER_URI>, false, getApplicationContext())
```
BotsConfiguration.BotsConfigurationBuilder(String chatServerUrl, Context context) – This can be used to establish a connection to channel with client authentication enabled.
Parameters:
- chatServerUrl – The URL to the Oracle Chat and Attachment Server. This cannot be null.
- context – The application context. This cannot be null.
```
BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<SERVER_URI>, getApplicationContext())
```

Initialize the SDK

Use the following methods to initialize the SDK:

public static void init(Application application, BotsConfiguration botsConfiguration)
public static void init(Application application, BotsConfiguration botsConfiguration, BotsCallback botsCallback)
public static void init(Application application, String chatServerUrl, String channelId, String userId, BotsCallback botsCallback)
public static void init(Application application, String chatServerUrl, AuthenticationTokenProvider authTokenProvider, BotsCallback botsCallback)

public static void init(Application application, BotsConfiguration botsConfiguration)

The public static void init(Application application, BotsConfiguration botsConfiguration) method initializes all of the services based on the BotsConfiguration instance passed by the user and establishes the WebSocket connection to the Oracle Chat Server.

Parameters:

application – The application instance. This cannot be null.
botsConfiguration – The BotsConfiguration object used to control the features of library. This cannot be null.

Bots.init(getApplication(),
      botsConfiguration);

public static void init(Application application, BotsConfiguration botsConfiguration, BotsCallback botsCallback)

The public static void init(Application application, BotsConfiguration botsConfiguration, BotsCallback botsCallback) method initializes all of the services based on the BotsConfiguration instance passed by the user and establishes the WebSocket connection to the Oracle Chat Server.

Parameters:

application – The application instance. This cannot be null.
botsConfiguration – The BotsConfiguration object used to control the features of library. This cannot be null.
botsCallback – The callback received while establishing the connection.

Bots.init(getApplication(), botsConfiguration, new BotsCallback() {
    @Override
    public void onSuccess(Response paramResponse) {}
 
    @Override
    public void onFailure(Response paramResponse) {}
});

public static void init(Application application, String chatServerUrl, String channelId, String userId, BotsCallback botsCallback)

The public static void init(Application application, String chatServerUrl, String channelId, String userId, BotsCallback botsCallback) method initializes all of the services with the default configuration. This method can be invoked to connect to a channel with client authentication disabled.

Parameters:

application – The application instance. This cannot be null.
chatServerUrl – The URL of the Oracle Chat Server. This cannot be null.
channelId – The Channel ID belonging to the Oracle Android channel that's routed to the skill or digital assistant. This cannot be null.
userId – A unique identifier for the user. The SDK initializes this value when it's not provided.
botsCallback – The callback received while establishing the connection to the Oracle Chat Server.

Bots.init(getApplication(), chatServerUrl, authTokenProvider, new BotsCallback() {
    @Override
    public void onSuccess(Response paramResponse) {}
 
    @Override
    public void onFailure(Response paramResponse) {}
});

public static void init(Application application, String chatServerUrl, AuthenticationTokenProvider authTokenProvider, BotsCallback botsCallback)

Invoke the public static void init(Application application, String chatServerUrl, AuthenticationTokenProvider authTokenProvider, BotsCallback botsCallback method to connect to a channel that has client authentication enabled. This method initializes all of the services with the default configuration.

Parameters:

application – The application instance. This cannot be null.
chatServerUrl – The URL of the Oracle Chat Server. This cannot be null.
authTokenProvider – The instance of AuthenticationTokenProvider, which is used to generate the authentication token whenever it's needed.
botsCallback – The callback received while establishing connection.

BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<SERVER_URI>, getApplicationContext())

Interface AuthenticationTokenProvider

The public String getAuthToken method returns the string of the generated token.

An instance of this interface can be passed to the authTokenProvider property to allow the SDK to generate a new authentication token when one is required to establish an authenticated channel connection. When implementing this interface, override the

public String
                getAuthToken

method.

private class AuthTokenProvider implements AuthenticationTokenProvider {
    @Override
    public String getAuthToken() {
        // Generate a new JWT Token and return
    }
}

Interface BotsCallback

This interface acts as a callback while initializing the library.

void onSuccess(Response paramResponse) – This method is called when the web socket connection has been successfully established.
void onFailure(Response paramResponse) – This method is called on any failures that occur while initializing the library.

Show Conversation Activity

After initializing the SDK, display the conversation view by invoking

public
                                static void show(Context context)

. This method's context parameter is the context from which to start the activity.

ConversationActivity.show(getApplicationContext())

Customize Notifications

You can customize the notifications received for the skill's messages by instantiating the NotificationCustomizer class and passing the instance to the notificationCustomizer property. The constructors are:

NotificationCustomizer()– Initializes the notification channel with the default configuration.
NotificationCustomizer(String channelId) – Initializes the notification channel with the given channel ID. The channelId parameter is the ID of the notification channel through which the notifications are sent.
NotificationCustomizer(String channelId, String channelName, String description, String title) – Initializes the notification channel with the given parameters:
- channelID – The ID of the notification channel through which notifications are sent.
- channelName – The name of the notification channel through which the notifications are sent.
- description – A description of the notification channel through which the notifications are sent.
- title – The title displayed on the notifications.

For example:

new BotsConfiguration.NotificationCustomizer(<NOTIFICATION_CHANNEL_ID>,
    <NOTIFICATION_CHANNEL_NAME>, <NOTIFICATION_CHANNEL_DESCRIPTION>, <NOTIFICATION_TITLE>);

Features

Absolute and Relative Timestamps

Feature flag: timestampType: TimestampMode.RELATIVE

You can enable absolute or relative timestamps for chat messages. Absolute timestamps display the exact time for each message. Relative timestamps display only on the latest message and express the time in terms of the seconds, days, hours, months, or years ago relative to the previous message.The precision afforded by absolute timestamps make them ideal for archival tasks, but within the limited context of a chat session, this precision detracts from the user experience because users must compare timestamps to find out the passage of time between messages. Relative timestamps allow users to track the conversation easily through terms like Just Now and A few moments ago that can be immediately understood. Relative timestamps improve the user experience in another way while also simplifying your development tasks: because relative timestamps mark the messages in terms of seconds, days, hours, months, or years ago, you don't need to convert them for timezones.

Configure Relative Timestamps

To add a relative timestamp:

Enable timestamps – enableTimestamp: true
Enable relative timestamps – timestampType: 'relative'

When you configure the timestamp (timestampType: 'relative'), an absolute timestamp displays before the first message of the day as a header. This header displays when the conversation has not been cleared and older messages are still available in the history.

This timestamp is updated at following regular intervals (seconds, minutes, etc.) until a new message is received.

For first 10s
Between 10s-60s
Every minute between 1m-60m
Every hour between 1hr-24hr
Every day between 1d-30d
Every month between 1m-12m
Every year after first year

When a new message is loaded into the chat, the relative timestamp on the previous message is removed and a new timestamp appears on the new message displaying the time relative to the previous message. At that point, the relative timestamp updates until the next messages arrives.

Action Buttons Layout

Feature flag: actionsLayout

actionsLayout sets layout direction for the local, global, card and form actions. When you set this as LayoutOrientation.HORIZONTAL, these buttons are laid out horizontally and will wrap if the content overflows.

BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<Server_URI>, false, getApplicationContext())
        .channelId(<CHANNEL_ID>)
        .userId(<USER_ID>)
        .actionsLayout(actionsLayout)
        .build();

Attachment Filtering

(Required) <Enter a short description here.>

Feature flag: shareMenuItems

Use this feature to restrict, or filter, the item types that are available in the share menu popup, set the file size limit for uploads (such as 1024 in the following snippet), and customize the menu's icons and labels.

Note:

Before you can configure shareMenuItems, you must set enableAttachment to true.

ArrayList<Object> customItems = new ArrayList<>();
        ShareMenuCustomItem shareMenuCustomItem1  = new ShareMenuCustomItem("pdf bin", "Label1", 1024, R.drawable.odaas_menuitem_share_file);
        ShareMenuCustomItem shareMenuCustomItem2  = new ShareMenuCustomItem("doc", "Label2", R.drawable.odaas_menuitem_share_file);
        ShareMenuCustomItem shareMenuCustomItem3  = new ShareMenuCustomItem("csv");
        ArrayList<Object> customItems = new ArrayList<>(Arrays.asList(shareMenuCustomItem1,shareMenuCustomItem2,shareMenuCustomItem3,ShareMenuItem.CAMERA));
        BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(sharedPreferences.getString(getString(R.string.pref_name_chat_server_host), Settings.CHAT_SERVER_URL), false, getApplicationContext())
        .channelId(<CHANNEL_ID>)
        .userId(<USER_ID>)
        .shareMenuItems(customItems)
        .enableAttachment(true)
        .build();

If a ShareMenuCustomItem object has no value or a null for the label, as does

shareMenuCustomItem3 =
                ShareMenuCustomItem('csv')

in the preceding snippet, then a type string that’s suffixed to share_ becomes the label. For shareMenuCustomItem3, the label is share_csv.

Note:

You can allow users to upload all file types by setting the type of a ShareMenuCustomItem object as *.

public static void shareMenuItems(ArrayList<Object> shareMenuItems)

You can dynamically update the share menu items popup by calling the Bots.shareMenuItems(customItems); API, where customItems is an ArrayList of Objects. Each object can either be of type ShareMenuItem enum values or an object of ShareMenuCustomItem.

ArrayList<Object> customItems = new ArrayList<>();
        ShareMenuCustomItem shareMenuCustomItem1  = new ShareMenuCustomItem("pdf bin", "Label1", 1024, R.drawable.odaas_menuitem_share_file);
        ShareMenuCustomItem shareMenuCustomItem2  = new ShareMenuCustomItem("doc", "Label2", R.drawable.odaas_menuitem_share_file);
        ShareMenuCustomItem shareMenuCustomItem3  = new ShareMenuCustomItem("csv");
        customItems.add(shareMenuCustomItem1);
        customItems.add(ShareMenuItem.CAMERA);
        customItems.add(ShareMenuItem.FILE);
        customItems.add(shareMenuCustomItem2);
        customItems.add(shareMenuCustomItem3);
        Bots.shareMenuItems(customItems);

public static void shareMenuItems()

You can get the share menu items list by calling the Bots.shareMenuItems(); API.

Bots.shareMenuItems()

Connect and Disconnect Methods

The skill can be connected and disconnected using the

public void
                disconnect()

and public void connect() methods. The WebSocket is closed after calling the direct method:

Bots.disconnect();

Calling the following method re-establishes the WebSocket connection if the skill has been in a disconnected state:

Bots.connect();

When public void connect(Botsconfiguration botsconfiguration) is called with a new botsconfiguration object, the existing WebSocket connection is closed and a new connection is established using the new botsconfiguration object.

BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<SERVER_URI>, false, getApplicationContext()) // Configuration to initialize the SDK
        .channelId(<CHANNEL_ID>)
        .userId(<USER_ID>)
        .build();

        Bots.connect(botsConfiguration);

Default Client Responses

Feature flag: enableDefaultClientResponse: true (default: false)

Use enableDefaultClientResponse: true to provide default client-side responses accompanied by a typing indicator when the skill response has been delayed, or when there's no skill response at all. If the user sends out the first message/query, but the skill does not respond with the number of seconds set by the odaas_default_greeting_timeout flag, the skill can display a greeting message that's configured using the odaas_default_greeting_message translation string. Next, the client checks again for the skill's response. The client displays the skill's response if it has been received, but if it hasn't, then the client displays a wait message (configured with the odaas_default_wait_message translation string) at intervals set by the odaas_default_wait_message_interval flag. When the wait for the skill response exceeds the threshold set by the typingIndicatorTimeout flag, the client displays a sorry response to the user and stops the typing indicator. You can configure the sorry response using the odaas_default_sorry_message translation string.

Delegation

Feature configuration: messageModifierDelegate

The delegation feature lets you set a delegate to receive callbacks before certain events in the conversation. To set a delegate, a class must implement the interface MessageModifierDelegate and pass its instance to the messageModifierDelegate property.

private MessageDelegate implements MessageModifierDelegate {
    @Override
    public Message beforeSend(Message message) {
        // Handle before send delegate here
    }

    @Override
    public Message beforeDisplay(Message message) {
        if (message != null && message.getPayload() != null && message.getPayload().getType() == MessagePayload.MessageType.CARD) {
            ((CardMessagePayload)message.getPayload()).setLayout(CardLayout.VERTICAL);
        }
        return message;
    }

    @Override
    public Message beforeNotification(Message message) {
        // Handle before notification delegate here
    }
}
    @Override
    public void beforeEndConversation(CompletionHandler completionHandler) {
        // Handle before end conversation end delegate here
        // Trigger completionHandler.onSuccess() callback after successful execution of the task.
        // Trigger completionHandler.onFailure() callback when the task is unsucessful.
        }
        }

public Message beforeDisplay(Message message)

The public Message beforeDisplay(Message message) delegate allows a skill's message to be modified before it is displayed in the conversation. The modified message that's returned by the delegate displays in the conversation. If the method returns null, then the message is not displayed.

public Message beforeDisplay(Message message)

The public Message beforeDisplay(Message message) delegate allows a user message to be modified before it is sent to the chat server. The message returned by the delegate is sent to the skill. If it returns null, then the message is not sent.

public Message beforeNotification(Message message)

The public Message beforeNotification(Message message) delegate allows a skill's message to be modified before a notification is triggered. If it returns null, then the notification is not triggered.

Display the Conversation History

You can either enable or display of a user's local conversation histor after the SDK has been re-initialized by setting displayPreviousMessages to true or false in the bots configuration. When set to false, previous messages are not displayed for the user, after re-initialization of SDK.

End the Chat Session

FeatureFlag: enableEndConversation: true

enableEndConversation: true adds a close button to the header view that enables users to explicitly end the current chat session. A confirmation prompt dialog opens when users click this close button and when they confirm the close action, the SDK sends an event message to the skill that marks the end of the chat session. The SDK then disconnects the skill from the instance, collapses the chat widget, and erases the current user's conversation history. The SDK triggers a delegate on beforeEndConversation(CompletionHandler completionHandler) which can be used to perform a task before sending close session request to server. It also raises a OnChatEnd() event that you can register for.

Opening the chat widget afterward starts a new chat session.

public static void endChat()

The conversation can also be dynamically ended by calling Bots.endChat() API.

Bots.endChat()

CompletionHandler

CompletionHandler is an event listener that is implemented on the SDK, which listens for completion of the task being performed on the beforeEndConversation(CompletionHandler completionHandler) delegate in the host application. Refer to the Javadoc included with the SDK available from the ODA and OMC download page.

Foreground Service

A foreground service starts by default to prevent the app from getting terminated in the background, even when it has been running there for a long period of time. To preserve the battery, users can turn this service off through a call to the following API, which disables the service.

ConversationActivity.enableForegroundService(false)

Headless SDK

The SDK can be used without its UI. To use it in this mode, import only the com.oracle.bots.client.sdk.android.core-22.12.aar package into the project as described in Add the Oracle Android Client SDK to the Project.

The SDK maintains the connection to server and provides APIs to send messages, receive messages, and get updates for the network status and for other services. You can use the APIs to interact with the SDK and update the UI.

You can send a message using any of the send*() APIs available in Bots class. For example, public static void sendMessage(String text) sends text message to skill or digital assistant.

public static void sendMessage(String text)

Sends a text message to the skill. Its text parameter is the text message.

Bots.sendMessage("I want to order a Pizza");

EventListener

To listen for the connection status change, the message sent to the skill and received from the skill, and the attachment upload status events, a class should implement the EventListener interface, which then implements the functionality for:

void onStatusChange(ConnectionStatus connectionStatus) – This method is called when the WebSocket connection status changes. Its connectionStatus parameter is the current status of the connection. Refer to the Javadocs included in the SDK (available from the ODA and OMC download page ) for more details about the ConnectionStatus enum.
void onMessageReceived(Message message) – This method is called when a new message is received from the skill. Its message parameter is the message received from the skill. Refer to the Javadocs included in the SDK (available from the ODA and OMC download page ) for more details about the Message class.
void onMessageSent(Message message) - This method is called when a message is sent to the skill. Its message parameter is the message sent to the skill. Refer to the Javadocs included in the SDK (available from the ODA and OMC download page ) for more details about the Message class.
void onAttachmentComplete() – This method is called when an attachment upload has completed.

public class BotsEventListener implements EventListener {
    @Override
    public void onStatusChange(ConnectionStatus connectionStatus) {
        // Handle the connection status change
    }
 
    @Override
    public void onMessageReceived(Message message) {
        // Handle the messages received from skill/DA
    }
 
 
    @Override
    public void onMessageSent(Message message) {
        // Handle the message sent to skill or Digital Assistant
    }
 
    @Override
    public void onAttachmentComplete() {
        // Handle the post attachment upload actions
        // Close the attachment upload progress popup if any etc.
    }
}

The instance of type EventListener should then be passed to setEventListener(EventListener eventListener).

public static void setEventListener(EventListener eventListener)

Sets the listener to receive the response returned from the skill to get updates on connection status change and to receive an update when the attachment upload is complete. Its eventListener parameter is an instance of type EventListener to receive updates.

Bots.setEventListener(new BotsEventListener());

In-Widget Webview

Feature flag: linkHandler

You can configure the link behavior in chat messages to allow users to access web pages from within the chat widget. Instead of having to switch from the conversation to view a page in a tab or separate browser window, a user can remain in the chat because the chat widget opens the link within a Webview.

Configure the In-Widget Webview

Feature flag: webViewConfig

You can configure the webview linking behavior by setting the linkHandler function to WebviewLinkHandlerType.WEBVIEW. You can set the size and display of the webview itself using a webViewConfig class object:

BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<SERVER_URI>, false, getApplicationContext()) // Configuration to initialize the SDK
    .channelId(<CHANNEL_ID>)
    .userId(<USER_ID>)
    .linkHandler(WebviewLinkHandlerType.WEBVIEW)
    .webViewConfig(new WebViewConfig()
                                .webViewSize(WebviewSizeWindow.FULL)
                                .webViewTitleColor(<COLOR_VALUE>)
                                .webviewHeaderColor(<COLOR_VALUE>)
                                .clearButtonLabel(<BUTTON_TEXT>)
                                .clearButtonLabelColor(<COLOR_VALUE>)
                                .clearButtonIcon(<IMAGE_ID>))
    .build();

As illustrated in this code snippet, you can set the following attributes for the webview.

Attribute	Settings
`webViewSize`	Sets the screen size of the in-widget webview window with the `WebviewSizeWindow` enum, which has two values: `PARTIAL` (`WebviewSizeWindow.PARTIAL`) and `FULL` (`WebviewSizeWindow.FULL`).
`clearButtonLabel`	Sets the text used for clear/close button in the top right corner of webview. The default text is `DONE`.
`clearButtonIcon`	Sets an icon for the clear button, which appears left-aligned inside the button.
`clearButtonLabelColor`	Sets the color of text of clear button label.
`clearButtonColor`	Sets the background color for the clear button.
`webviewHeaderColor`	Sets the background color for webview header.
`webviewTitleColor`	Sets the color of title in the header. The title is the URL of the web link that has been opened.

Multi-Lingual Chat

Feature flag: multiLangChat

The Android SDK's native language support enables the chat widget to both detect a user's language and allow the user to select the conversation language from a dropdown menu in the header. Users can switch between languages, but only in between conversations, not during a conversation because the conversation gets reset whenever a user selects a new language.

Enable the Language Menu

You can enable a menu that allows users to select a preferred language from a dropdown menu by defining the multiLangChat property with an object containing the supportedLanguage ArrayList, which is comprised of language tags (lang) and optional display labels (label). Outside of this array, you can optionally set the default language with the primary property as illustrated by the (primary("en") in the following snippet.

ArrayList<SupportedLanguage> supportedLanguages = new ArrayList<>();
supportedLanguages.add(new SupportedLanguage("en"));
supportedLanguages.add(new SupportedLanguage("fr", "French"));
supportedLanguages.add(new SupportedLanguage("de", "German"));
MultiLangChat multiLangChat = new MultiLangChat().supportedLanguage(supportedLanguages).primary("en");
BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<SERVER_URI>, false, getApplicationContext()) // Configuration to initialize the SDK
    .channelId(<CHANNEL_ID>)
    .userId(<USER_ID>)
    .multiLangChat(multiLangChat)
    .build();

The chat widget displays the passed-in supported languages in a dropdown menu that's located in the header. In addition to the available languages, the menu also includes a Detect Language option. When a user selects a language from this menu, the current conversation is reset, and a new conversation is started with the selected language. The language selected by the user persists across sessions in the same browser, so the user's previous language is automatically selected when the user revisits the skill through the page containing the chat widget.

Here are some things to keep in mind when configuring multi-language support:

You need to define a minimum of two languages to enable the dropdown menu to display.
If you omit the primary key, the widget automatically detects the language in the user profile and selects the Detect Language option in the menu.

Disable Language Menu

Starting with Version 21.12, you can also configure and update the chat language without also having to configure the language selection dropdown menu by passing primary in the initial configuration without the supportedLanguage ArrayList. The value passed in the primary variable is set as the chat language for the conversation.

Language Detection

In addition to the passed-in languages, the chat widget displays a Detect Language option in the dropdown. Selecting this option tells the skill to automatically detect the conversation language from the user's message and, when possible, to respond in the same language.

Note:

If you omit the primary property, the widget automatically detects the language in the user profile and activates the Detect Language option in the menu.

You can dynamically update the selected language by calling the setPrimaryChatLanguage(lang) API. If the passed lang matches one of the supported languages, then that language is selected. When no match can be found, Detect Language is activated. You can also activate the Detected Language option by calling Bots.setPrimaryChatLanguage('und') API, where 'und' indicates undetermined.

You can update the chat language dynamically using the setPrimaryChatLanguage(lang) API even when the dropdown menu has not been configured.

Multi-Lingual Chat Quick Reference

To do this...	...Do this
Display the language selection dropdown to end users.	Define `multiLangChat` property with an object containing the `supportedLanguage` ArrayList.
Set the chat language without displaying the language selection dropdown menu to end users.	Define `primary` only.
Set a default language.	Pass `primary` with the `supportedLanguage` Arraylist. The `primary` value must be one of the supported languages included the array.
Enable language detection.	Pass `primary` as `und`.
Dynamically update the chat language.	Call the `setPrimaryChatLanguage(lang)` API.

Share Menu Options

By default, the share menu displays options for the following file types:

visual media files (images and videos)
audio files
general files like documents, PDFs, and spreadsheets
location

By passing an ArrayList of Objects to shareMenuItems shareMenuItems(Arraylist<Object>), you can restrict, or filter, the type of items that are available in the menu, customize the menu's icons and labels, and limit the upload file size (such as 1024 in the following snippet). These objects can either be an object of shareMenuCustomItem, or ShareMenuItem enum values that are mapped to the share menu items: ShareMenuItem.CAMERA for the camera menu item (if supported by the device), ShareMenuItem.VISUAL for sharing an image or video item, ShareMenuItem.AUDIO for sharing an audio item, and ShareMenuItem.FILE for sharing a file item. Passing either an empty value or a null value displays all of the menu items that can be passed as ShareMenuItem enum values.

If a ShareMenuCustomItem object has no value or a null for the label as does shareMenuCustomItem3 = ShareMenuCustomItem('csv') in the following snippet, then a type string that's suffixed to share_ becomes the label. For shareMenuCustomItem3, the label is share_csv. You can allow users to upload all file types by setting the type of a ShareMenuCustomItem object as *.

Note:

This configuration only applies when enableAttachment is set to true.

ArrayList<Object> customItems = new ArrayList<>();
ShareMenuCustomItem shareMenuCustomItem1  = new ShareMenuCustomItem("pdf bin", "Label1", 1024, R.drawable.odaas_menuitem_share_file);
ShareMenuCustomItem shareMenuCustomItem2  = new ShareMenuCustomItem("doc", "Label2", R.drawable.odaas_menuitem_share_file);
ShareMenuCustomItem shareMenuCustomItem3  = new ShareMenuCustomItem("csv");
ArrayList<Object> customItems = new ArrayList<>(Arrays.asList(shareMenuCustomItem1,shareMenuCustomItem2,shareMenuCustomItem3,ShareMenuItem.CAMERA));
BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(sharedPreferences.getString(getString(R.string.pref_name_chat_server_host), Settings.CHAT_SERVER_URL), false, getApplicationContext())
         .channelId(<CHANNEL_ID>)
         .userId(<USER_ID>)
        .shareMenuItems(customItems)
        .enableAttachment(true)
        .build();

public static void shareMenuItems()

You can get the share menu items list by calling the Bots.shareMenuItems(); API.

Bots.shareMenuItems()

public static void shareMenuItems(ArrayList<Object> shareMenuItems)

You can dynamically update the share menu items popup by calling the Bots.shareMenuItems(customItems); API, where customItems is an ArrayList of Objects. Each object can either be of type ShareMenuItem enum values or an object of


                ShareMenuCustomItem

ArrayList<Object> customItems = new ArrayList<>();
ShareMenuCustomItem shareMenuCustomItem1  = new ShareMenuCustomItem("pdf bin", "Label1", 1024, R.drawable.odaas_menuitem_share_file);
ShareMenuCustomItem shareMenuCustomItem2  = new ShareMenuCustomItem("doc", "Label2", R.drawable.odaas_menuitem_share_file);
ShareMenuCustomItem shareMenuCustomItem3  = new ShareMenuCustomItem("csv");
customItems.add(shareMenuCustomItem1);
customItems.add(ShareMenuItem.CAMERA);
customItems.add(ShareMenuItem.FILE);
customItems.add(shareMenuCustomItem2);
customItems.add(shareMenuCustomItem3);
Bots.shareMenuItems(customItems);

Speech Recognition

Feature flag: enableSpeechRecognition

Setting the enableSpeechRecognition feature flag to true enables the microphone button to display along with the send button whenever the user input field is empty.

Setting this property to true also supports the functionality enabled by the enableSpeechRecognitionAutoSend property, which when also set to true, enables the user's speech response to be sent to the chat server automatically while displaying the response as a sent message in the chat window. You can allow users to first edit (or delete) their dictated messages before they send them manually by setting enableSpeechRecognitionAutoSend to false.

Speech recognition is utilized through the following methods:

public static void startRecording(IBotsSpeechListener listener)

Starts recording the user's voice message. The listener parameter is an instance of IBotsSpeechListener to receive the response returned from the server.

public static void stopRecording()

Stops recording the user's voice message.

public static boolean isRecording()

Checks whether the voice recording has started or not. Returns true if the recording has started. Otherwise, it returns false.

IBotsSpeechListener

A class should implement the interface IBotsSpeechListener which then implements the functionality for the following methods:

void onError(String error)

This method is called when errors occur while establishing the connection to the server, or when there is either no input given or when too much input is given. Its error parameter is the error message.

void onSuccess(String utterance)

This method is called when a final result is received from the server. Its utterance parameter is the final utterance received from the server.

Note:

This method is deprecated in Release 20.8.1.

void onSuccess(BotsSpeechResult botsSpeechResult)

This method is called when a final result is received from the server. Its parameter, botsSpeechResult, is the final response received from the server.

void onPartialResult(String utterance)

This method is called when a partial result is received from the server. Its utterance parameter is the partial utterance received from the server.

void onClose(int code, String message)

This method is called when the connection to server closes.

Parameters:

code – The status code
message – The reason for closing the connection

void onOpen()

The method called when the connection to server opens.

onActiveSpeechUpdate(byte[] speechData)

This method is called when there is an update in the user's voice message, which can then be used for updating the speech visualizer. It's parameter is speechData, the byte array of the recorded voice of user.

public class BotsSpeechListener implements IBotsSpeechListener {
    @Override
    public void onError(String error) {
            // Handle errors
    }
 
    @Override
    public void onSuccess(String utterance) {
        // This method was deprecated in release 20.8.1.
        // Handle final result
    }
 
 
    @Override
    public void onSuccess(BotsSpeechResult botsSpeechResult) {
        // Handle final result
    }  
 
    @Override
    public void onPartialResult(String utterance) {
        // Handle partial result
    }
 
    @Override
    public void onClose(int code, String message) {
        // Handle the close event of connection to server
    }
 
    @Override
    public void onOpen() {
        // Handle the open event of connection to server
    }
 
 
    @Override
    public void onActiveSpeechUpdate(byte[] speechData) {
        // Handle the speech update event
    }
}
 
 
Bots.startRecording(new BotsSpeechListener()); // Start voice recording
 
if (Bots.isRecording()) {
    Bots.stopRecording(); // Stop voice recording
}

Speech Synthesis

Feature flag: enableSpeechSynthesis
Functionality configuration: speechSynthesisVoicePreferences

The SDK has been integrated with speech synthesis to read the skill's message aloud when a new message is received from skill:

Users can mute or unmute the skill's audio response using a button that's located in the header of the chat view. You enable this feature by setting the enableSpeechSynthesis feature flag to true.
You can set the preferred language that read the skill's messages aloud with the speechSynthesisVoicePreferences property. This parameter that sets the language and voice is a list of SpeechSynthesisSetting instances (described in the SDK's Javadoc that you download from the ODA and OMC download page). This property enables a fallback when the device doesn't support the preferred language or voice. If the device does not support the preferred voice, then the default voice for the preferred language is used instead. When neither the preferred voice or language are supported, then the default voice and language are used.

public static void initSpeechSynthesisService()

Initializes the speech synthesis service. This method should be called in the onCreate() method of an Activity to initialize the speech synthesis service. The initialization of speech synthesis service will be done when the SDK library initializes only if the enableSpeechSynthesis feature flag is set to true.

public class ConversationActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Bots.initSpeechSynthesisService();
    }
}

public static void startBotAudioResponse(String text)

Starts reading the skill's response aloud. Its text parameter is the text for the skill's message that's read aloud.

Bots.startBotAudioResponse("What kind of crust do you want?");

Note:

This method was deprecated in Release 21.08.

public static void stopBotAudioResponse()

Stops reading the skill's response aloud.

Bots.stopBotAudioResponse()

public static boolean isSpeaking()

Checks if the skill's response is currently being read aloud or not.

Returns true if the skill's response is currently being read aloud. Otherwise, it returns false.

if (Bots.isSpeaking()) {
    Bots.stopBotAudioResponse();
}

public static void shutdownBotAudioResponse()

Releases the resources used by the SDK.

This method is called in the onDestroy() method of ConversationActivity.

public class ConversationActivity extends AppCompatActivity {
    @Override
    protected void onDestroy() {
        super.onDestroy();
        Bots.shutdownBotAudioResponse();
    }
}

Speech Service Injection

Feature flag : ttsService

The speechSynthesisService feature flag allows you to inject any text-to-speech (TTS) service -- your own, or one provided by a third-party vendor -- into the SDK. To inject a TTS service, you must first set the enableSpeechSynthesis feature flag to true and then pass an instance of the SpeechSynthesisService interface to the speechSynthesisService flag.

The SpeechSynthesisService Interface

You create an instance of a class that's an implementation of the SpeechSynthesisService interface. It implements these methods:

initTextToSpeechService(@NonNull Application application,
                        @NonNull BotsConfiguration botsConfiguration)

: Initializes a new TTS service.

Parameter	Description
`application`	The application. This cannot be null.
`botsConfiguration`	The `BotsConfiguration` object used to control the features of the library. This cannot be null.

speak(String phrase): Adds a phrase that's to be spoken to the utterance queue. It's phrase parameter is the text to be spoken.
isSpeaking(): Checks whether or not the audio response is being spoken. It returns false if there is no ongoing audio response is being spoken.

Note:
This method was deprecated in Release 21.08.
stopTextToSpeech(): Stops any ongoing speech synthesis.

Note:
This method was deprecated in Release 21.08.
shutdownTextToSpeech(): Releases the resources used by the TextToSpeech engine.
getSpeechSynthesisVoicePreferences(): Returns the voice preferences array which is used to choose the best match for the available voice that's used for speech synthesis.
setSpeechSynthesisVoicePreferences(ArrayList<SpeechSynthesisSetting> speechSynthesisVoicePreferences): Sets the voice preferences array which is used to choose the best available voice match for speech synthesis. The speechSynthesisVoicePreferences parameter is the voice preference array for speech synthesis.
onSpeechSynthesisVoicePreferencesChange(ArrayList<SpeechSynthesisSetting> speechSynthesisVoicePreferences): Sets the speech synthesis voice to the best available voice match.

Note:
This method was deprecated in Release 21.08.
We recommend that you call this method inside the setSpeechSynthesisVoicePreferences method after setting the voice preferences ArrayList. The speechSynthesisVoicePreferences parameter is the voice preference array for speech synthesis.
onSpeechRecognitionLocaleChange(Locale speechLocale): This method gets invoked when the speech recognition language has changed. By overriding this method, you can set the speech synthesis language to the same language as the speech recognition language. The speechLocale parameter is the locale set for speech recognition.

   private class TextToSpeechServiceInjection implements SpeechSynthesisService {

        @Override
        public void initTextToSpeechService(@NonNull Application application, @NonNull BotsConfiguration botsConfiguration) {
            // Initialisation of Text to Speech Service.
        }

        @Override
        public void speak(String phrase) {
            // Adds a phrase to the utterance queue to be spoken
        }

        @Override
        public boolean isSpeaking() {
            // Checks whether the bot audio response is being spoken or not.
            return false;
        }

        @Override
        public void stopTextToSpeech() {
            // Stops any ongoing speech synthesis
        }

        @Override
        public void shutdownTextToSpeech() {
            // Releases the resources used by the TextToSpeech engine.
        }

        @Override
        public ArrayList<SpeechSynthesisSetting> getSpeechSynthesisVoicePreferences() {
            // The voice preferences array which is used to choose the best match available voice for speech synthesis.
            return null;
        }

        @Override
        public void setSpeechSynthesisVoicePreferences(ArrayList<SpeechSynthesisSetting> speechSynthesisVoicePreferences) {
            // Sets the voice preferences array which can be used to choose the best match available voice for speech synthesis.
        }

        @Override
        public SpeechSynthesisSetting onSpeechSynthesisVoicePreferencesChange(ArrayList<SpeechSynthesisSetting> speechSynthesisVoicePreferences) {
            // Sets the speech synthesis voice to the best voice match available.
            return null;
        }

        @Override
        public void onSpeechRecognitionLocaleChange(Locale speechLocale) {
            // If the speech recognition language is changed, the speech synthesis language can also be changed to the same language.
        }
    }

Note:

SpeechSynthesisService#setSpeechSynthesisVoicePreferencesonSpeechSynthesisVoicePreferencesChange(ArrayList<SpeechSynthesisSetting>)

and SpeechSynthesisService#onSpeechSynthesisVoicePreferencesChange(ArrayList<SpeechSynthesisSetting>) have been deprecated in this release and have been replaced by SpeechSynthesisService#setTTSVoice(ArrayList<SpeechSynthesisSetting>) and SpeechSynthesisService#getTTSVoice(). Previously,


                    SpeechSynthesisService#setSpeechSynthesisVoicePreferencesonSpeechSynthesisVoicePreferencesChange

set the speech synthesis voice preference array and SpeechSynthesisService#onSpeechSynthesisVoicePreferencesChange set the best voice available for speech synthesis and returned the selected voice. Now, the same functionality is attained through the new methods:

SpeechSynthesisService#setTTSVoice(ArrayList<SpeechSynthesisSetting>
                    TTSVoices)

, which sets both the speech synthesis voice preference array and the best available voice for speech synthesis and SpeechSynthesisService#getTTSVoice(), which returns the selected voice for speech synthesis.

Typing Indicator for User-Agent Conversations

Feature flag: enableSendTypingStatus

When enabled, the SDK sends a RESPONDING typing event along with the text that's currently being typed by the user to . This shows a typing indicator on the agent console. When the user has finished typing, the SDK sends a LISTENING event to Oracle Fusion Cloud B2C Service (Oracle B2C Service). This hides the typing indicator on the agent console.

Similarly, when the agent is typing, the SDK receives a RESPONDING event from Oracle B2C Service. On receiving this event, the SDK shows a typing indicator to the user. When the agent is idle, the SDK receives LISTENING event from Oracle B2C Service. On receiving this event, the SDK hides the typing indicator that's shown to the user.

The sendUserTypingStatus API enables the same behavior for headless mode.

public void sendUserTypingStatus(TypingStatus status, String text)

To show the typing indicator on the agent console:
```
Bots.sendUserTypingStatus("RESPONDING", "<Message_Being_Typed>");
```
To hide the typing indicator on the agent console:
```
Bots.sendUserTypingStatus("LISTENING", "");
```

To control user-side typing indicator, use the onReceiveMessage(Message message) event. For example:

public void onReceiveMessage(Message message) {
     if (message != null) {
       MessagePayload messagePayload = message.getPayload();
       if (messagePayload instanceof StatusMessagePayload) {
         StatusMessagePayload statusMessagePayload = (StatusMessagePayload) messagePayload;
         String status = statusMessagePayload.getStatus();

         if (status.equalsIgnoreCase(String.valueOf(TypingStatus.RESPONDING))) {
           // show typing indicator
         } else if (status.equalsIgnoreCase(String.valueOf(TypingStatus.LISTENING))
           // hide typing indicator
         }
       }
     }

There are two more settings that provide additional control:

typingStatusInterval – By default, the SDK sends the RESPONDING typing event every three seconds to Oracle B2C Service. Use this flag to throttle this event. The minimum value that can be set is three seconds.
enableAgentSneakPreview - Oracle B2C Service supports showing the user text as it's being entered. If this flag is set to true (the default is false), then the SDK sends the actual text. To protect user privacy, the SDK sends … instead of the actual text to Oracle B2C Service when the flag is set to false.

Note:
This feature must be enabled in both the SDK and the Oracle B2C Service chat configuration.

Update the User Avatar

You can enable dynamic updating of the user avatar at runtime.

public void updatePersonAvatar

Sets the user avatar for the all the messages, including previous messages.

ConversationActivity.setUserPerson(Object);

Expose Agent Details

Use these APIs to modify agent name, the text color, avatar, agent name initials, text color, and avatar background.

public AgentDetails getAgentDetails()

Returns an object containing the agent details.

Bots.getAgentDetails(AgentDetails);

Refer to the Javadocs for more details about the AgentDetails class.

public void setAgentDetails(AgentDetails)

Overrides the agent details received from server.

Bots.setAgentDetails(AgentDetails);

public AgentDetails getAgentDetails()

Returns an object containing the agent details.

Bots.getAgentDetails(AgentDetails);

Refer to the Javadocs for more details about the AgentDetails class.

Voice Visualizer

When voice support is enabled (enableSpeechRecognition(true)), the footer of the chat widget displays a voice visualizer, a dynamic visualizer graph that indicates the frequency level of the voice input. The visualizer responds to the modulation of the user's voice by indicating whether the user is speaking too softly or too loudly. This visualizer is created using the stream of bytes that are recorded while the user is speaking, which is also exposed in the IBotsSpeechListener#onActiveSpeechUpdate(byte[]) method for use in headless mode.

The chat widget displays a voice visualizer when users click the voice icon. It's an indicator of whether the audio level is sufficiently high enough for the SDK to capture the user’s voice. The user’s message, as it is recognized as text, displays below the visualizer.

Note:

Voice mode is indicated when the keyboard icon appears.

When enableSpeechRecognitionAutoSend(true), the recognized text is automatically sent to the skill after the user has finished dictating the message. The mode then reverts to text input. When enableSpeechRecognitionAutoSend(false), the mode also reverts to text input, but in this case, users can modify the recognized text before sending the message to the skill.

Message Model

To use features like headless mode and delegate, you need to understand both user and skill messages. Everything that's received or sent from the Oracle Chat Server is represented as a message, one that's sent from the user to the skill, or from the skill to the user.

Base Types

These are the base types used in all messages sent from the user to the skill and vice versa. They are the building blocks of all messages.

Attachment

Represents an attachment that's sent by the user.

Name	Description	Type	Required?
`type`	The attachment type	string (valid values: `audio`, `file`, `image`, `video`)	Yes
`url`	The download URL for the attachment	string	Yes
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

For example:

{
    "type": "image",
    "url": "https://www.oracle.com/us/assets/hp07-oow17-promo-02-3737849.jpg"
}

Location

Represents a location object.

Name	Description	Type	Required?
`title`	The location title	string	No
`URL`	The URL for displaying the location on a map	string	No
`latitude`	The GPS coordinate's longitude value	double	Yes
`longitude`	The GPS coordinate's latitude value	double	Yes
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

For example:

{
    "title": "Oracle Headquarters",
    "url": "https://www.google.com.au/maps/place/37°31'47.3%22N+122°15'57.6%22W",
    "longitude": -122.265987,
    "latitude": 37.529818
}

Heading

Represents a heading for tables in a Table or Table-Form object.

Name	Description	Type	Required?
`label`	The heading label	String	Yes
`alignment`	The positioning of ht e label within the cell	`"left"`, `"right"`, `"center"`	Yes
`width`	The suggested percentage of the table width that should be provided to the heading.		No
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

Field

Represents the atomic information of a table cell or a form field within the Table, Form, and Table-Form objects, provided as key-value pair.

Name	Description	Type	Required?
`displayType`	The field type	`"text"`, `"link"`	Yes
`label`	The field key	String	Yes
`value`	The field value	String	No
`linkLabel`	A short label for the link value if `displayType` is `link`.	String	No
`alignment`	The positioning of the label within its cell	`"left"`, `"right"`, `"center"`	No
`width`	The suggested percentage of the table width that should be provided to the field		No
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

Row

Represents an array of fields.

Name	Description	Type	Required?
`fields`	An array of fields	Array <field>	Yes
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

Form

Represents an array of fields along with a title. Used in Table-Form messages for nested forms of a table row.

Name	Description	Type	Required?
`title`	The form title	String	No
`field`	An array of fields	Array <field>	Yes
`actions`	An array of actions	Array <BotsAction>	No
`channelExtensions`	The channel-specific extension properties associated with the message	JSON object	No

PaginationInfo

Represents the paging information for the results in the Table, Form, and Table-Form objects.

Name	Description	Type	Required?
`totalCount`	The total results count	number	Yes
`rangeSize`	The range size of the results per page	number	Yes
`status`	The paging status message	string	Yes
`currentRangeSize`	The size of curent range of results	number	Yes
`rangeStart`	The starting offset of the current range of results	number	Yes
`nextRangeSize`	The size of the next range of results	number	Yes
`hasPrevious`	Indicates whether there is a previous set of results	boolean	Yes
`hasNext`	Indicates whether there is a next set of results	boolean	Yes

Action

An action represents something that the user can select.

Name	Description	Type	Required?
`type`	The action type	string	Yes
`label`	The descriptive label text for the action.	string	At least one `label` or `imageUrl` must be present.
`imageUrl`	The image for the action	string	At least one `label` or `imageUrl` must be present.
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

PostbackAction

Sends a predefined postback back to the skill when the user selects an action.

Name	Description	Type	Required?
`type`	The action type	"postback"	Yes
`postback`	The postback that's returned when the user selects an action.	A string or JSON object	Yes

For example:

{
    "type": "postback",
    "label": "Large Pizza",
    "imageUrl": "https://example.com/images/gallery/locations/11.jpg",
    "postback": {
        "state": "askSize",
        "action": "getCrust"
    }
}

CallAction

Requests the client to call a specified phone number on behalf of the user.

Name	Description	Type	Required?
`type`	The action type	"call"	Yes
`phoneNumber`	The phone number to call	string	Yes

For example:

{
    "type": "call",
    "label": "Call Support",
    "imageUrl": "http://example.com.ar/files/2016/05/cuidado.jpg",
    "phoneNumber": "18005555555"
}

urlAction

Requests the client to open a website in a new tab or in an in-app browser.

Name	Description	Type	Required?
`type`	The action type	"call"	Yes
`URL`	The URL of the website that's displayed.	string	Yes

For example:

{
    "type": "url",
    "label": "Open URL",
    "imageUrl": "http://example.com.ar/files/2016/05/cuidado.jpg",
    "url": "https://example.com/images/gallery/locations/11.jpg",
}

LocationAction

Requests the client to ask for the user's location.

Name	Description	Type	Required?
`type`	The action type	"location"	Yes

For example:

{
    "type": "location",
    "label": "Share location",
    "imageUrl": "http://images.example.com/location-clipart-location-pin-clipart-1.jpg"
}

Card

Represents a single card in the message payload.

Name	Description	Type	Required?
`title`	The title of the card, displayed as the first line on the card.	string	Yes
`description`	The description of the card	string	No
`imageUrl`	The URL of the image that is displayed.	string	No
`URL`	The website URL that's opened by a tap.	string	No
`actions`	An array of actions related to the text	array	No
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

Conversation Message

All of the messages that are part of a conversation have the following structure:

Name	Description	Type	Required?
`messagePayload`	The message payload	Message	Yes
`userId`	The user ID	string	Yes

For example:

{
    "messagePayload": {
        "text": "show menu",
        "type": "text"
    },
    "userId": "guest"
}

Message

Message is an abstract base type for all other messages. All messages extend it to provide some information.

Name	Description	Type	Required?
`type`	The message type	string	Yes

User Message

Represents a message sent from the user to the skill.

User Text Message

The simple text message that's sent to the server.

Name	Description	Type	Required?
`type`	The message type	`"text"`	Yes
`text`	The message text	string	Yes

For example:

{
    "messagePayload": {
        "text": "Order Pizza",
        "type": "text"
    },
    "userId": "guest"
}

User Postback Message

The postback response message that's sent to the server.

Name	Description	Type	Required?
`type`	The message type	`"postback"`	Yes
`text`	The postback text	string	No
`postback`	The postback of the selected action	A string or JSON object	Yes

For example:

{
    "messagePayload": {
        "postback": {
            "variables": {
                "pizza": "Small"
            },
            "system.botId": "69BBBBB-35BB-4BB-82BB-BBBB88B21",
            "system.state": "orderPizza"
        },
        "text": "Small",
        "type": "postback"
    },
    "userId": "guest"
}

User Attachment Message

The attachment response message that's sent to the server.

Name	Description	Type	Required?
`type`	The message type	`"attachment"`	Yes
`attachment`	The attachment metadata	Attachment	Yes

For example:

{
    "messagePayload": {
        "attachment": {
            "type": "image",
            "url": "http://oda-instance.com/attachment/v1/attachments/d43fd051-02cf-4c62-a422-313979eb9d55"
        },
        "type": "attachment"
    },
    "userId": "guest"
}

User Location Message

The location response message that's sent to the server.

Name	Description	Type	Required?
`type`	The message type	`"location"`	Yes
`location`	The user location information	Location	Yes

For example:

{
    "messagePayload": {
        "location": {
            "latitude": 45.9285271,
            "longitude": 132.6101925
        },
        "type": "location"
    },
    "userId": "guest"
}

Skill Message

Represents the message sent from the skill to the user.

Skill Text Message

Represents a text message.

Name	Description	Type	Required?
`type`	The message type	`"text"`	Yes
`text`	The message text	string	Yes
`headerText`	The header text for cards	string	No
`footerText`	The footer text for cards	string	No
`actions`	An array of actions related to the text.	array	No
`globalActions`	An array of global actions related to the text.	array	No
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

For example:

{
    "messagePayload": {
        "type": "text",
        "text": "What do you want to do?",
        "actions": [
            {
                "type": "postback",
                "label": "Order Pizza",
                "postback": {
                    "state": "askAction",
                    "action": "orderPizza"
                }
            },
            {
                "type": "postback",
                "label": "Cancel A Previous Order",
                "postback": {
                    "state": "askAction",
                    "action": "cancelOrder"
                }
            }
        ],
        "channelExtensions": {
            "displayType":"stars"
         }
    },
    "userId": "guest",
    "msgId": "message_id",
    "source": "BOT"
}

Location Message

represents a location message.

Name	Description	Type	Required?
`type`	The message type	`"location"`	Yes
`location`	The location	`location`	No
`headerText`	The header text for the message	string	No
`footerText`	The footer text for the message	string	No
`actions`	An array of actions related to the text	Array<Action>	No
`globalActions`	An array of global actions related to the text	Array<Action>	No
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

Skill Attachment Message

Represents an attachment message.

Name	Description	Type	Required?
`type`	The message type	`"attachment"`	Yes
`attachment`	The attachment sent	Attachment	Yes
`headerText`	The card's header text	string	No
`footerText`	the card's footer text	string	No
`actions`	An array of actions related to the text.	array	No
`globalActions`	An array of global actions related to the text.	array	No
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

Skill Card Message

Represents a set of choices that are displayed for the user, either horizontally as carousels or vertically as lists.

Name	Description	Type	Required?
`type`	The message type	`"card"`	Yes
`layout`	Whether to display the messages horizontally or vertically.	string (values: horizontal, vertical)	Yes
`cards`	An array of cards to be rendered.	array	Yes
`headerText`	The cards' header text	string	No
`actions`	An array of actions related to the text.	array	No
`globalActions`	An array of global actions related to the text.	array	No
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

{
    "messagePayload": {
        "type": "card",
        "layout": "horizontal",
        "cards": [
            {
                "title": "Hawaiian Pizza",
                "description": "Ham and pineapple on thin crust",
                "actions": [
                    {
                        "type": "postback",
                        "label": "Order Small",
                        "postback": {
                            "state": "GetOrder",
                            "variables": {
                                "pizzaType": "hawaiian",
                                "pizzaCrust": "thin",
                                "pizzaSize": "small"
                            }
                        }
                    },
                    {
                        "type": "postback",
                        "label": "Order Large",
                        "postback": {
                            "state": "GetOrder",
                            "variables": {
                                "pizzaType": "hawaiian",
                                "pizzaCrust": "thin",
                                "pizzaSize": "large"
                            }
                        }
                    }
                ]
            },
            {
                "title": "Cheese Pizza",
                "description": "Cheese pizza (i.e. pizza with NO toppings) on thick crust",
                "actions": [
                    {
                        "type": "postback",
                        "label": "Order Small",
                        "postback": {
                            "state": "GetOrder",
                            "variables": {
                                "pizzaType": "cheese",
                                "pizzaCrust": "thick",
                                "pizzaSize": "small"
                            }
                        }
                    },
                    {
                        "type": "postback",
                        "label": "Order Large",
                        "postback": {
                            "state": "GetOrder",
                            "variables": {
                                "pizzaType": "cheese",
                                "pizzaCrust": "thick",
                                "pizzaSize": "large"
                            }
                        }
                    }
                ]
            }
        ],
        "globalActions": [
            {
                "type": "call",
                "label": "Call for Help",
                "phoneNumber": "123456789"
            }
        ]
    },
    "userId": "guest",
    "msgId": "message_id",
    "source": "BOT"
    }

Skill Table Message

Represents a message that returns the results of a query in table form The message consists of an array of headings and an array of rows. The rows themselves contain a fields array that represents individual cells.

Note:

This message type is used for SQL dialogs.

Name	Description	Type	Required?
`type`	The message type	`"table"`	Yes
`headings`	An array of table headings	Array<Heading>	Yes
`rows`	An array of table rows. Each row contains a`fields` array that represents the table cells.	Array<Row>	Yes
`paginationInfo`	The paging information for the results in the table	`PaginationInfo`	No
`actions`	An array of actions related to the table	Array<Action>	No
`globalActions`	An array of global actions	Array<Action>	No
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

{
    "type":"table",
    "headerText":"A-Team",
    "headings":[
        {
            "width":20,
            "label":"First Name",
            "alignment":"left"
        },
        {
            "width":20,
            "label":"Last Name",
            "alignment":"left"
        },
        {
            "width":35,
            "label":"Title",
            "alignment":"left"
        },
        {
            "width":25,
            "label":"Phone",
            "alignment":"right"
        }
    ],
    "rows":[
        {
            "fields":[
                {
                    "displayType":"text",
                    "width":20,
                    "label":"First Name",
                    "alignment":"left",
                    "value":"Aaron"
                },
                {
                    "displayType":"text",
                    "width":20,
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Adams"
                },
                {
                    "displayType":"text",
                    "width":35,
                    "label":"Title",
                    "alignment":"left",
                    "value":"Demo Builder"
                },
                {
                    "displayType":"text",
                    "width":25,
                    "label":"Phone",
                    "alignment":"right",
                    "value":"1234567890"
                }
            ]
        },
        {
            "fields":[
                {
                    "displayType":"text",
                    "width":20,
                    "label":"First Name",
                    "alignment":"left",
                    "value":"Bob"
                },
                {
                    "displayType":"text",
                    "width":20,
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Brown"
                },
                {
                    "displayType":"text",
                    "width":35,
                    "label":"Title",
                    "alignment":"left",
                    "value":"Multi-lingual Expert"
                },
                {
                    "displayType":"text",
                    "width":25,
                    "label":"Phone",
                    "alignment":"right",
                    "value":"1234567890"
                }
            ]
        },
        {
            "fields":[
                {
                    "displayType":"text",
                    "width":20,
                    "label":"First Name",
                    "alignment":"left",
                    "value":"Charlie"
                },
                {
                    "displayType":"text",
                    "width":20,
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Chase"
                },
                {
                    "displayType":"text",
                    "width":35,
                    "label":"Title",
                    "alignment":"left",
                    "value":"Flow Builder"
                },
                {
                    "displayType":"text",
                    "width":25,
                    "label":"Phone",
                    "alignment":"right",
                    "value":"1234567890"
                }
            ]
        },
        {
            "fields":[
                {
                    "displayType":"text",
                    "width":20,
                    "label":"First Name",
                    "alignment":"left",
                    "value":"David"
                },
                {
                    "displayType":"text",
                    "width":20,
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Davidson"
                },
                {
                    "displayType":"text",
                    "width":35,
                    "label":"Title",
                    "alignment":"left",
                    "value":"Machine Learning Expert"
                },
                {
                    "displayType":"text",
                    "width":25,
                    "label":"Phone",
                    "alignment":"right",
                    "value":"1234567890"
                }
            ]
        },
        {
            "fields":[
                {
                    "displayType":"text",
                    "width":20,
                    "label":"First Name",
                    "alignment":"left",
                    "value":"Eric"
                },
                {
                    "displayType":"text",
                    "width":20,
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Eastman Junior"
                },
                {
                    "displayType":"text",
                    "width":35,
                    "label":"Title",
                    "alignment":"left",
                    "value":"Docker Expert"
                },
                {
                    "displayType":"text",
                    "width":25,
                    "label":"Phone",
                    "alignment":"right",
                    "value":"1234567890"
                }
            ]
        }
    ],
    "paginationInfo":{
        "currentRangeSize":5,
        "rangeStart":0,
        "nextRangeSize":-3,
        "hasPrevious":false,
        "hasNext":false,
        "totalCount":5,
        "rangeSize":8,
        "status":"Showing 1-5 of 5 items"
    }
}

Skill Form Message

Represents a message that returns the results of a query in a form that's read only. The message consists of an array of form results. Each form result contains a fields array with key-value pairs that represent a field.

Note:

This message type is used for SQL dialogs.

Name	Description	Type	Required?
`type`	The message type	`"form"`	Yes
`forms`	An array of form results. Each result contains a `fields` array that represents the form fields.	Array<Row>	Yes
`formColumns`	A number suggesting the number of columns in which the fields of the form should be grouped.	1, 2	Yes
`paginationInfo`	The paging information for the results in the form	`PaginationInfo`	No
`actions`	An array of actions related to the form	Array<Action>	No
`globalActions`	An array of global actions	Array<Action>	No
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

{
    "type":"form",
    "headerText":"A-Team",
    "forms":[
        {
            "fields":[
                {
                    "displayType":"text",
                    "label":"First Name",
                    "alignment":"left",
                    "value":"Aaron"
                },
                {
                    "displayType":"text",
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Adams"
                },
                {
                    "displayType":"text",
                    "label":"Title",
                    "alignment":"left",
                    "value":"Demo Builder"
                },
                {
                    "displayType":"text",
                    "label":"Phone",
                    "alignment":"left",
                    "value":"1234567890"
                },
                {
                    "linkLabel":"Open Link",
                    "displayType":"link",
                    "label":"Contact",
                    "alignment":"left",
                    "value":"https://www.example.com/in/aaron-adams-4862752"
                },
                {
                    "displayType":"text",
                    "label":"Bio",
                    "alignment":"left"
                }
            ]
        },
        {
            "fields":[
                {
                    "displayType":"text",
                    "label":"First Name",
                    "alignment":"left",
                    "value":"Bob"
                },
                {
                    "displayType":"text",
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Brown"
                },
                {
                    "displayType":"text",
                    "label":"Title",
                    "alignment":"left",
                    "value":"Multi-lingual Expert"
                },
                {
                    "displayType":"text",
                    "label":"Phone",
                    "alignment":"left",
                    "value":"1234567890"
                },
                {
                    "linkLabel":"Open Link",
                    "displayType":"link",
                    "label":"Contact",
                    "alignment":"left",
                    "value":"https://www.example.com/in/Bobbrown"
                },
                {
                    "displayType":"text",
                    "label":"Bio",
                    "alignment":"left",
                    "value":"Bob is a member of the cloud architects team which is specialized in enterprise mobility and cloud development. Bob has been directly involved with Oracle middleware since 2005 during which he held different roles in managing highly specialized teams."
                }
            ]
        },
        {
            "fields":[
                {
                    "displayType":"text",
                    "label":"First Name",
                    "alignment":"left",
                    "value":"Charlie"
                },
                {
                    "displayType":"text",
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Chase"
                },
                {
                    "displayType":"text",
                    "label":"Title",
                    "alignment":"left",
                    "value":"Flow Builder"
                },
                {
                    "displayType":"text",
                    "label":"Phone",
                    "alignment":"left",
                    "value":"1234567890"
                },
                {
                    "linkLabel":"Open Link",
                    "displayType":"link",
                    "label":"Contact",
                    "alignment":"left",
                    "value":"https://www.example.com/in/Charlie-chase-97a418"
                },
                {
                    "displayType":"text",
                    "label":"Bio",
                    "alignment":"left",
                    "value":"Charlie is a member of the enterprise mobility team. Charlie has 20+ years experience with custom development. Charlie is an expert on mobile cloud services and development tools. He is the creator of productivity tools. His latest passion is building chatbots with a minimum amount of custom code."
                }
            ]
        }
    ],
    "formColumns":2,
    "paginationInfo":{
        "currentRangeSize":3,
        "rangeStart":0,
        "nextRangeSize":2,
        "hasPrevious":false,
        "hasNext":true,
        "totalCount":5,
        "rangeSize":3,
        "status":"Showing 1-3 of 5 items"
    },
    "globalActions":[
        {
            "postback":{
                "variables":{},
                "action":"system.showMore"
            },
            "label":"Show More",
            "type":"postback"
        }
    ]
}

Skill Table-Form Message

This message combines the Table and Form message types. It represents a message that returns the results of a query in the form of a table. Each each row of the table has a read-only form in addition to the row information.

Note:

This message type is used for SQL dialogs.

Name	Description	Type	Required?
`type`	The message type	`"tableForm"`	Yes
`headings`	An array of table headings	Array<Heading>	Yes
`rows`	An array of table rows. Each row contains an array of fields that represent the table cells.	Array<Row>	Yes
`forms`	An array of form results that correspond to each table row. Each form contains a `fields` array that represents the form fields.	Array<Form>	Yes
`formColumns`	The number suggesting the number of columns in which the fields of the form should be grouped.	1, 2	Yes
`paginationInfo`	An array of global actions related to the text	Array<Action>	No
`actions`	An array of actions related to the table form	Array<Action>	No
`globalActions`	An array of global actions	Array<Action>	No
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

{
    "type":"tableForm",
    "headerText":"A-Team",
    "headings":[
        {
            "width":47,
            "label":"First Name",
            "alignment":"left"
        },
        {
            "width":47,
            "label":"Last Name",
            "alignment":"left"
        }
    ],
    "rows":[
        {
            "fields":[
                {
                    "displayType":"text",
                    "label":"First Name",
                    "alignment":"left",
                    "value":"Aaron"
                },
                {
                    "displayType":"text",
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Adams"
                }
            ]
        },
        {
            "fields":[
                {
                    "displayType":"text",
                    "label":"First Name",
                    "alignment":"left",
                    "value":"Bob"
                },
                {
                    "displayType":"text",
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Brown"
                }
            ]
        },
        {
            "fields":[
                {
                    "displayType":"text",
                    "label":"First Name",
                    "alignment":"left",
                    "value":"Charlie"
                },
                {
                    "displayType":"text",
                    "label":"Last Name",
                    "alignment":"left",
                    "value":"Chase"
                }
            ]
        }
    ],
    "forms":[
        {
            "title":"View details Aaron Adams",
            "fields":[
                {
                    "displayType":"text",
                    "label":"Title",
                    "alignment":"left",
                    "value":"Demo Builder"
                },
                {
                    "displayType":"text",
                    "label":"Phone",
                    "alignment":"left",
                    "value":"1234567890"
                },
                {
                    "linkLabel":"Open Link",
                    "displayType":"link",
                    "label":"Contact",
                    "alignment":"left",
                    "value":"https://www.example.com/in/Aaron-adams-4862572"
                },
                {
                    "displayType":"text",
                    "label":"Bio",
                    "alignment":"left"
                }
            ]
        },
        {
            "title":"View details Bob Brown",
            "fields":[
                {
                    "displayType":"text",
                    "label":"Title",
                    "alignment":"left",
                    "value":"Multi-lingual Expert"
                },
                {
                    "displayType":"text",
                    "label":"Phone",
                    "alignment":"left",
                    "value":"1234567890"
                },
                {
                    "linkLabel":"Open Link",
                    "displayType":"link",
                    "label":"Contact",
                    "alignment":"left",
                    "value":"https://www.example.com/in/Bobbrown"
                },
                {
                    "displayType":"text",
                    "label":"Bio",
                    "alignment":"left",
                    "value":"Bob is a member of the cloud architects team which is specialized in enterprise mobility and cloud development. Bob has been directly involved with Oracle middleware since 2005 during which he held different roles in managing highly specialized teams."
                }
            ]
        },
        {
            "title":"View details Charlie Chase",
            "fields":[
                {
                    "displayType":"text",
                    "label":"Title",
                    "alignment":"left",
                    "value":"Flow Builder Fanatic"
                },
                {
                    "displayType":"text",
                    "label":"Phone",
                    "alignment":"left",
                    "value":"1234567890"
                },
                {
                    "linkLabel":"Open Link",
                    "displayType":"link",
                    "label":"Contact",
                    "alignment":"left",
                    "value":"https://www.example.com/in/Charlie-chase-97a418"
                },
                {
                    "displayType":"text",
                    "label":"Bio",
                    "alignment":"left",
                    "value":"Charlie is a member of the enterprise mobility team. Charlie has 20+ years experience with custom development. Charlie is an expert on mobile cloud services and development tools. He is the creator of productivity tools. His latest passion is building chatbots with a minimum amount of custom code."
                }
            ]
        }
    ],
    "formColumns":2,
    "paginationInfo":{
        "currentRangeSize":3,
        "rangeStart":0,
        "nextRangeSize":2,
        "hasPrevious":false,
        "hasNext":true,
        "totalCount":5,
        "rangeSize":3,
        "status":"Showing 1-3 of 5 items"
    },
    "actions":[
        {
            "postback":{
                "variables":{

                },
                "action":"system.showMore"
            },
            "label":"Show More",
            "type":"postback"
        }
    ],
    "footerText":"Tap on a row to see personal details"
}

Skill Raw Message

Used when a component creates the channel-specific payload itself.

Name	Description	Type	Required?
`type`	The message type	`"raw"`	Yes
`payload`	The channel-specific payload	A JSON object	Yes
`channelExtensions`	The channel-specific extension properties associated with the message	A JSON object	No

Oracle Android Channel Extensions

For Oracle Android channels, you can extend the functionality of Common Response components with capabilities that are specific to the Oracle Android SDK.

You access the extensions by using the channelCustomProperties element in Common Response components and setting the appropriate properties. The code has the following format:

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

You can apply channelCustomProperties in the component's metadata at the level of globalActions, responseItems, and elements of responseItems, depending on the given property.

Here are the available custom properties for Oracle Android 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 information on using channelCustomProperties, see Channel-Specific Extensions.