Quick Start Guide

Get a working voice call in your Android app in under 5 minutes.

Before You Begin

Make sure you have:

✅ Android Studio Hedgehog (2023.1.1) or later
✅ minSdk 24 (Android 7.0+)
✅ A Kasookoo publishable key (get one at https://app.kasookoo.com/)
✅ A real Android device or emulator (real device recommended for audio testing)

Step 1: Install the SDK (2 minutes)

Add Maven Repository

In your settings.gradle.kts:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.kasookoo.ai/releases")
        }
    }
}

Add Dependency

In app/build.gradle.kts:

dependencies {
    implementation("com.kasookoo:sdk-android:1.0.0")
    
    // Required dependencies (if not already added)
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
}

Click Sync Now when prompted.

Step 2: Configure Your App (2 minutes)

Add Permissions to AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
    <!-- Network -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
    <!-- Audio -->
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    
    <!-- Calls -->
    <uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    
    <!-- Push notifications -->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    
    <application ...>
        ...
    </application>
</manifest>

Request Runtime Permissions

For Android 6.0+, runtime permissions are required. Request these at app startup:

private val requestPermissions = registerForActivityResult(
    ActivityResultContracts.RequestMultiplePermissions()
) { permissions ->
    permissions.entries.forEach {
        Log.d("Permissions", "${it.key} = ${it.value}")
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    
    val permissionsToRequest = arrayOf(
        Manifest.permission.RECORD_AUDIO,
        Manifest.permission.POST_NOTIFICATIONS  // Android 13+
    )
    
    requestPermissions.launch(permissionsToRequest)
}

Step 3: Initialize the SDK (1 minute)

In your Application class:

import android.app.Application
import com.kasookoo.sdk.KasookooSDK
import com.kasookoo.sdk.KasookooConfig
import com.kasookoo.sdk.Environment
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

class MyApplication : Application() {

    lateinit var sdk: KasookooSDK
        private set

    override fun onCreate() {
        super.onCreate()

        sdk = KasookooSDK(this)

        val config = KasookooConfig(
            publishableKey = "pk_test_YOUR_KEY_HERE",
            organizationId = "your_org_id",
            environment = Environment.SANDBOX  // or PRODUCTION
        )

        CoroutineScope(Dispatchers.Main).launch {
            try {
                sdk.initialize(config)
                Log.d("SDK", "✅ Initialized")
            } catch (e: Exception) {
                Log.e("SDK", "❌ Init failed", e)
            }
        }
    }
}

<application
    android:name=".MyApplication"
    ... >

Step 4: Connect and Identify (1 minute)

In your Activity or ViewModel:

private val sdk by lazy { (application as MyApplication).sdk }

lifecycleScope.launch {
    try {
        // Connect to backend (establishes session)
        sdk.connect()
        
        // Identify the current user
        val profile = CallerProfile(
            name = "Alice Smith",
            email = "[email protected]",
            phoneNumber = "+1234567890",
            type = ParticipantType.CUSTOMER
        )
        sdk.identify(callerProfile = profile)
        
        Log.d("SDK", "✅ Connected and identified")
    } catch (e: Exception) {
        Log.e("SDK", "Setup failed", e)
    }
}

Step 5: Make Your First Call (30 seconds)

val caller = Participant(
    name = "Alice Smith",
    email = "[email protected]",
    phoneNumber = "+1234567890",
    type = ParticipantType.CUSTOMER
)

val callee = Participant(
    name = "Bob Agent",
    email = "[email protected]",
    phoneNumber = "+0987654321",
    type = ParticipantType.AGENT
)

val params = StartCallParams(
    roomName = "room_${UUID.randomUUID()}",
    caller = caller,
    callee = callee
)

lifecycleScope.launch {
    try {
        val call = sdk.call.start(params)
        Log.d("Call", "📞 Call started: ${call.id}")
    } catch (e: Exception) {
        Log.e("Call", "❌ Call failed", e)
    }
}

🎉 You Did It!

You now have a working voice call. Let's verify:

Check the Logs

You should see something like:

✅ SDK Initialized
✅ Session created, TTL: 600s
✅ User identified: [email protected]
📞 Call started: <call-id>
✅ LiveKit: Connecting to room...
✅ Room connected
✅ Microphone enabled

Test on Emulator/Device

The call will initiate even on the emulator — you'll see the call state transition through:

INITIATING → RINGING → CONNECTING → CONNECTED

Note: Real audio testing requires a physical device with proper microphone setup.

Next Steps

Now that you have the basics working, explore more:

Guide	What You'll Learn
Receiving Calls	Handle incoming calls with ConnectionService
Push Notifications	Set up Firebase for incoming call pushes
Messaging	Send and receive messages
Event Handling	Subscribe to SDK events
Error Handling	Gracefully handle failures
Production Checklist	Prepare for Play Store release

Need Help?

📖 Full Documentation: docs.kasookoo.ai
💬 Community: Discord
📧 Support: [email protected]
🎬 Demo App: github.com/kasookoo/android-demo

Common Issues

"SDK not initialized" error

Make sure you call initialize() before any other SDK method.

"Invalid publishable key" error

Double-check the key format: should start with pk_test_ or pk_live_
Verify the key in your Kasookoo Dashboard

Call connects but no audio

Verify RECORD_AUDIO permission granted at runtime
Test on a real device (not emulator)
Check Manifest has MODIFY_AUDIO_SETTINGS

Build fails with "Could not find com.kasookoo:sdk-android"

Verify Maven repository added in settings.gradle.kts
Sync project: File → Sync Project with Gradle Files
Invalidate caches: File → Invalidate Caches & Restart

For more troubleshooting, see Troubleshooting Guide.