Android SDK

This guide explains how to install and configure WotNot’s Android SDK to embed the native chat widget inside your Android app.

Step 1: Add the SDK Package

1: Add dependency

Add the WotNot SDK and required Android libraries in your app-level build.gradle file:

dependencies {
    // WotNot Chatbot SDK
    implementation 'io.wotnot.android:chatbotsdk:1.0.3'

    // Required Android dependencies
    implementation 'androidx.core:core-ktx:1.13.1'
    implementation 'androidx.appcompat:appcompat:1.7.0'
    implementation 'com.google.android.material:material:1.12.0'
    implementation 'androidx.constraintlayout:constraintlayout:2.2.0'
    implementation 'androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.7'
    implementation 'androidx.lifecycle:lifecycle-livedata-ktx:2.8.7'
    implementation 'androidx.fragment:fragment-ktx:1.8.5'
    implementation 'androidx.activity:activity-ktx:1.9.3'
}

1.2: Sync Gradle

In Android Studio:

• File → Sync Project with Gradle Files

• Or use the toolbar sync button

Step 3: Add required permissions

Add the following permissions to your AndroidManifest.xml:

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

Step 2: SDK Configuration

2.1 Create a WidgetConfig

The SDK requires a WidgetConfig object to initialize the chat widget.

import com.widget.sdk.data.model.WidgetConfig
import com.widget.sdk.utils.VisitorKeyManager

// Initialize VisitorKeyManager first (optional, but recommended)
VisitorKeyManager.initialize(context)

val config = WidgetConfig(
    botId = "YOUR_BOT_ID",                    // Required: Your bot ID
    visitorKey = “VISITOR_KEY”, // Required: Visitor key (auto-generated if not set)
    accountKey = "YOUR_ACCOUNT_KEY",          // Required: Your account key
    accountId = YOUR_ACCOUNT_ID,              // Required: Your account ID (Int)
    
    // Optional Configurations
    isMessageAvatarVisible = true,            // Show/hide message avatars (default: true)
    isHeaderVisible = true,                   // Show/hide headers (default: true)
    conversationKey = null,                   // Optional: Pre-existing conversation key
    dataSessionPayload = null,                // Optional: Additional data payload
    badRequestMessage = "Bad request. Please check your configuration.",
    botNotActiveMessage = "Bot is not active."
)

Where to find these credentials

YOUR_BOT_ID — open the bot you want to embed, and copy the bot_id from the URL.

YOUR_ACCOUNT_ID — goto Settings > Account Settings and copy the account_id from the URL.

YOUR_ACCOUNT_KEY — Goto the bot list screen, open the embed option from context menu and copy the highlighted key.

Visitor key notes

• If you don’t provide a visitorKey, the SDK auto-generates and persists one.

• It’s recommended to provide the unique visitor key, as it helps uniquely identify each visitor and maintain their chats and session history.

---

Step 2: Initialize the SDK

Call wn.initialize() in your Application class or MainActivity.

import com.widget.sdk.wn

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        try {
            val config = WidgetConfig(
                botId = "YOUR_BOT_ID", //String
                visitorKey = "VISITOR_KEY_32_BIT_LONG", //String
                accountKey = "YOUR_ACCOUNT_KEY", //String
                accountId = "YOUR_ACCOUNT_ID" //Number
            )

            wn.initialize(this, config)

        } catch (e: Exception) {
            Log.e("SDK", "Initialization failed: ${e.message}")
        }
    }
}

IMPORTANT

• Always initialize the SDK before launching any chat screen.

• All required fields (botId, visitorKey, accountKey, accountId) must be present.

• The SDK validates config and throws an exception on failure.

---

Step 3: Launching the chat screen

The SDK provides built-in functions to launch chat screens.

All functions optionally support useAnimation = true.

3.1 Conversation list screen

// Without animation
wn.launchConversationList(this)

// With animation (bottom-to-top slide)
wn.launchConversationList(this, useAnimation = true)

3.2 Conversation detail screen without key

// Launch without animation
wn.launchConversationDetailScreenWithoutKey(this)

// Launch with animation
wn.launchConversationDetailScreenWithoutKey(this, useAnimation = true)

3.2 Ending the conversation

// Ends the conversation, so a new conversation can be started
wn.endChat()

Step 4: Theme customization

You can fully customize the look of the chat widget using WidgetTheme.

4.1 Theme options

Property	Setter	Default	Used For
accentPrimary	setAccentPrimary()	#0075ff	Buttons, headers, links
userMessageTextColor	setUserMessageTextColor()	#FFFFFF	User message text & timestamp
accentSecondary	setAccentSecondary()	#d4e3ffff	Secondary accents
gray8	setGray8()	#F2F5F8	Bot message background
botMessageTextColor	setBotMessageTextColor()	#1C1C1E	Bot text & timestamp
failurePrimary	setFailurePrimary()	#FF0000	Error messages
failureSecondary	setFailureSecondary()	#FFEBEE	Error states

4.2 Applying a theme

// After SDK initialization
val customTheme = WidgetTheme.Builder()
    .setAccentPrimary(Color.parseColor("#0075ff"))
    .setBackgroundColor(Color.WHITE)
    .build()

wn.setTheme(customTheme)

Complete integration example

Below is a full working example combining all steps:

import android.os.Bundle
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import com.widget.sdk.wn
import com.widget.sdk.data.model.WidgetConfig
import com.widget.sdk.theme.WidgetTheme
import com.widget.sdk.utils.VisitorKeyManager
import android.graphics.Color
import android.util.Log

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Step 1: Initialize VisitorKeyManager
        VisitorKeyManager.initialize(this)

        // Step 2: Build WidgetConfig
        val config = WidgetConfig(
            botId = "YOUR_BOT_ID",
            visitorKey = VisitorKeyManager.getVisitorKey(),
            accountKey = "YOUR_ACCOUNT_KEY",
            accountId = YOUR_ACCOUNT_ID,
            isMessageAvatarVisible = true,
            isHeaderVisible = true
        )

        // Step 3: Initialize SDK
        try {
            wn.initialize(this, config)
        } catch (e: Exception) {
            Log.e("SDK", "Initialization failed: ${e.message}")
            return
        }

        // Step 4: Apply Theme
        val customTheme = WidgetTheme.Builder()
            .setAccentPrimary(Color.parseColor("#0075ff"))
            .setBackgroundColor(Color.WHITE)
            .setTextPrimaryColor(Color.parseColor("#1C1C1E"))
            .build()

        wn.setTheme(customTheme)

        // Step 5: Setup Launch Buttons
        findViewById<Button>(R.id.btnNewChat).setOnClickListener {
            wn.launchNewConversation(this, useAnimation = true)
        }

        findViewById<Button>(R.id.btnConversationList).setOnClickListener {
            wn.launchConversationList(this, useAnimation = true)
        }
    }
}