ui

The UI module provides a pre-built Jetpack Compose conversation interface for Messaging for In-App. It handles the full messaging experience including pre-chat forms, the chat feed, file attachments, and transcript downloads. Add it to your app with minimal code, then customize branding, components, and behavior as needed.

Getting Started

Create a UIConfiguration with your deployment values, then obtain a UIClient from the factory:

val config = UIConfiguration(
    serviceAPI = "https://myorg.my.salesforce-scrt.com",
    organizationId = "00D000000000001AAA",
    developerName = "My_Deployment",
    conversationId = UUID.randomUUID()
)
val uiClient = UIClient.Factory.create(config)

Alternatively, load configuration from the file downloaded from Salesforce setup:

val config = UIConfiguration(
    configuration = CoreConfiguration.fromFile(context),
    conversationId = UUID.randomUUID()
)

The factory maintains a singleton -- calling create with the same configuration returns the existing instance. When using the same CoreConfiguration in both the UIClientFactory and CoreClientFactory, the UIClient shares the same underlying CoreClient instance. This allows the host app to perform operations on the active client even when the UI is not displayed. Call UIClient.Factory.destroy() when messaging is no longer needed.

Launching the Conversation UI

Activity-based (simplest)

Let the SDK manage a full-screen activity:

uiClient.openConversationActivity(context)

Composable-based (more control)

Embed the messaging UI directly in your Compose navigation graph:

uiClient.MessagingInAppUI(onExit = {
    // Navigate back or finish the activity
})

Bottom sheet (modal)

Present the messaging UI in a ModalBottomSheet:

ModalBottomSheet(
    onDismissRequest = { updateOpenBottomSheet(false) },
    sheetState = sheetState
) {
    Box(Modifier.fillMaxHeight(0.9f)) {
        uiClient.MessagingInAppUI { dismissSheet() }
    }
}

When the bottom sheet is closed, MessagingInAppUI is removed from the composition and stops managing the event stream. To continue receiving events (e.g., push-triggered unread counts), call coreClient.start(lifecycleScope) while the sheet is closed and coreClient.stop() when re-opening. Do not call coreClient.start() while MessagingInAppUI is active — the composable manages the lifecycle automatically.

Customizing the UI

ViewComponents

Override composable slots by assigning a custom ViewComponents implementation. Each slot receives a content lambda you can call to render the default, wrap, or ignore entirely. Available slots: ChatFeedEntry, ChatTopAppBar, ConversationClosed, and MarkdownContent.

Replace the top app bar with a custom header and unread message counter:

uiClient.viewComponents = object : ViewComponents {
    @Composable
    override fun ChatTopAppBar(content: @Composable () -> Unit) {
        val conversation by uiClient.conversationClient(context)
            .conversation.map { it.data }.collectAsStateWithLifecycle(null)

        Row(
            modifier = Modifier.fillMaxWidth().padding(16.dp),
            horizontalArrangement = Arrangement.SpaceBetween
        ) {
            Text("Support Chat", style = MaterialTheme.typography.titleLarge)
            conversation?.unreadMessageCount?.takeIf { it > 0 }?.let { count ->
                Badge { Text("$count") }
            }
        }
    }
}

Start a new conversation when the current one is closed:

uiClient.viewComponents = object : ViewComponents {
    @Composable
    override fun ConversationClosed(content: @Composable () -> Unit) {
        Column(Modifier.fillMaxWidth().padding(16.dp)) {
            Text("This conversation has ended.")
            Button(onClick = {
                UIClient.Factory.destroy()
                val newConfig = UIConfiguration(
                    configuration = coreConfig,
                    conversationId = UUID.randomUUID()
                )
                UIClient.Factory.create(newConfig).openConversationActivity(context)
            }) {
                Text("Start New Conversation")
            }
        }
    }
}

For more examples including voice UI, bottom sheet widgets, and conversation list components, see the sample app.

Entry-type rendering

Control rendering per entry type using when expressions inside ChatFeedEntry:

uiClient.viewComponents = object : ViewComponents {
    @Composable
    override fun ChatFeedEntry(entry: ChatFeedEntry, content: @Composable () -> Unit) {
        when (entry) {
            is ChatFeedEntry.ConversationEntryModel -> {
                when (entry.entryType) {
                    ConversationEntryType.Message -> MyCustomMessage(entry)
                    ConversationEntryType.ParticipantChanged -> { /* hide */ }
                    else -> content()
                }
            }
            else -> content()
        }
    }
}

Important: The render decision applies to all entries of a given type. You cannot selectively replace individual messages while keeping others as defaults within the same type.

For interactive messages (quick replies, list pickers), use ConversationClient.sendReply() to submit the user's selection — not sendMessage().

Navigation within custom components

Access LocalSMINavigation inside a custom ViewComponents composable to conditionally render based on the current screen or navigate programmatically:

@Composable
override fun ChatTopAppBar(content: @Composable () -> Unit) {
    val navigation = LocalSMINavigation.current
    if (navigation.currentRoute?.route?.contains("ChatFeed") == true) {
        // Show custom header only on the chat feed
        MyCustomHeader()
    } else {
        content()
    }
}

Available navigation actions: navigateToChatFeed, navigateToPreChat, navigateToForm, navigateToOptions, navigateToTranscriptViewer, navigateToAttachmentViewer, and navigateBack.

Branding and theming

The SDK supports three levels of UI customization:

1. Color token overrides — Override named color resources in your app's colors.xml to change colors throughout the SDK UI without replacing components.

2. String overrides — Override localized string resources to change text labels.

3. Full component replacement — Use ViewComponents to replace entire composables.

There is no middle ground between color/string overrides and full replacement. You cannot change individual properties (font size, padding, etc.) of the default components.

To override color tokens, define colors in your app's res/values/colors.xml (light mode) and res/values-night/colors.xml (dark mode) with the SDK token names:

<!-- res/values/colors.xml -->
<resources>
    <color name="smi_sent_bubble_background">#FF0070D2</color>
    <color name="smi_received_bubble_background">#FFF3F2F2</color>
    <color name="smi_navigation_background">#FFFFFFFF</color>
    <color name="smi_chat_background">#FFF3F2F2</color>
    <color name="smi_cta_buttons">#FF0070D2</color>
</resources>

Run ./gradlew dokkaGenerate to produce the full branding token reference at build/dokka/html/resources/ui/.

URL Display Mode

Control how tappable URLs are opened via UIConfiguration.urlDisplayMode:

• UrlDisplayMode.InlineBrowser (default) -- Chrome Custom Tabs within your app

• UrlDisplayMode.ExternalBrowser -- device default browser

Pre-Chat Fields

Pre-populate visible pre-chat field values so end users see defaults they can edit:

uiClient.preChatFieldValueProvider = { fields ->
    fields.onEach { field ->
        when (field.name) {
            "FirstName" -> field.userInput = "Jane"
            "Email" -> field.userInput = "jane@example.com"
        }
    }
}

For hidden pre-chat values used in routing (not visible to the user), use CoreClient.registerHiddenPreChatValuesProvider instead. Hidden pre-chat values are used for routing decisions in Salesforce Flows and are not displayed to the agent directly.

Accessing Core APIs

Retrieve the underlying CoreClient or ConversationClient for advanced operations such as registering a user verification provider or sending messages programmatically:

val coreClient = uiClient.coreClient(context)
val conversationClient = uiClient.conversationClient(context)

CoreClient lifecycle

When MessagingInAppUI is active, the SDK manages CoreClient.start() and CoreClient.stop() automatically. When the UI is not active (e.g., bottom sheet closed), the host app must manage the lifecycle manually to maintain the real-time event stream:

LifecycleResumeEffect(Unit) {
    coreClient.start(lifecycleScope)
    onPauseOrDispose { coreClient.stop() }
}

Do not call coreClient.start() while MessagingInAppUI is active — this causes instability.

Conversation Lifecycle

Conversation IDs

Use UUID.randomUUID() to start a new conversation. To resume an existing conversation, pass the same UUID that was used when the conversation was created.

After an app reinstall for unverified users, always generate a new conversation ID. The previous conversation is no longer accessible because the local encrypted database was cleared. Reusing the old ID will result in errors. For verified users (user verification enabled), conversations can be safely resumed across reinstalls because the server can re-associate the user.

Switching deployments

When switching between different Salesforce deployments within the same app, clear the local storage first to avoid data corruption:

UIClient.Factory.destroy()
CoreClient.clearStorage(context, clearAuthorization = true)

Call UIClient.Factory.destroy() before clearStorage to release the active client, then create a new UIClient with the new configuration.

Colors

To customize the color scheme in your app, create a color resource file in your app using the SDK's token names. To learn more, see Customize Colors for Android.

Icons

To customize the icons and images used throughout the SDK, add a drawable asset to your project using the associated keyword. To learn more, see Customize Icons for Android.

Show Icons

Token	Image	Description
smi_action_attach_file		Icon for attaching a file.
smi_action_attach_photo		Icon for attaching a photo.
smi_action_cancel		Icon representing the cancel action.
smi_action_delete		Icon representing the delete action.
smi_action_download		Icon representing the download action.
smi_action_jump_to		Icon representing the jump-to action.
smi_action_mute		null
smi_action_scroll_to_bottom		Icon representing the scroll down action on the overlay badge in the feed.
smi_action_search		Icon representing the message search action.
smi_action_send		null
smi_action_share		Icon representing the share action.
smi_action_take_photo		Icon for taking a photo.
smi_action_unmute		null
smi_add		Icon representing the menu button on the text input.
smi_avatar_agent		Agent avatar shown in the chat feed.
smi_avatar_bot		Default bot avatar shown in the chat feed.
smi_avatar_user		User avatar shown in search results.
smi_chevron_right		Icon representing a link to the preview that can be navigated.
smi_icon_check		Icon representing a confirmed action.
smi_icon_clock		Icon representing the image used for business hours banner.
smi_icon_error		Icon representing an error.
smi_icon_failed		Icon representing an error that occured while sending a message.
smi_icon_file_audio		Icon representing an audio file attachment.
smi_icon_file_csv		Icon representing a CSV file with extension .csv.
smi_icon_file_excel		Icon representing an Excel file with extension .xls or .xlsx.
smi_icon_file_other		Icon representing a generic file attachment.
smi_icon_file_txt		Icon representing a text file with extension .txt.
smi_icon_file_video		Icon representing a video file attachment.
smi_icon_file_word		Icon representing a word file with extension .doc or .docx.
smi_icon_file_xml		Icon representing a XML file with extension .xml.
smi_icon_form		Icon representing the form message shown in the feed.
smi_icon_offline		Icon representing an offline state.
smi_icon_pre_chat_receipt		Icon representing a checklist in the pre-chat receipt.
smi_icon_read		Icon representing a read state.
smi_icon_sending		Icon representing a message in transit.
smi_icon_sent		Icon representing a successfully sent message.
smi_image_icon		Icon representing an image placeholder in the feed.
smi_no_search_results		Icon shown when there are no search results.
smi_options_menu_icon		Icon representing the conversation options navigation action.

Strings

To customize any UI text, create a strings.xml resource file in your app using the SDK's resource names. To learn more, see Customize Strings for Android.