Android Chatbot SDK

Installation#

Gradle#

To integrate YMChat into your Android project using gradle, specify the following configurations in App level build.gradle file

repositories {
jcenter()
// Add these two lines
maven { url "https://jitpack.io" }
maven { url "https://oss.sonatype.org/content/repositories/snapshots/" }
}
...
...
...
dependencies {
...
...
implementation 'com.github.yellowmessenger:YMChatbot-Android:1.6.+
}

Note: By puting + at the end, you need not to worry about updating and releaseing your app for every patch we are making in SDK. Still, if you want to use exact and latest version please visit the github repository mentioned https://github.com/yellowmessenger/YMChatbot-Android/releases

File provider#

Note: Only for version v1.4.0 & above

Add following key in your strings.xml file, this will override default file provider used by SDK.

Overriding the file provider path will avoid conflict with other app using YM CHATBOT SDK. You can use your application id and suffix it with ".fileprovider" Example - applicationId : "com.abc.xyz" then application_id_for_provider = com.abc.xyz.fileprovider

<string name="application_id_for_provider">your.application.id.fileprovider</string>

Basic Usage#

Import the YMChat library in your Activity.

import com.yellowmessenger.ymchat.YMChat;
import com.yellowmessenger.ymchat.YMConfig;

After the library is imported the basic bot can be presented with few lines as below

Example onCreate method of the Activity:

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Dummy bot id. (Purrs a lot)
String botID = "x1587041004122";
//Get YMChat instance
YMChat ymChat = YMChat.getInstance();
ymChat.config = new YMConfig(botId);
setContentView(R.layout.activity_main);
FloatingActionButton fab = findViewById(R.id.fab);
fab.setOnClickListener(view -> {
//Starting the bot activity
try {
ymChat.startChatbot(this);
} catch (Exception e) {
//Catch and handle the exception
e.printStackTrace();
}
});
}

YMConfig#

YMConfig can be used to set the bot id and other bot related settings. It is recommended to set all appropriate config before starting the bot

Initialize YMConfig#

YMConfig requires botID to initialize. All other settings are optional.

ymChat.config = new YMConfig("<BOT-ID>");

YM AuthenticationToken#

ymAuthenticationToken is used to associate an identity of the user with the chat bot.

Whenever chatbot is launched with ymAuthenticationToken it will load the previous chats associated with this user since inception.

ymChat.config.ymAuthenticationToken = "your-token"

Note: History will load only when Show history flag is enabled in the channel settings

Push Notifications#

YMChat supports firebase notifications. Assign your FCM token to deviceToken

ymChat.config.deviceToken = "your-firebase-device-token"

Note: Firebase service account key is required to send notifications. You can share the service account key with us. More info here

Payload#

Additional information can be passed in the form of key value pair from app to bot using payload.

HashMap<String, Object> payloadData = new HashMap<>();
//Setting Payload Data
payloadData.put("some-key", "some-value");
ymChat.config.payload = payloadData;

Payload can be used to pass information from host app to bot. The payload dictionary should be JSON compatible else an error will be thrown

For passing data from bot to app refer bot Bot Events

payload security

Payload is securely passed in HTTPS post request to protect the information passed in it

On Premise deployments#

Your on-prem deployment URL can be set to customBaseUrl

ymChat.config.customBaseUrl = "https://yourcustomurl.com";

V2 bot#

You can enable V2 bot by setting the version in config. Default value is 1

ymChat.config.version = 2;

Speech to Text#

Speech to text can be enabled by setting the enableSpeech flag present in config. Default value is false

ymChat.config.enableSpeech = true

Colors#

Status bar#

Status bar color can be set on statusBarColor color variable

ymChat.config.statusBarColor = R.color.red

Close button#

Close button color can be set on closeButtonColor

ymChat.config.closeButtonColor = R.color.white

Starting the bot#

Once the config is set, chat bot can be presented by calling startChatbot() and passing your Activity context as an argument

ymChat.startChatbot(this);

Bot Events#

Bot events are used to pass information from bot to app. Events from bot can be handled using event Listeners. Simply define the onSuccess method of onEventFromBot listener.

ymChat.onEventFromBot(botEvent -> {
switch (botEvent.getCode()) {
case "event-name": break;
}
});

Bot close event#

Bot close event is separately sent and it can be handled by listening to onBotClose event as mentioned below. To programatically close bot use ymChat.closeBot() method

ymChat.onBotClose(() -> {
Log.d("Example App", "Bot Was closed");
});

Close bot#

Bot can be programatically closed using closeBot() function

ymChat.closeBot();

Unlink Device Token#

If you want to stop receiving push notifications you can unlink the device token. Device token typically is unlinked when the user logs out of the app.

try {
YMChat ymChat = YMChat.getInstance();
ymChat.unlinkDeviceToken(botId, apiKey, deviceToken, new YellowCallback() {
@Override
public void success() {
Toast.makeText(MainActivity.this, "Token unlinked", Toast.LENGTH_SHORT).show();
}
@Override
public void failure(String message) {
Toast.makeText(MainActivity.this, message, Toast.LENGTH_SHORT).show();
}
});
} catch (Exception e) {
//Catch and handle the exception
e.printStackTrace();
}

Note: API key can be found in account settings under Access keys section after you login.

Dependencies#

Following dependencies are used in chat bot SDK

implementation 'androidx.appcompat:appcompat:1.3.0'
implementation 'androidx.legacy:legacy-support-v4:1.0.0'
implementation 'com.google.android.material:material:1.3.0'
implementation 'com.squareup.okhttp3:okhttp:4.7.2'
implementation 'com.google.code.gson:gson:2.8.6'
implementation 'androidx.multidex:multidex:2.0.1'
testImplementation 'junit:junit:4.13.2'
androidTestImplementation 'androidx.test.ext:junit:1.1.2'
androidTestImplementation 'androidx.test.espresso:espresso-core:3.3.0'

Permissions#

We are declaring and asking for following permission in our manifest file

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />

All permissions will be asked at run time except INTERNET. For attachment (picking file/images from phone storage)

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

For voice input

<uses-permission android:name="android.permission.RECORD_AUDIO" />

Important#

If facing problem in release build, add the following configuration in the app's proguard-rules.pro file.

-keep public class com.yellowmessenger.ymchat.** {
*;
}

Demo App#

A demo has been created to better understand the integration of SDK in Android app https://github.com/yellowmessenger/YmChatBot-Android-DemoApp