A web chat widget can bring customer conversations into a website with one embedded component. Mobile applications need a different integration boundary. Their navigation, visual language, accessibility behavior, lifecycle, and state management already belong to the native application.

That is why we have created two open-source, headless Aamu Livechat client libraries: one for Android and one for iOS. They handle the Livechat protocol and leave the interface to the application that embeds them.

The source is available now:

Headless means the application owns the experience

Neither library contains a chat window, message list, email form, buttons, colors, animations, or other ready-made UI. Instead, the library publishes connection state and typed events. The host application decides how those values should appear.

This makes the clients useful in applications that already have their own design system. A banking app, an internal operations tool, and a consumer mobile product may all want Livechat, but they should not be forced into the same navigation pattern or visual component.

The application can build the experience with Jetpack Compose, Android Views, SwiftUI, UIKit, or its existing presentation architecture. It can show Livechat as a full-screen support view, a sheet, part of an account page, or a flow connected to an existing Help section.

What the libraries handle

The Android and iOS clients implement the same Livechat protocol responsibilities:

  • opening and closing the secure WebSocket connection,

  • serializing outgoing commands and parsing incoming JSON messages,

  • persisting the user and chat session identifiers,

  • sending heartbeats and detecting stale connections,

  • reconnecting after a connection closes,

  • starting, continuing, and ending a chat,

  • publishing agent availability and queue information,

  • handling AI availability and thinking events,

  • restoring message history and correlating message acknowledgements,

  • sending Email fallback messages,

  • sending post-chat feedback, and

  • requesting signed URLs for attachments.

The application remains responsible for user input, rendering, accessibility, file selection, and deciding when the client should connect or disconnect.

One protocol, two native APIs

The two libraries share a platform-independent protocol contract, but each exposes the result in a way that feels natural on its platform.

Android is implemented in Kotlin. Livechat state is exposed as a StateFlow, while messages and other one-time events are exposed through a SharedFlow. Session identifiers can be stored with the included SharedPreferencesSessionStore. The library supports Android API level 23 and newer and is structured as an Android library that can be published as an AAR/Maven artifact.

val client = LivechatClient(
    config = LivechatConfig(host = "your-tenant", pid = "your-widget"),
    sessionStore = SharedPreferencesSessionStore(context)
)

lifecycleScope.launch {
    client.events.collect { event ->
        // Update your application's own state and UI.
    }
}

client.connect()
client.startChat("Hello")

iOS is a Swift Package. It publishes typed events through an event handler and stores session identifiers through the included UserDefaultsSessionStore. It supports iOS 13 and newer and can be integrated as a local package today or through a Git repository dependency.

let configuration = try LivechatConfiguration(
    host: "your-tenant",
    pid: "your-widget"
)

let client = LivechatClient(
    configuration: configuration,
    sessionStore: UserDefaultsSessionStore()
)

client.onEvent = { event in
    // Update your application's own state and UI.
}

client.connect()
try client.startChat(message: "Hello")

Chat and Email use the same session context

Livechat can report that chat is available, that only a human agent is unavailable, or that the connection cannot currently reach the chat service. The host application can use that state to offer the right contact path.

When the WebSocket is available, an Email message can travel through the normal protocol. When it is not, both libraries can use the HTTPS Email fallback endpoint. The SDK reports sending, success, and failure state while the application decides how to ask for a name, email address, and message.

Mobile lifecycle is explicit

A mobile application should not assume that a foreground WebSocket will remain active indefinitely in the background. The intended integration is explicit: connect when the owning application flow becomes active, disconnect when it leaves the foreground, and reconnect when it returns.

The current protocol does not include APNs or Firebase Cloud Messaging push delivery. Background chat notifications would need a separate server-side push contract. Keeping that boundary clear prevents the SDK from promising background behavior the operating system cannot guarantee through a normal WebSocket.

A deliberately small attachment boundary

The libraries can request a signed upload URL, but they do not open a system file picker or provide an upload interface. The application selects the file and decides how progress should be displayed.

Protocol version 1.0 does not include a correlation identifier in the signed URL response, so the clients permit only one pending signed URL request. This limitation is documented rather than hidden. A future protocol version can add a request identifier and safely allow concurrent requests.

Why open source

A customer communication SDK sits inside another team's application. Integrators should be able to inspect how it connects, what it stores, what it sends, how it responds to errors, and what happens when the network disappears.

Both repositories use the Apache License 2.0. The license permits commercial and private use, modification, and distribution, and includes an explicit patent grant. Each repository also includes tests, development instructions, and continuous integration configuration.

The current release stage

These are initial source releases. The Android project already has Maven publication metadata, but it is not yet published to a public Maven repository. The iOS project can be consumed directly as a Swift Package from its Git repository. The APIs may still evolve as the clients are tested in real mobile applications.

Keeping the clients in separate repositories makes that evolution visible. Android and iOS issues, releases, examples, and package metadata can follow their own platform conventions while the wire protocol remains shared.

The bottom line

Aamu Livechat no longer has to be presented only through a web widget. The new Android and iOS libraries provide the protocol layer needed to build a native support experience without importing someone else's user interface.

The SDK owns the connection. The application owns the experience. Chat and Email stay compatible with Aamu Livechat, while each mobile product remains free to feel like itself.