# 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`:

```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.

```kotlin
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.

<figure><img src="/files/Q78YxpeIztBCxNw3fVEL" alt=""><figcaption></figcaption></figure>

**YOUR\_ACCOUNT\_ID** — goto Settings > Account Settings and copy the account\_id from the URL.

<figure><img src="/files/QYmHguPuNGq6GFMM6Jqc" alt=""><figcaption></figcaption></figure>

**YOUR\_ACCOUNT\_KEY** — Goto the bot list screen, open the embed option from context menu and copy the highlighted key.

<figure><img src="/files/BSfHkrzXVNL09rRTmoHv" alt=""><figcaption></figcaption></figure>

#### 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.

```kotlin
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}")
        }
    }
}
```

{% hint style="warning" %}

### 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.
  {% endhint %}

***

## 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

```kotlin
// 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

<table><thead><tr><th width="192.69879150390625">Property</th><th width="227.533935546875">Setter</th><th width="99.999267578125">Default</th><th>Used For</th></tr></thead><tbody><tr><td>accentPrimary</td><td>setAccentPrimary()</td><td>#0075ff</td><td>Buttons, headers, links</td></tr><tr><td>userMessageTextColor</td><td>setUserMessageTextColor()</td><td>#FFFFFF</td><td>User message text &#x26; timestamp</td></tr><tr><td>accentSecondary</td><td>setAccentSecondary()</td><td>#d4e3ffff</td><td>Secondary accents</td></tr><tr><td>gray8</td><td>setGray8()</td><td>#F2F5F8</td><td>Bot message background</td></tr><tr><td>botMessageTextColor</td><td>setBotMessageTextColor()</td><td>#1C1C1E</td><td>Bot text &#x26; timestamp</td></tr><tr><td>failurePrimary</td><td>setFailurePrimary()</td><td>#FF0000</td><td>Error messages</td></tr><tr><td>failureSecondary</td><td>setFailureSecondary()</td><td>#FFEBEE</td><td>Error states</td></tr></tbody></table>

### 4.2 Applying a theme

```kotlin
// 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:

```kotlin
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)
        }
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.wotnot.io/deploy/publishing-agents/mobile-app/android-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.