Displaying Messages

The SDK provides pre-built UI components for displaying the embedded messaging inbox. These components handle message fetching, pagination, selection, deletion and navigation to the detailed view automatically.

Prerequisites

Before displaying the message list, verify that:

1. The SDK is initialized.
2. Tracking is enabled with a valid application code.

Full Embedded Messaging View

The full embedded messaging view includes filtering options (categories, read/unread) and an adaptive layout that shows the detailed view on larger screens.

Android

Use the EmbeddedMessagingView composable in your Compose code:

import com.sap.ec.mobileengage.embeddedmessaging.ui.list.EmbeddedMessagingView

@Composable
fun MessagingScreen() {
    EmbeddedMessagingView(showFilters = true)
}

Parameters:

• showFilters - Displays the category and read/unread filter controls. Is set to true by default.
  • customMessageItem - Optional custom composable for rendering message items (see Custom Message Items).

Android (Views / XML)

If your Android app is not using Compose, you can still use Embedded Messaging with a ComposeView. See: Using Compose Views in Non-Compose Android Apps.

Kotlin Multiplatform

Use the EmbeddedMessagingView composable in your shared Compose code:

import com.sap.ec.mobileengage.embeddedmessaging.ui.list.EmbeddedMessagingView

@Composable
fun MessagingScreen() {
    EmbeddedMessagingView(showFilters = true)
}

Parameters:

• showFilters - Displays the category and read/unread filter controls. Is set to true by default.
  • customMessageItem - Optional custom composable for rendering message items (see Custom Message Items).

iOS

1. Get a UIViewController containing the message list:

// In your view controller
let messagingViewController = EngagementCloud.shared.embeddedMessaging.ViewController(showFilters: true)

2. Use UIViewControllerRepresentable to embed in SwiftUI:

struct EmbeddedMessagingView: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        EngagementCloud.shared.embeddedMessaging.ViewController(showFilters: true)
    }
    
    func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
    }
}

// Usage in a SwiftUI view
struct ContentView: View {
    var body: some View {
        EmbeddedMessagingView()
    }
}

Web

Add the following custom element to your HTML:

<ec-embedded-messaging></ec-embedded-messaging>

Attributes:

• custom-message-item-element-name - Optional name of a custom element for rendering message items.
  • hide-filters - Set to true to hide the filter controls.

Example with custom element:

<ec-embedded-messaging 
    custom-message-item-element-name="my-custom-message">
</ec-embedded-messaging>

Compact View

The compact view displays only the message list without filters or detailed view navigation. Use this when you want to embed the message list in a smaller area or handle navigation yourself.

Android

import com.sap.ec.mobileengage.embeddedmessaging.ui.list.EmbeddedMessagingCompactView

@Composable
fun CompactMessagingScreen() {
    EmbeddedMessagingCompactView(
        onNavigate = {
            // Handle navigation to detailed view
        }
    )
}

Parameters:

• onNavigate - Callback is triggered when a message is selected. Since the compact list does not include a built-in detailed view, use this callback to navigate to your own detailed view.
• customMessageItem - Optional custom composable for rendering message items. For more information, refer to Custom Message Items.

Kotlin Multiplatform

import com.sap.ec.mobileengage.embeddedmessaging.ui.list.EmbeddedMessagingCompactView

@Composable
fun CompactMessagingScreen() {
    EmbeddedMessagingCompactView(
        onNavigate = {
            // Handle navigation to detailed view
        }
    )
}

Parameters:

• onNavigate - Callback is triggered when a message is selected. Since the compact list does not include a built-in detailed view, use this callback to navigate to your own detailed view.
• customMessageItem - Optional custom composable for rendering message items. For more information, refer to Custom Message Items.

iOS

EngagementCloud.shared.embeddedMessaging.CompactViewController {
    //onNavigate logic
} customMessageItem: { viewModel, isSelected in
    //customMessageItem viewController implementation
}

Parameters:

• onNavigate - Callback triggered when a message is selected. Since the compact list does not include a built-in detailed view, use this callback to navigate to your own detailed view.
• customMessageItem - Optional custom ViewController for rendering message items (see Custom Message Items)

SwiftUI Integration

Use UIViewControllerRepresentable to embed in SwiftUI:

struct EmbeddedMessagingCompactView: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        EngagementCloud.shared.embeddedMessaging.CompactViewController {
            //onNavigate logic
        } customMessageItem: { viewModel, isSelected in
            //customMessageItem viewController implementation
        }
    }
    
    func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
    }
}

// Usage in a SwiftUI view
struct ContentView: View {
    var body: some View {
        EmbeddedMessagingView()
    }
}

Web

<ec-embedded-messaging-compact></ec-embedded-messaging-compact>

Attributes:

• custom-message-item-element-name - Optional name of a custom element for rendering message items.

Example:

<div style="height: 400px; width: 300px;">
    <ec-embedded-messaging-compact></ec-embedded-messaging-compact>
</div>

Handling Navigation Events

The compact view sends a navigate event when a message is selected. Use this to navigate to your own detailed view:

document.querySelector('ec-embedded-messaging-compact')
    .addEventListener('navigate', (e) => {
        // Navigate to your custom detailed view
    });

Adaptive Layout

The full embedded messaging view automatically adapts to different screen sizes:

• Single pane - On smaller screens, only the message list is displayed. The user navigates to the detailed view from there.
• Two pane - On larger screens, the message list is displayed on the left and the detailed view on the right.

This behavior is built-in and requires no additional configuration.

Loading States

The message list automatically handles loading states:

• Initial Load - Displays a shimmer/skeleton placeholder while fetching the first page.
• Pagination - Displays a loading spinner at the bottom while fetching more messages.
• Empty State - Displays an empty state message when no messages are available.
• Filtered Empty State - Displays an empty state message and a "Clear Filters" button when no messages are available based on the filters set.
• Error State - Shows an error message with a retry option when the user is offline or there's a network issue.

Platform-Specific Interactions

Message Deletion

The SDK provides platform-specific interactions for deleting messages that cannot be customized:

• Mobile (Android/iOS) - Swipe from right to left on a message item to delete it.
• Web - Delete using an icon button on the message item.

These behaviors are built into the pre-built UI components and are not configurable.

Navigating Back to the Message List

The SDK provides platform-specific navigation interactions that cannot be customized:

• Mobile (Android/iOS) - A swipe-back gesture navigates from the detailed view back to the message list.
• Web - The detailed view includes a back navigation button.