Chat SDKs for iOS and Android

Plans and permissions:

• Add-on: AI agents, billed separately
• Find your company ID and JWT secret: Admin, Manager, or Team Lead role, or a custom role with Chat agent settings set to Can edit chat agent settings or Can view chat agent settings

Use the Assembled Chat SDKs to add the chat agent to your iOS and Android apps, so customers get in-app support from the same chat agent as on your website. The SDKs handle the chat interface for you, and let you decide when the chat opens and who the user is.

This article is for mobile developers. For websites, see Chat widget installation.

What the SDKs include

• Native integration for iOS and Android, with SwiftUI and UIKit on iOS, and Jetpack Compose and Views on Android.
• JWT-based user authentication, and user data for personalized answers.
• Options to change the widget’s appearance.
• Full control over when the chat initializes and opens.

How the SDKs work

• Call initialize() before open().
• If you get build errors on iOS, check that you meet the Swift and Xcode versions under Requirements, and that the package was added to your target.
• On Android, give the view that holds the chat a width and height, and call chat.destroy() in onDestroy() so the chat doesn’t leak memory.
• Turn on the debug option to see log messages while you build.

Find your company ID

Both SDKs need your Assembled company ID.

1. Go to AI support > Chat agent, and open the chat agent.
2. Select the Setup tab.
3. Under Installation, find data-company-id in the script tag. If you have more than one chat agent, data-profile-id is the chat agent’s profile ID.

Set up the iOS SDK

Requirements

• iOS 13.0 or later, as your deployment target
• Swift 5.9 or later
• Xcode 14.0 or later

Install the SDK

1. In Xcode, go to File > Add Package Dependencies.
2. Enter the repository URL: https://github.com/assembledhq/assembled-chat-ios-sdk.git. See assembled-chat-ios-sdk on GitHub.
3. Select the latest version.
4. Select Add Package.

Or add it to your Package.swift:

dependencies: [
    .package(url: "https://github.com/assembledhq/assembled-chat-ios-sdk.git", from: "1.0.0")
]

Then add AssembledChat to your target’s dependencies:

.target(
    name: "YourApp",
    dependencies: ["AssembledChat"]
)

To use CocoaPods instead, add the following to your Podfile, then run pod install:

platform :ios, '13.0'


target 'YourApp' do
  use_frameworks!


  pod 'AssembledChat', '~> 1.0'
end

Add the chat with UIKit

Import, initialize, and open the chat

import UIKit
import AssembledChat


class ViewController: UIViewController {
    private var chat: AssembledChat?


    override func viewDidLoad() {
        super.viewDidLoad()


        let config = AssembledChatConfiguration(
            companyId: "YOUR_COMPANY_ID"
        )


        chat = AssembledChat(configuration: config)
        chat?.delegate = self


        Task {
            try await chat?.initialize()
            chat?.open()
        }
    }
}


extension ViewController: AssembledChatDelegate {
    func assembledChatDidLoad() {
        print("Chat loaded")
    }


    func assembledChatDidOpen() {
        print("Chat opened")
    }


    func assembledChatDidClose() {
        print("Chat closed")
    }


    func assembledChat(didReceiveError error: Error) {
        print("Error: \(error.localizedDescription)")
    }
}

Add the chat with SwiftUI

import SwiftUI
import AssembledChat


struct ContentView: View {
    @StateObject private var chatManager = AssembledChatManager(
        configuration: AssembledChatConfiguration(
            companyId: "YOUR_COMPANY_ID"
        )
    )


    var body: some View {
        VStack {
            Button("Open Chat") {
                Task {
                    if !chatManager.isReady {
                        try await chatManager.initialize()
                    }
                    chatManager.open()
                }
            }


            if chatManager.isOpen {
                AssembledChatSwiftUIView(
                    configuration: chatManager.chatInstance.configuration
                )
            }
        }
    }
}

iOS configuration options

Set up the Android SDK

Requirements

• Android API 21 (Android 5.0) or later
• Target SDK 34
• Kotlin 1.9.20 or later
• Android Studio Arctic Fox or later
• Gradle 7.0 or later

Install the SDK with Gradle

Add the SDK to your app’s build.gradle.kts:

dependencies {
    implementation("io.github.assembledhq:assembledchat:1.0.0")
}

Or, with Groovy, in build.gradle:

dependencies {
    implementation("io.github.assembledhq:assembledchat:1.0.0")
}

The package is on Maven Central at io.github.assembledhq/assembledchat.

Make sure your repositories are set up in settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

Add the chat to your app

Open the chat as a full-screen activity

import com.assembled.chat.models.AssembledChatConfiguration
import com.assembled.chat.ui.AssembledChatActivity


val configuration = AssembledChatConfiguration(
    companyId = "YOUR_COMPANY_ID"
)


val intent = AssembledChatActivity.createIntent(this, configuration)
startActivity(intent)

Embed the chat in a fragment or view

import com.assembled.chat.AssembledChat
import com.assembled.chat.AssembledChatListener
import com.assembled.chat.models.AssembledChatConfiguration


class ChatFragment : Fragment(), AssembledChatListener {
    private lateinit var chat: AssembledChat


    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        val view = inflater.inflate(R.layout.fragment_chat, container, false)
        val chatContainer = view.findViewById<FrameLayout>(R.id.chatContainer)


        val config = AssembledChatConfiguration(
            companyId = "YOUR_COMPANY_ID"
        )


        chat = AssembledChat(config)
        chat.listener = this
        chat.initialize(requireContext())


        chat.getWebView()?.let { webView ->
            chatContainer.addView(webView)
        }


        chat.open()
        return view
    }


    override fun onDestroy() {
        super.onDestroy()
        chat.destroy()
    }


    override fun onChatReady() {
        Log.d("Chat", "Ready")
    }


    override fun onChatOpened() {
        Log.d("Chat", "Opened")
    }


    override fun onChatClosed() {
        Log.d("Chat", "Closed")
    }


    override fun onError(error: ChatError) {
        Log.e("Chat", "Error: $error")
    }
}

Add the chat with Jetpack Compose

import androidx.compose.runtime.Composable
import com.assembled.chat.ui.AssembledChatComposable


@Composable
fun ChatScreen() {
    AssembledChatComposable(
        companyId = "YOUR_COMPANY_ID",
        modifier = Modifier.fillMaxSize(),
        onReady = { Log.d("Chat", "Ready") },
        onOpened = { Log.d("Chat", "Opened") },
        onClosed = { Log.d("Chat", "Closed") },
        onError = { error -> Log.e("Chat", "Error: $error") }
    )
}

Android configuration options

Identify signed-in users

Both SDKs can link chats to your users’ accounts, so the chat agent can personalize its answers. Create a JWT on your server, signed with the JWT secret from the chat agent’s Setup tab, and pass it with the user’s details. To create the secret and the token, see Create a signed token.

User data fields

iOS example

let userData = UserData(
    userId: "user123",
    email: "user@example.com",
    name: "Jane Doe"
)


let config = AssembledChatConfiguration(
    companyId: "YOUR_COMPANY_ID",
    jwtToken: "YOUR_JWT_TOKEN",
    userData: userData
)

Android example

val userData = UserData(
    userId = "user123",
    email = "user@example.com",
    name = "Jane Doe"
)


val config = AssembledChatConfiguration(
    companyId = "YOUR_COMPANY_ID",
    jwtToken = "YOUR_JWT_TOKEN",
    userData = userData
)

If the chat doesn’t load or doesn’t appear in your app, see Is the chat set up in your mobile app?.