Embedded Messaging API

Use the embedded messaging API to apply and manage message filters independently of the built-in components.

Using Built-In Components for Filtering

The following components include built-in filter controls for read/unread state and categories:

• Android / KMP: EmbeddedMessagingView with showFilters = true
• iOS: ViewController with showFilters = true
• Web: <ec-embedded-messaging>

These controls are connected to the component's internal state and update the message list automatically.

Filter by Unread State

Filter the message list to show only unread messages.

Android

// Show only unread messages
EngagementCloud.embeddedMessaging.filterUnreadOnly(true)

// Show all messages
EngagementCloud.embeddedMessaging.filterUnreadOnly(false)

// Check if unread filter is active
val isFilteringUnread = EngagementCloud.embeddedMessaging.isUnreadFilterActive

Kotlin Multiplatform

// Show only unread messages
EngagementCloud.embeddedMessaging.filterUnreadOnly(true)

// Show all messages
EngagementCloud.embeddedMessaging.filterUnreadOnly(false)

// Check if unread filter is active
val isFilteringUnread = EngagementCloud.embeddedMessaging.isUnreadFilterActive

iOS

// Show only unread messages
EngagementCloud.shared.embeddedMessaging.filterUnreadOnly(filterUnreadOnly: true)

// Show all messages
EngagementCloud.shared.embeddedMessaging.filterUnreadOnly(filterUnreadOnly: false)

// Check if unread filter is active
let isFilteringUnread = EngagementCloud.shared.embeddedMessaging.isUnreadFilterActive

Web

// Show only unread messages
await window.EngagementCloud.embeddedMessaging.filterUnreadOnly(true);

// Show all messages
await window.EngagementCloud.embeddedMessaging.filterUnreadOnly(false);

// Check if unread filter is active
const isFilteringUnread = await window.EngagementCloud.embeddedMessaging.isUnreadFilterActive();

Filter by Category

Filter the message list by specific categories.

Android

// Get available categories
val categories = EngagementCloud.embeddedMessaging.categories

// Filter by specific categories
EngagementCloud.embeddedMessaging.filterByCategories(listOf(category1, category2))

// Clear category filter and show all categories
EngagementCloud.embeddedMessaging.filterByCategories(emptyList())

// Get currently active category filters
val activeFilters = EngagementCloud.embeddedMessaging.activeCategoryFilters

Kotlin Multiplatform

// Get available categories
val categories = EngagementCloud.embeddedMessaging.categories

// Filter by specific categories
EngagementCloud.embeddedMessaging.filterByCategories(listOf(category1, category2))

// Clear category filter and show all categories
EngagementCloud.embeddedMessaging.filterByCategories(emptyList())

// Get currently active category filters
val activeFilters = EngagementCloud.embeddedMessaging.activeCategoryFilters

iOS

// Get available categories
let categories = EngagementCloud.shared.embeddedMessaging.categories

// Filter by specific categories
EngagementCloud.shared.embeddedMessaging.filterByCategories(categories: [Category(id: "61f0c404-5cb3-11e7-907b-a6006ad3dba0", text: "Category 1")])

// Clear category filter (show all categories)
EngagementCloud.shared.embeddedMessaging.filterByCategories(categories: [])

// Get currently active category filters
let activeFilters = EngagementCloud.shared.embeddedMessaging.activeCategoryFilters

Web

// Get available categories
const categories = await window.EngagementCloud.embeddedMessaging.getCategories();

// Filter by specific categories
await window.EngagementCloud.embeddedMessaging.filterByCategories([{id: "61f0c404-5cb3-11e7-907b-a6006ad3dba0", text: "Category 1"}]);

// Clear category filter (show all categories)
await window.EngagementCloud.embeddedMessaging.filterByCategories([]);

// Get currently active category filters
const activeCategoryFilters = await window.EngagementCloud.embeddedMessaging.getActiveCategoryFilters();

API Reference

Category Model

Each category has the following properties:

Property	Type	Description
id	String	Unique identifier for the category
text	String	Display text of the category

Properties

Property	Type	Description
categories	List<Category>	All available categories for filtering
isUnreadFilterActive	Boolean	true if showing only unread messages
activeCategoryFilters	List<Category>	Currently selected categories

Methods

Method	Parameters	Description
filterUnreadOnly	filterUnreadOnly: Boolean	Enable or disable the unread-only filter
filterByCategories	categories: List<Category>	Filter by categories, or pass an empty list to clear

Combining Filters

Filters can be combined. For example, you can show only unread messages in a specific category:

Android

// Show only unread messages in category1
EngagementCloud.embeddedMessaging.filterUnreadOnly(true)
EngagementCloud.embeddedMessaging.filterByCategories(listOf(category1))

Kotlin Multiplatform

// Show only unread messages in category1
EngagementCloud.embeddedMessaging.filterUnreadOnly(true)
EngagementCloud.embeddedMessaging.filterByCategories(listOf(messageCategory1))

iOS

// Show only unread messages in messageCategory1
EngagementCloud.shared.embeddedMessaging.filterUnreadOnly(filterUnreadOnly: true)
EngagementCloud.shared.embeddedMessaging.filterByCategories(categories: [messageCategory1])

Web

// Show only unread messages in messageCategory1
await window.EngagementCloud.embeddedMessaging.filterUnreadOnly(true);
await window.EngagementCloud.embeddedMessaging.filterByCategories([messageCategory1]);