Android SDK

The Android SDK is a native Kotlin library that embeds PolyAI’s messaging agent directly inside your Android app. It’s headless by design — you own the UI, PolyAI provides the AI layer underneath. Your app connects to the same agent logic used across voice, webchat, and other channels.

How it works

The SDK handles authentication, session management, WebSocket connections, and reconnection logic. Your app sends and receives messages through the SDK and renders them however you choose — in Jetpack Compose or Android Views.

Installation

The SDK is published to Maven Central as ai.poly:messaging. Ensure mavenCentral() is in your repositories (it’s there by default in new Android projects).

// build.gradle.kts
dependencies {
    implementation("ai.poly:messaging:0.8.0")
}

Requirements

No permissions to declare — the SDK’s manifest merges INTERNET and ACCESS_NETWORK_STATE into your app automatically. R8/minify works without extra configuration.

Authentication setup

The Android SDK authenticates using a connector token and your app’s package name.

Quick start

Initialize the SDK once in Application.onCreate(), then create a ChatSession and render messages.

Initialize once

// HelloApplication.kt
import ai.poly.messaging.Configuration
import ai.poly.messaging.PolyMessaging
import android.app.Application
class HelloApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        PolyMessaging.initialize(
            this,
            Configuration(apiKey = "YOUR_API_KEY"),
        )
    }
}

Register it in your manifest with android:name=".HelloApplication". No network happens at init — the work starts when you call chat().

Build the chat UI

// MainActivity.kt
import ai.poly.messaging.ChatMessage
import ai.poly.messaging.ChatSession
import ai.poly.messaging.PolyMessaging
import androidx.compose.foundation.layout.*
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import kotlinx.coroutines.launch
@Composable
fun ChatScreen() {
    val session: ChatSession = remember { PolyMessaging.chat() }
    val messages by session.messages.collectAsStateWithLifecycle()
    val scope = rememberCoroutineScope()
    var input by remember { mutableStateOf("") }
    Column(Modifier.fillMaxSize().imePadding()) {
        LazyColumn(Modifier.weight(1f)) {
            items(messages, key = { it.id }) { message ->
                val mine = message is ChatMessage.User
                Box(Modifier.fillMaxWidth().padding(vertical = 4.dp, horizontal = 8.dp)) {
                    Text(
                        message.text ?: "",
                        Modifier.align(if (mine) Alignment.CenterEnd else Alignment.CenterStart),
                    )
                }
            }
        }
        Row(Modifier.padding(8.dp)) {
            TextField(value = input, onValueChange = { input = it }, modifier = Modifier.weight(1f))
            Button(onClick = {
                val body = input.trim()
                if (body.isNotEmpty()) {
                    input = ""
                    scope.launch { runCatching { session.send(body) } }
                }
            }) { Text("Send") }
        }
    }
}

Key features

Session persistence

Sessions persist across app launches. If the user leaves and returns, the SDK reconnects to the existing session and replays the conversation history automatically. Use PolyMessaging.chat() to resume or PolyMessaging.start() to always start fresh.

val session = if (PolyMessaging.hasResumableSession()) {
    PolyMessaging.chat()    // resume the previous conversation
} else {
    PolyMessaging.start()   // start a new one
}

Streaming responses

Streaming is on by default — agent replies grow token-by-token. The SDK reassembles chunks and updates session.messages automatically. To switch to complete-message bubbles, set streamingEnabled = false on the Configuration.

PolyMessaging.initialize(
    this,
    Configuration(apiKey = "YOUR_API_KEY", streamingEnabled = false),
)

Handoff to live agents

The full handoff flow is supported. When the PolyAI agent triggers a handoff, the SDK delivers the same handoff events via ChatMessage.System messages with typed SystemEvent cases (HandoffStarted, QueueStatus, LiveAgentJoined, etc.). Live agent messages arrive as ChatMessage.Agent with agentKind == AgentKind.LIVE.

Response suggestions

Agent messages can include suggestions — pre-written reply options. Render these as tappable chips in your UI. When the user taps one, call clearSuggestions(messageId) then send(suggestion.messageText).

Attachments

Agent messages may include rich content via the attachments field — images (AttachmentContentType.IMAGE), link cards (AttachmentContentType.URL), and call-to-action phone buttons (callActions).

Delivery tracking

User messages appear immediately as Delivery.PENDING, then settle to SENT or FAILED. The SDK retries automatically (every 3s, up to 3 times). On FAILED, call removeMessage(draftId) then re-send.

Connection & reconnect

The SDK reconnects automatically with exponential backoff and jitter. Observe session.connection to show a reconnect banner:

// StateFlow<ConnectionStatus> — Connecting / Open / Reconnecting(attempt) / Failed(reason)
session.connection.collect { status ->
    showBanner = status is ConnectionStatus.Reconnecting
}

When the reconnect budget is exhausted (ConnectionStatus.Failed), recover with session.client.startNewSession().

Configuration reference

Environments

ChatSession reference

State (read-only StateFlow properties)

Methods

Platform values

When the SDK creates a session, it sets platform to android automatically. This is visible in Agent Studio analytics and can be used in your agent logic to tailor behavior for mobile users.

Limitations

Example apps

The SDK ships with a 7-rung example ladder, mirrored across Jetpack Compose and Android Views:

Browse the examples on GitHub.

Multichannel

The Android SDK connects to the same agent project as your voice and webchat channels. Agent behavior, knowledge, and flows are shared — only channel-specific settings (greetings, formatting) differ. See multichannel agents for how to tailor behavior per channel.

In your agent’s start function, detect the mobile channel using conv.channel_type:

def start(conv):
    if conv.channel_type == "android":
        conv.state.greet_message = "Hi! How can I help you today?"
    elif conv.channel_type.startswith("webchat"):
        conv.state.greet_message = "Hi there! 👋 How can I help?"

Related pages