This page is part of the Customer.io documentation. For the complete documentation index, see llms.txt.

55

Notification inbox

How it works

Unlike other messages, inbox messages don’t necessarily appear immediately to your audience, and they don’t disappear when a person dismisses them. Instead, messages collect in a notification inbox that people can check at their leisure. You send inbox messages as part of an automation, broadcast, or transactional message.

The SDK gives you two ways to show the inbox in your app:

• Recommended: add the visual inbox. Mount the SDK’s ready-made inbox views—a bell icon with an unread badge and a panel that lists messages. The SDK renders the inbox you style and publish in Customer.io using native UI—no webviews—and handles fetching messages, unread counts, opens, and clicks for you.
• Advanced: build your own inbox. The SDK delivers inbox messages as JSON payloads, and you render them in your own inbox UI. Take this path when you need complete control over the inbox experience.

Add the visual inbox

The visual inbox renders the same inbox you publish for your website: your icon, colors, position, unread indicator, and message templates—including dark mode styles. When there’s nothing to show—the inbox isn’t published or has no messages—the inbox views render nothing, so they’re safe to mount unconditionally.

Prerequisites

• Create, style, and publish a notification inbox in your workspace.
• Set up in-app messaging in your app. The inbox module builds on the in-app messaging module.
• The visual inbox views are Jetpack Compose composables. If your app uses XML layouts, you can host them in a ComposeView.

Install the inbox module

The visual inbox ships as its own module, so apps that don’t use it don’t carry its dependencies. Add the dependency to your app’s build.gradle.

implementation "io.customer.android:messaging-inbox:4.20.1"

Add the inbox to your app

NotificationInboxOverlay is the all-in-one option: a floating bell button with an unread badge that slides out the message list, and a scrim that closes it when a person taps outside. Mount it once, near the top of your Compose hierarchy, so it overlays the rest of your content.

import io.customer.messaginginbox.NotificationInboxOverlay

Box(modifier = Modifier.fillMaxSize()) {
    AppContent()
    NotificationInboxOverlay()
}

That’s the whole integration. The overlay fetches messages, shows and updates the unread badge, marks messages opened when the panel opens, and reports opens and clicks to your inbox metrics.

If your app uses XML layouts instead of Compose, host the overlay in a ComposeView that sits on top of your layout:

composeView.setContent {
    NotificationInboxOverlay()
}

Place the bell and message list yourself

If the floating overlay doesn’t fit your design, compose the two underlying views directly:

• NotificationInboxBell: the bell button with the unread badge. Place it anywhere—a top app bar, a tab, a corner—and use its onClick to present your inbox.
• NotificationInboxView: the message list without any surrounding chrome. Embed it in a bottom sheet, a dialog, or a dedicated inbox screen.

import io.customer.messaginginbox.NotificationInboxBell
import io.customer.messaginginbox.NotificationInboxView

var isInboxVisible by remember { mutableStateOf(false) }

Scaffold(
    topBar = {
        TopAppBar(
            title = { Text("Dashboard") },
            actions = {
                NotificationInboxBell(onClick = { isInboxVisible = true })
            }
        )
    }
) { padding ->
    AppContent(Modifier.padding(padding))

    if (isInboxVisible) {
        ModalBottomSheet(onDismissRequest = { isInboxVisible = false }) {
            NotificationInboxView(modifier = Modifier.fillMaxWidth())
        }
    }
}

Handle message actions

When a person taps a message or a button inside it, the SDK runs the action you set on the message: it opens URLs in the browser, removes the message for dismiss actions, and so on. If your messages use deep links or you want to route navigation through your own code, set an InboxEventListener when you configure the in-app messaging module.

import io.customer.messaginginapp.MessagingInAppModuleConfig
import io.customer.messaginginapp.ModuleMessagingInApp
import io.customer.messaginginapp.type.InboxEventListener

ModuleMessagingInApp(
    config = MessagingInAppModuleConfig.Builder(siteId = "site-id", region = Region.US)
        .setInboxEventListener(object : InboxEventListener {
            override fun messageActionTaken(
                message: InboxMessage,
                actionName: String,
                actionValue: String
            ): Boolean {
                if (actionValue.startsWith("myapp://")) {
                    // Navigate within your app
                    deepLinkRouter.open(actionValue)
                    // Return true to tell the SDK you handled the action,
                    // so it doesn't run its default behavior
                    return true
                }
                // Return false to let the SDK handle the action
                return false
            }
        })
        .build()
)

You can also set or replace the listener at runtime:

ModuleMessagingInApp.instance().setInboxEventListener(listener)

The listener also receives optional, observe-only callbacks you can use for analytics or app state—their return values don’t change SDK behavior:

Dismiss actions always remove the message; they aren’t routed to your listener.

Visual inbox behaviors

• The bell hides itself when there’s nothing to show. If your inbox isn’t published, or the person has no messages, the bell and panel don’t render at all.
• Opening the inbox marks messages opened. Messages visible in the open panel—or in an embedded NotificationInboxView—are marked opened automatically, and the unread badge updates to match.
• Dismissing a message deletes it. When a person dismisses a message, the SDK removes it from their inbox on every device.
• Dark mode is automatic. The inbox follows the device’s appearance and re-renders when it changes, using the dark mode colors you set in Design Studio.
• Style changes flow to your app. When you update your inbox’s styles or templates in Customer.io, the SDK picks up the changes on its next refresh—no app update required.

Build your own inbox

If you need complete control over the inbox experience, skip the visual inbox and work with the message payloads directly. Customer.io delivers inbox messages as JSON payloads, not fully rendered messages. The SDK helps you listen for these payloads, but you determine how to display them in your own inbox client.

Get the inbox instance

You’ll access inbox functionality through the inbox() method on the in-app messaging module.

val inbox = CustomerIO.instance().inAppMessaging().inbox()

Inbox methods

The inbox instance provides several methods to manage messages.

Inbox message payloads

Inbox messages are delivered as a JSON payload. The SDK helps you listen for the payload, but you’ll render the content in your own inbox client.

The client payload includes the following fields, but you’re most concerned with the properties object, which represents your message content. By default, we’ll send a title and body field, but you can add other fields like an image or a link—whatever you set up your inbox to expect.

Make sure that your team members know what payloads to send—especially if you expect different payloads for different topics or types of messages.

{
    "messageId": "1234567890",
    "sentAt": "2026-02-05T12:00:00Z",
    "expiresAt": "2026-02-05T12:00:00Z",
    "opened": false,
    "topics": ["orders", "shipping"],
    "type": "order_shipped",
    "properties": {
        "title": "Hey Cool Person, your order shipped!",
        "body": "You can track your order #1234567890 here:",
        "link": "https://example.com/orders/1234567890"
    }
}

Inbox topics and types

When you send an inbox message, you can assign it to one or more topics. You can use these topics to filter messages when you fetch them. You can also use the topics to determine how to render the messages in your notification inbox.

Messages also have a type. Think of this like a sub-category or topic for a message. For example, you might have orders and sale topics, where orders don’t have images but sale topics might. Or, within the orders topic, you might have order_placed and order_shipped types, where order_placed lists order details and images of purchased products and order_shipped provides a link to the tracking information for the order that opens in a new tab.

Setup your notification inbox

Inbox messages are just JSON payloads. You’ll need to build your own inbox client to display the messages. The code below gives you a starting point, but you can build your own inbox client however you want.

Fetch messages

// Using suspend function (recommended)
val messages = notificationInbox.getMessages()

// Fetch messages filtered by topic
val promoMessages = notificationInbox.getMessages(topic = "promotions")

// Using callback
notificationInbox.fetchMessages { result ->
    runOnUiThread {
        result.onSuccess { messages ->
            // Update your UI with the messages
            updateInboxUI(messages)
        }.onFailure { error ->
            // Handle error
            Log.e("Inbox", "Failed to fetch messages", error)
        }
    }
}

// Using callback with topic filter
notificationInbox.fetchMessages("promotions") { result ->
    runOnUiThread {
        result.onSuccess { messages ->
            // Update your UI with filtered messages
            updatePromotionsUI(messages)
        }.onFailure { error ->
            Log.e("Inbox", "Failed to fetch messages", error)
        }
    }
}

Listen for message updates

// Create a change listener
val notificationInboxChangeListener = object : NotificationInboxChangeListener {
    override fun onMessagesChanged(messages: List<InboxMessage>) {
        // Update your UI with the new messages
        updateInboxUI(messages)
    }
}

// Add the listener
notificationInbox.addChangeListener(notificationInboxChangeListener)

// Don't forget to remove the listener when you're done
notificationInbox.removeChangeListener(notificationInboxChangeListener)

Mark messages as opened or unopened

// Mark a message as opened
notificationInbox.markMessageOpened(message)

// Mark a message as unopened
notificationInbox.markMessageUnopened(message)

Track message clicks

// Track a click without an action name
notificationInbox.trackMessageClicked(message)

// Track a click with an action name
notificationInbox.trackMessageClicked(message, "view_order")

Delete messages

// Mark a message as deleted
notificationInbox.markMessageDeleted(message)

Working with message properties

You can access message properties to display custom content in your inbox:

// Access message properties
val title = message.properties["title"] as? String
val body = message.properties["body"] as? String
val link = message.properties["link"] as? String
val imageUrl = message.properties["image"] as? String

// Handle message action when user taps
fun handleMessageTap(message: InboxMessage) {
    // Mark as opened
    notificationInbox.markMessageOpened(message)

    // Track the click
    notificationInbox.trackMessageClicked(message)

    // Open link if available
    val link = message.properties["link"] as? String
    if (link != null) {
        val intent = Intent(Intent.ACTION_VIEW, Uri.parse(link))
        startActivity(intent)
    }
}