Oracle Cloud Infrastructure Documentation

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 29 (Android 10. "Q"). API Level 26 (Android Oreo) 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.

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 backend server generates these tokens using the Secret Key generated from the Oracle Android channel when a user authenticates with the Android app. These tokens are then sent on every HTTP request, thus allowing the server to authenticate the user. The information contained within the token is signed by a private key which is owned by the server. When the server gets the token back from the client, it compares the signature sent by the client with the one that it will generate with its private key. The token is valid when the two signatures are identical. When the client needs to establish a WebSocket connection with the chat server, it first requests a JWT token from the backend server and then adds the token to the Authorization header in its call to the chat server.
The JWT Token has the following claims: channelId, 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 decoded header looks something like this:
{

 "alg": "HS256",

 "typ": "JWT"

}
An example of the decoded 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:
  1. Choose Development, then Channels from the menu.
  2. Choose Users.
  3. Click Add Channel and then Oracle Android as the channel type.
  4. 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 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.
  5. Route the channel to your skill or digital assistant.
  6. Switch Channel Enabled to On.

Add the Oracle Android Client SDK to the Project

To add the SDK:
  1. Download the ODA Client SDK for Android and extract it to your local system.
  2. In Android Studio, select your project's App directory and then click File > New > New Module.
  3. Choose Import JAR/.AAR Package and then click Next.
  4. Navigate to, and select, com.oracle.bots.client.sdk.android.core-20.2.1.aar. Click Finish.
  5. Repeat these steps to import com.oracle.bots.client.sdk.android.ui-20.2.1.aar.
    Note

    You don't need to import this package if you're using the SDK in headless mode.
  6. 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-20.2.1', ':com.oracle.bots.client.sdk.android.ui-20.2.1'
    rootProject.name = 'ODASDKSample'
  7. 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.ui-20.2.1')
      implementation project(':com.oracle.bots.client.sdk.android.core-20.2.1')
       
      // Core dependencies
      implementation 'androidx.room:room-runtime:2.2.3'
      implementation 'io.socket:socket.io-client:0.8.3'
       
      //UI dependencies
      implementation 'androidx.appcompat:appcompat:1.1.0'
      implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
      implementation 'com.google.android.material:material:1.0.0'
      implementation 'com.intuit.sdp:sdp-android:1.0.6'
      implementation 'com.squareup.picasso:picasso:2.5.0'
      implementation 'com.google.android.gms:play-services-location:17.0.0'

    For example:

    apply plugin: 'com.android.application'
     
    android {
        compileSdkVersion 29
        buildToolsVersion "29.0.0"
        defaultConfig {
            applicationId "com.example.odasdksample"
            minSdkVersion 26
            targetSdkVersion 29
            versionCode 2
            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 library dependencies
        implementation project(':com.oracle.bots.client.sdk.android.ui-20.2.1')
        implementation project(':com.oracle.bots.client.sdk.android.core-20.2.1')
     
        // Core dependencies
        implementation 'androidx.room:room-runtime:2.2.3'
        implementation 'io.socket:socket.io-client:0.8.3'
     
        // UI dependencies
        implementation 'androidx.appcompat:appcompat:1.1.0'
        implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
        implementation 'com.google.android.material:material:1.0.0'
        implementation 'com.intuit.sdp:sdp-android:1.0.6'
        implementation 'com.squareup.picasso:picasso:2.5.0'
        implementation 'com.google.android.gms:play-services-location:17.0.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.
public class YourApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        try {
                BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<Server URI>, false, getApplicationContext()) // Feature flag settings to initialize the sdk library
                    .channelId(<CHANNEL_ID>)
                    .userId(<USER_ID>)
                    .build();
 
 
                Bots.init(this, botsConfiguration, new BotsCallBack() {  // Initialize the library
                    @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:
public class YourApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        try {
                BotsConfiguration botsConfiguration = new BotsConfiguration.BotsConfigurationBuilder(<Server URI>, true, getApplicationContext()) // Feature flag settings to initialize the sdk library
                    .authTokenProvider(new AuthTokenProvider())
                    .build();
 
 
                Bots.init(this, botsConfiguration, new BotsCallBack() {  // Initialize the library
                    @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
        }
    }
 
    /**
     * Generates and returns new JWT token
    */
    private class AuthTokenProvider implements AuthenticationTokenProvider {
        @Override
        public String getAuthToken() {
            // Generate a new JWT Token and return
        }
    }
}
Show Conversation Activity:
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
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. No all
enableAttachment Enables attachment sharing in the chat view. No true
enableClearMessage Enables the clear message button in the header of the chat view. No false
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
enableSpeechRecognition Enables the speech recognition service to convert user voice to text messages. No false
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
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
notificationCustomizer An instance of the NotificationCustomizer class which is used to customize notifications received from SDK. No N/A
enableTimestamp Enables the timestamp for messages. No true
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
googleMapsApiKey The Google Maps API key that’s used to display a location preview image for Location messages. No N/A
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
messageModifierDelegate An instance of type MessageModifierDelegate which is used to receive callbacks before certain events in the conversation. 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 a person avatar icon beside the user messages. No false
showTypingIndicator Enables the display of the value associated with the odaas_bot_status_responding string resource on the chat view header when waiting for skill's response. No true
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
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 20
youtubeApiKey Supports the streaming of YouTube videos by setting the YouTube API key. No N/A

Custom Colors

The following colors can be modified to provide a custom look for the chat view. You can configure colors by defining name attributes for the <color> elements in the res/values/colors.xml file (located in the project's app resources) with the following keys. For example, the following snippet demonstrates how you can modify the color that's used for the background of the skill's message (odaas_primary) and the text color on 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>
Key Description Default Value
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. #1976D2
odaas_primary_status_bar The color that's used in the status bar. #1976D2
odaas_primary_variant_light The light variant of the primary color that's used in the background for the skill's attachment messages. #63A4FF
odaas_primary_variant_dark The dark variant of primary color that's used in app bar and in notifications. #01579B
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. #FFFFFF
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_secondary_variant_dark The dark variant of the secondary color that's used for the background of user attachment messages. #CCCCCC
odaas_background The background color for the view. #E3F2FD
odaas_error The text color that's used in error messages. #EF5350
odaas_on_primary The text color that's used with the odaas_primary color @android:color/white
odaas_on_primary_variant_light The text color used with the odaas_primary_variant_light color. @android:color/black
odaas_on_primary_variant_dark The text color used with the odaas_primary_variant_dark color. @android:color/white
odaas_on_secondary The text color used with the odaas_secondary color. @android:color/black
odaas_on_secondary_variant_light The text color used with the odaas_secondary_variant_light color. @android:color/black
odaas_on_background The text color used with the odaas_background color. #777777

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 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. Ask
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. Responding...
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_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. Go Back
odaas_content_desc_button_cancel The tooltip that appears when a long press gesture has been detected on the cancel button of the speech recognition dialog. Also, the content description for the cancel 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 Messages
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_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. Unmute 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. Mute Notification Sound
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 Audio Response
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 Audio Response
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_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_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_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_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_dialog_text_clear_messages The text displayed within a popup that prompts the user for confirmation before clearing the messages. Clear messages?
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_file_uploading_in_progress The text displayed within the popup while uploading a user's attachment to the Oracle Chat Server. Uploading file to server.....
odaas_hint_edit_text_user_message The placeholder text that appears in the user input field. Type a message
odaas_no_messages_to_clear The message displayed when there are no messages to clear. No messages to clear
odaas_notification_intent The activity to open, when tapped by the user, on notifications received from the SDK. oracle.cloud.bots.mobile.ui.ConversationActivity
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_speech_to_text_dialog_placeholder The placeholder text displayed on the speech recognition popup before the user starts speaking. Listening.....
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_notification_app_icon The app icon displayed in the status bar and on notifications received from SDK library.
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_person_avatar The avatar icon for user messages.

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

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-20.1.1.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, a message received from skill and attachment upload status events, a class can implement the EventListener interface which then implements the following:
  • 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 for more details about the ConnectionStatus enum.
  • 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 for more details about the Message class.
  • 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 onAttachmentComplete(String utterance) {
        // 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());
Speech Recognition

Setting the enableSpeechRecognition feature flag to true enables the microphone button to display in place of the send button whenever the user input field is empty.

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(final 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(final 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.

void onPartialResult(final 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(final int code, final 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.
public class BotsSpeechListener implements IBotsSpeechListener {
    @Override
    public void onError(final String error) {
            // Handle errors
    }
 
    @Override
    public void onSuccess(final String utterance) {
        // 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
    }
}
 
 
Bots.startRecording(new BotsSpeechListener()); // Start voice recording
 
if (Bots.isRecording()) {
    Bots.stopRecording(); // Stop voice recording
}
Speech Synthesis

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.

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?");
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();
    }
}
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 MessagePayload beforeSend(MessagePayload messagePayload) {
        // Handle before send delegate here
    }

    @Override
    public MessagePayload beforeDisplay(MessagePayload messagePayload) {
        // Handle before display delegate here
    }

    @Override
    public MessagePayload beforeNotification(MessagePayload messagePayload) {
        // Handle before notification delegate here
    }
}
public MessagePayload beforeDisplay(MessagePayload messagePayload)

The public MessagePayload beforeDisplay(MessagePayload messagePayload) 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 MessagePayload beforeSend(MessagePayload messagePayload)

The public MessagePayload beforeSend(MessagePayload messagePayload) 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 MessagePayload beforeNotification(MessagePayload messagePayload)

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

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
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
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
}
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.
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
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"
}
Bot Message

Represents the message sent from the skill to the user.

Bot 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
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"
                }
            }
        ]
    },
    "userId": "guest"
}
Bot 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
Bot 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
{
    "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"
}
Bot 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