Integration Guide

Add VIH Messenger to your app

Drop the VIH Messenger SDK into your Android or iOS app to give users authenticated, bidirectional chat with enterprises on your channel — installed with one dependency and launched with a single call.

On this page

Overview Requirements What you'll need Android integration iOS integration Theming & dark mode Support

🧭 Overview

The SDK ships the full messaging experience — sign-in, the list of enterprises on your channel, and real-time two-way chat — as a self-contained module. You supply two things from the VIH team (a channel hashcode and an API base URL), wire one entry point, and the SDK renders and manages the rest.

Android and iOS use the same hashcode for a given channel, so a user is reachable identically on both platforms.

📋 Requirements

Android

Min SDK: 24 (Android 7.0)
Target SDK: 35
Gradle: 7+ (AGP 8+)
Language: Kotlin / Java
Distribution: Maven (AAR)

iOS

Deployment: iOS 15.0+
Xcode: 15+
Language: Swift 5.9+
UI: UIKit host
Distribution: Swift Package

🔑 What you'll need

Before you integrate, get these from the VIH team for your channel:

Channel hashcode — a per-tenant identifier (e.g. 046c8dd…07e43) that scopes the app to your channel. Identical on Android and iOS.
API base URL — the backend host for your environment (staging or production).
Firebase config — google-services.json (Android) and GoogleService-Info.plist (iOS) for push notifications, provided out-of-band.

💡

Version numbers below are examples. Always use the exact SDK version and package URL the VIH team gives you, and pin to it.

Android Integration

Four steps: point Gradle at the repositories, add the dependency, declare permissions, then launch the SDK from your app.

🛠️ Configure repositories

In your root settings.gradle.kts, make sure both blocks include Google, Maven Central, the Gradle Plugin Portal, and JitPack.

kotlinsettings.gradle.kts

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven { url = uri("https://jitpack.io") }
    }
}
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

📦 Add the dependency

Add the SDK to your module-level build.gradle. Use the production coordinates for release builds:

groovyapp/build.gradle

dependencies {
    // Production
    implementation "io.github.vihmessenger:vih-sdk:1.0.9"
}

Kotlin DSL:

kotlinapp/build.gradle.kts

dependencies {
    implementation("io.github.vihmessenger:vih-sdk:1.0.9")
}

For testing against staging, swap in the staging artifact instead:

groovyapp/build.gradle

// Staging
implementation "io.github.vihmessenger:vih-sdk-staging:1.0.0"

🔄

Click Sync Now in Android Studio after editing Gradle files. The first sync fetches Firebase and other transitive dependencies and can take a minute.

🔐 Declare permissions

The SDK's own manifest already merges what it needs. If your app manifest is strict, these are the permissions the SDK uses:

xmlAndroidManifest.xml

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

✅

The SDK does not read phone state, phone numbers, or call logs — no READ_PHONE_STATE / READ_CALL_LOG is requested, so it clears Google Play's sensitive-permission review on those.

🚀 Launch the SDK

Start the messaging flow with FloatingButtonView.startSdk(), passing the user's phone number and your channel hashcode. Call it from any click listener:

kotlinMainActivity.kt

import com.vihmessenger.vihchatbot.utils.FloatingButtonView

launchButton.setOnClickListener {
    FloatingButtonView.startSdk(
        context  = this,
        phone    = "919876543210",
        hashcode = "your-channel-hashcode"
    )
}

Optional parameters let you pre-fill the signed-in user's identity so they skip straight into chat:

kotlinMainActivity.kt

FloatingButtonView.startSdk(
    context        = this,
    phone          = "919876543210",
    hashcode       = "your-channel-hashcode",
    name           = "Priya Sharma",           // optional
    userProfileUrl = "https://…/avatar.jpg"     // optional
)

Optional: a persistent floating button

To show an always-on chat launcher, drop FloatingButtonView into any layout and set your hashcode via app:extraValue. Tapping it opens the SDK.

xmlactivity_main.xml

<com.vihmessenger.vihchatbot.utils.FloatingButtonView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_gravity="bottom|end"
    app:extraValue="your-channel-hashcode" />

iOS Integration

The SDK ships as a Swift Package. Add it, wire Firebase for push, configure once at launch, then present the SDK's UI.

📦 Add the Swift Package

In Xcode: File ▸ Add Package Dependencies…, paste the package URL, set the rule to Up to Next Major from 1.0.0, and add the VihChatBotSDK product to your app target.

textPackage URL

https://github.com/vihmessenger/vih-sdk-ios.git

Or, if your app is itself a Swift Package:

swiftPackage.swift

dependencies: [
    .package(
        url: "https://github.com/vihmessenger/vih-sdk-ios.git",
        from: "1.0.0"
    ),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "VihChatBotSDK", package: "vih-sdk-ios"),
        ]
    ),
]

⏳

The first package resolve pulls in the Firebase iOS SDK and can take several minutes to download and cache. Subsequent builds are fast.

🔥 Add Firebase (push)

Add your GoogleService-Info.plist to the app bundle and configure Firebase before the SDK. Enable the Push Notifications and Background Modes ▸ Remote notifications capabilities on your target.

⚙️ Configure the SDK

Configure the SDK once at launch with a VihSDKConfig — before presenting any SDK screen.

swiftAppDelegate.swift

import VihChatBotSDK

VihChatBotSDK.shared.configure(
    VihSDKConfig(
        apiBaseURL: URL(string: "https://api.platform.vihresearchlabs.ai/")!,
        hashcode:   "your-channel-hashcode",
        sdkVersion: "1.0.0",
        isDebug:    true
    )
)

Fields: apiBaseURL and hashcode are required; bugfenderKey and certificatePins are optional. Use the same hashcode as Android.

🚀 Launch the SDK

Configure Firebase and the SDK in didFinishLaunchingWithOptions, then set the SDK's splash screen as your root — it checks for a stored session and routes to sign-in or chat.

swiftAppDelegate.swift

import UIKit
import VihChatBotSDK
import FirebaseCore

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?

    func application(_ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions:
            [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {

        FirebaseApp.configure()                     // 1. push

        VihChatBotSDK.shared.configure(             // 2. SDK
            VihSDKConfig(
                apiBaseURL: URL(string: "https://api.platform.vihresearchlabs.ai/")!,
                hashcode:   "your-channel-hashcode",
                sdkVersion: "1.0.0",
                isDebug:    false
            )
        )

        // 3. present the SDK's splash as root
        let window = UIWindow(frame: UIScreen.main.bounds)
        let nav = UINavigationController(rootViewController: SplashViewController())
        nav.isNavigationBarHidden = true
        window.rootViewController = nav
        window.makeKeyAndVisible()
        self.window = window
        return true
    }
}

✅

That's it — build and run (⌘R). SplashViewController loads the saved theme and routes the user into the correct flow automatically.

🌗 Theming & dark mode

The SDK automatically follows the device's system Light/Dark setting — screen backgrounds and body text adapt for legibility. Your channel's brand / accent colors (primary color, headers, highlights from the channel config) are preserved in both modes; only backgrounds and text flip. No integration work is required — it just works.

Android

Built on a DayNight theme that follows the system. Nothing to enable.

To pin the SDK to one appearance, force it from your host app:

kotlin

AppCompatDelegate.setDefaultNightMode(
    AppCompatDelegate.MODE_NIGHT_NO   // or MODE_NIGHT_YES
)

iOS

Uses UIKit semantic colors, which adapt automatically. Nothing to enable.

To pin the SDK to one appearance, set it on your window:

swift

window.overrideUserInterfaceStyle = .light  // or .dark

💡

If your host app already forces a night mode (setDefaultNightMode / overrideUserInterfaceStyle), that setting wins and the SDK follows it — so the SDK matches the rest of your app.

📚 Support

Stuck on integration, need your channel hashcode, or want the latest SDK version? Reach the VIH team at developers@vihmessenger.com. Include your platform, SDK version, and any Gradle/Xcode error output so we can help fast.