Brand Concierge API reference (Android)

Managed Integration

The SDK manages the chat lifecycle. Provide a trigger UI element — the SDK shows it when the extension is ready and opens the chat as a full-screen dialog when the trigger is invoked.

Jetpack Compose

Syntax

@Composable
fun ConciergeChat(
    modifier: Modifier = Modifier,
    viewModel: ConciergeChatViewModel,
    surfaces: List<String>? = null,
    handleLink: LinkHandler? = null,
    content: @Composable (showChat: () -> Unit) -> Unit
)

Parameters

viewModel required - A ConciergeChatViewModel instance. Obtain via viewModel<ConciergeChatViewModel>().
surfaces - Surface identifiers sent to the Brand Concierge server.
modifier - Optional Modifier to apply to the composable.
handleLink - Optional LinkHandler callback. Return true to claim the URL; return false for default behavior.
content required - Composable lambda receiving a showChat function. Call showChat() to open the chat.

Example

@Composable
fun MyScreen() {
    val viewModel = viewModel<ConciergeChatViewModel>()

    ConciergeChat(
        viewModel = viewModel,
        surfaces = listOf("web://example.com/your-surface.html")
    ) { showChat ->
        MyTriggerButton(onClick = { showChat() })
    }
}

XML/Views

Syntax

fun bind(
    lifecycleOwner: LifecycleOwner,
    viewModelStoreOwner: ViewModelStoreOwner,
    surfaces: List<String>? = null,
    theme: ConciergeThemeData? = null,
    handleLink: ((String) -> Boolean)? = null,
    triggerView: View
)

Parameters

lifecycleOwner required - The LifecycleOwner (typically your Activity or Fragment).
viewModelStoreOwner required - The ViewModelStoreOwner (typically your Activity or Fragment).
surfaces - Surface identifiers sent to the Brand Concierge server.
theme - Optional ConciergeThemeData to apply to the chat UI.
handleLink - Optional callback. Return true to claim the URL; return false for default behavior.
triggerView required - The View that launches the chat when clicked.

Example

val chatView = findViewById<ConciergeChatView>(R.id.concierge_chat)
val triggerButton = Button(this).apply { text = "Chat" }

chatView.bind(
    lifecycleOwner = this,
    viewModelStoreOwner = this,
    surfaces = listOf("web://example.com/your-surface.html"),
    triggerView = triggerButton
)

Custom Integration

Embed the chat interface directly into your screen and manage its lifecycle yourself. Use this for dedicated chat screens or custom layouts where you control when chat appears and handle dismissal.

Jetpack Compose

Syntax

@Composable
fun ConciergeChat(
    viewModel: ConciergeChatViewModel,
    onClose: () -> Unit,
    modifier: Modifier = Modifier,
    handleLink: LinkHandler? = null
)

Parameters

viewModel required - A ConciergeChatViewModel instance. Obtain via viewModel<ConciergeChatViewModel>().
onClose required - Callback invoked when the user dismisses the chat (back press, close button, or gesture).
modifier - Optional Modifier to apply to the composable.
handleLink - Optional LinkHandler callback. Return true to claim the URL; return false for default behavior.

Example

@Composable
fun YourChatScreen() {
    val viewModel = viewModel<ConciergeChatViewModel>()
    val conciergeState by ConciergeStateRepository.instance.state.collectAsStateWithLifecycle()
    val surfaces = listOf("web://example.com/your-surface.html")

    ConciergeStateRepository.instance.setSessionSurfaces(surfaces)

    val ready = conciergeState.configurationReady &&
        conciergeState.experienceCloudId != null &&
        conciergeState.surfaces.isNotEmpty()

    if (ready) {
        ConciergeChat(
            viewModel = viewModel,
            onClose = { /* navigate back */ }
        )
    }
}

XML/Views

Syntax

fun bind(
    lifecycleOwner: LifecycleOwner,
    viewModelStoreOwner: ViewModelStoreOwner,
    surfaces: List<String>? = null,
    theme: ConciergeThemeData? = null,
    handleLink: ((String) -> Boolean)? = null,
    onClose: () -> Unit
)

Parameters

lifecycleOwner required - The LifecycleOwner (typically your Activity or Fragment).
viewModelStoreOwner required - The ViewModelStoreOwner (typically your Activity or Fragment).
surfaces - Surface identifiers sent to the Brand Concierge server.
theme - Optional ConciergeThemeData to apply to the chat UI.
handleLink - Optional callback. Return true to claim the URL; return false for default behavior.
onClose required - Callback invoked when the user dismisses the chat.

Example

val chatView = findViewById<ConciergeChatView>(R.id.concierge_chat)

chatView.bind(
    lifecycleOwner = this,
    viewModelStoreOwner = this,
    surfaces = listOf("web://example.com/your-surface.html"),
    onClose = { finish() }
)

Concierge.setAuthTokenProvider

Registers a ConciergeAuthTokenProvider that supplies an app-minted authentication token, attached to every chat and feedback request until cleared. Pass null to clear a previously registered provider.

Syntax

@JvmStatic
@JvmOverloads
fun setAuthTokenProvider(
    provider: ConciergeAuthTokenProvider?,
    timeoutMillis: Long = 3000L
)

Parameters

provider required - A ConciergeAuthTokenProvider instance, or null to clear a previously registered provider.
timeoutMillis - How long to wait for provider.provideToken() before sending the turn without a token. Defaults to 3000 (3 seconds); out-of-bounds values are clamped rather than rejected.

Example

Concierge.setAuthTokenProvider(
    ConciergeAuthTokenProvider { myAuthTokenCache.getCurrentToken() },
    timeoutMillis = 5000L
)

ConciergeAuthTokenProvider

A functional interface that supplies the app-minted authentication token attached to each conversation turn (chat and feedback). Register an implementation with Concierge.setAuthTokenProvider.

Syntax

fun interface ConciergeAuthTokenProvider {
    fun provideToken(): String?
}

Parameters

provideToken required - Called immediately before building each turn's request. Return the current opaque, app-minted token, or null to send the turn without one. Invoked on a background thread and may block briefly to refresh the token; the SDK bounds the wait via timeoutMillis.

Concierge.sendDataHandoff

Hands data that did not originate in the chat UI (for example, the result of a native checkout flow) to the Brand Concierge agent pipeline. The response is rendered through the active chat transcript without requiring the user to type or say a chat message.

data-variant=info

data-slots=text

A configured ConciergeChat or ConciergeChatView must be rendered with a non-empty surfaces list while calling this API. A handoff made without an active chat session fails with NO_ACTIVE_SESSION. See Data handoff in the implementation guide for details.

Syntax

@JvmStatic
@JvmOverloads
fun sendDataHandoff(
    routingHint: String = "",
    xdmFields: Map<String, Any>,
    localMessage: String? = null,
    completion: ConciergeDataHandoffCallback? = null
)

Parameters

routingHint - A string consumed only by Brand Concierge's phrase-based router (for example, "successful-checkout"). Never shown to the end user. Defaults to an empty string, which is appropriate when xdmFields alone determine routing. Java callers pass "" explicitly.
xdmFields required - Non-empty, XDM-shaped data merged into the root of the outbound XDM object. Keys must be Strings, and values must be JSON-safe (String, Boolean, finite Int, Long, Float, or Double, or maps and lists containing those values). identityMap is reserved and cannot be used as a top-level key.
localMessage - Optional text rendered as a local, agent-attributed chat message immediately before an accepted handoff starts. It is not sent to Brand Concierge.
completion - Optional ConciergeDataHandoffCallback, called exactly once on a background thread with the outcome.

Example

Concierge.sendDataHandoff(
    routingHint = "successful-checkout",
    xdmFields = mapOf(
        "commerce" to mapOf(
            "order" to mapOf("purchaseID" to orderId)
        )
    ),
    localMessage = "Your order is confirmed!"
) { accepted, rejectReason ->
    if (!accepted) {
        // Inspect rejectReason; retry on CHAT_IN_PROGRESS after the active turn completes.
    }
}

ConciergeDataHandoffCallback

A functional interface that reports the outcome of a Concierge.sendDataHandoff call. Invoked exactly once, on a background thread.

Syntax

fun interface ConciergeDataHandoffCallback {
    fun onResult(accepted: Boolean, rejectReason: ConciergeDataHandoffRejectReason?)
}

Parameters

accepted - true only after the handoff was validated, rendered through the active chat session, and completed by Brand Concierge with renderable content.
rejectReason - A ConciergeDataHandoffRejectReason when accepted is false, or null when accepted is true. See the reject reason table in the implementation guide for all values.

ConciergeThemeLoader.load

Loads a ConciergeThemeData from a JSON file in the app's assets directory. Returns null if the file cannot be found or parsed.

Syntax

@JvmStatic fun load(context: Context, filename: String): ConciergeThemeData?

Parameters

context required - An Android Context used to access the assets directory.
filename required - The filename of the JSON theme file (including the .json extension).

Example

val theme = ConciergeThemeLoader.load(context, "my-theme.json")
    ?: ConciergeThemeLoader.default()

ConciergeThemeLoader.default

Returns the built-in default ConciergeThemeData.

Syntax

@JvmStatic fun default(): ConciergeThemeData

Example

val theme = ConciergeThemeLoader.default()