# App Inbox Messaging

Antsomi App Inbox Messaging feature allows you to engage and communicate with your users effectively through notifications within your mobile application. App Inbox messages provide a seamless way to deliver timely and personalized information to your users. With this feature, you can enhance user engagement, promote important updates, and tailor your communication based on user behavior and preferences.

{% hint style="warning" %}
**Important**

Before continuing, please ensure that you've [added the Antsomi Android SDK to your app](https://docs.antsomi.com/developers-guide/android/getting-started).
{% endhint %}

## 1. Configure App Inbox

In your `MainActivity`, after initializing the Antsomi SDK instance, you can init the Antsomi App Inbox by following:

{% tabs %}
{% tab title="Java" %}

```java
import com.antsomi.AntsomiSdk;
import com.antsomi.AppInbox.AppInbox;

public class MainActivity {
    // ... other fields and methods

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        // Init Antsomi App Inbox instance
        try {
            String destinationId = "8987794";
        
            AppInbox appInbox = AntsomiSdk.getInstanceAppInbox();
            appInbox.init(destinationId, AppInbox.AUDIENCE_TYPE_VISITOR);
        } catch (Exception e) {
            Log.e(TAG, e.getMessage(), e);
        }
    }
}
```

{% endtab %}
{% endtabs %}

To effectively configure Antsomi App Inbox Messaging, you'll need to define two essential parameters: `destinationId` and `audienceType`. The table below provides a quick overview of each parameter and its purpose.

<table><thead><tr><th width="184">Field</th><th width="292">Data Type</th><th>Description</th><th data-hidden>Description</th></tr></thead><tbody><tr><td><code>destinationID</code></td><td><code>String</code></td><td>A unique identifier specifying the message destination.</td><td>A unique identifier specifying the message destination.</td></tr><tr><td><code>audienceType</code></td><td><p><code>AppInbox</code> enum</p><ul><li><code>AUDIENCE_TYPE_CUSTOMER</code></li><li><code>AUDIENCE_TYPE_VISITOR</code></li></ul></td><td>A classification parameter for targeted messaging.<br>Each <code>destinationID</code> can target one <code>audieneceType</code> only.</td><td>A classification parameter for targeted messaging. <br>Each destination can target to one type of audience only.</td></tr></tbody></table>

If you don't know how to get your Destination ID, refer to this [<mark style="color:blue;">document</mark>](https://docs.antsomi.com/cdp-365-user-guide-en/marketing-hub/destinations/all-destinations/smart-inbox#how-to-get-portalid-and-destinationid).

## 2. App Inbox APIs

After configuring the Antsomi App Inbox, you're ready to harness the power of the following APIs to manage and deliver messages effectively. These APIs empower you to organize messages into categories, retrieve messages, access specific messages by their unique identifiers, and control message statuses, enhancing your ability to engage with users through the App Inbox.

### Get a List of Message Categories

When App Inbox messages are delivered via Antsomi, they are categorized into one or multiple catalogs based on their content and relevance. This API allows you to retrieve these categorized catalogs, efficiently organizing and presenting messages to users, enhancing their overall messaging experience within your mobile app.

To retrieve a list of message categories, you can use the following function:

{% tabs %}
{% tab title="Java" %}

```dart
import com.antsomi.APICallback;
import com.antsomi.AntsomiSdk;
import com.antsomi.AppInbox.AppInbox;
import com.antsomi.AppInbox.Catalog;

public class InboxActivity {
    // ... other fields and methods
    private List<Catalog> catalogs;

    @Override
    protected void onStart() {
        super.onStart();

        try {
            AntsomiSdk antsomiSdk = AntsomiSdk.getInstance();
            AppInbox appInbox = AntsomiSdk.getInstanceAppInbox();
            
            appInbox.getAllLabels(new APICallback<List<Catalog>>() {
                @Override
                public void onResponse(List<Catalog> response) {
                    // Set activity fields
                    this.catalogs = response;
                }

                @Override
                public void onFailure(Throwable t) {
                    Log.e(TAG, t.getMessage(), t);
                }
            });
        } catch (IllegalStateException e) {
            Log.e(TAG, e.getMessage(), e);
        }
    }
}
```

{% endtab %}
{% endtabs %}

The `Catalog` object is a structured data container that represents a message category within the Antsomi App Inbox. Here's a brief description of the key attributes within the `Catalog` object:

| Field         | Data Type | Description                                   |
| ------------- | --------- | --------------------------------------------- |
| `catalogId`   | `String`  | A unique identifier for the message category. |
| `catalogName` | `String`  | The name or title of the category.            |

To illustrate, look at the sample result below, showcasing a list of Catalogs retrieved from the API. In a real app scenario, this information is typically presented to users on a mobile app screen, ensuring seamless message organization and access.

<figure><img src="https://1976329911-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fi16t4WMYZYowEFalUZLL%2Fuploads%2FEENNLX3qDMS2dVQJIHII%2Fimage.png?alt=media&#x26;token=24063cbc-a26d-435d-a35a-66d1d536440c" alt="" width="375"><figcaption><p>Sample Result - List of Catalogs Retrieved from the API</p></figcaption></figure>

### Get a List of Messages

The Get List Messages API allows you to retrieve a comprehensive list of messages within your Antsomi App Inbox.&#x20;

To retrieve a list of messages, you can use the following function:

{% tabs %}
{% tab title="Java" %}

```java
import com.antsomi.APICallback;
import com.antsomi.AntsomiSdk;
import com.antsomi.AppInbox.AppInbox;
import com.antsomi.AppInbox.MessageInbox;

public class InboxActivity {
    // ... other fields and methods
    private List<Catalog> catalogs;
    private List<MessageInbox> messages;
    private int page;

    @Override
    protected void onStart() {
        super.onStart();

        try {
            AntsomiSdk antsomiSdk = AntsomiSdk.getInstance();
            AppInbox appInbox = AntsomiSdk.getInstanceAppInbox();
            
            appInbox.setPageLimit(20);
            appInbox.getListNotification(Collections.emptyList(), page, new APICallback<List<MessageInbox>>() {
                @Override
                public void onResponse(List<MessageInbox> response) {
                    messages = response;
                }

                @Override
                public void onFailure(Throwable t) {
                    Log.e(TAG, t.getMessage(), t);
                }
            });
        } catch (IllegalStateException e) {
            Log.e(TAG, e.getMessage(), e);
        }
    }
}
```

{% endtab %}
{% endtabs %}

This API can be further customized with a filter parameter, which accepts a list of catalog IDs obtained from the previous [Get List of Message Categories](#get-a-list-of-message-categories) API.&#x20;

{% tabs %}
{% tab title="Java" %}

```java
import com.antsomi.APICallback;
import com.antsomi.AntsomiSdk;
import com.antsomi.AppInbox.AppInbox;
import com.antsomi.AppInbox.Catalog;
import com.antsomi.AppInbox.MessageInbox;

public class InboxActivity {
    // ... other fields and methods
    private List<Catalog> catalogs;
    private List<MessageInbox> messages;
    private int page;

    @Override
    protected void onStart() {
        super.onStart();

        try {
            AntsomiSdk antsomiSdk = AntsomiSdk.getInstance();
            ArrayList<String> catalogIds = new ArrayList<>();
            
            for (int i = 0; i < catalogs.toArray().length; i++) {
                catalogIds.add(catalogs.get(i).getCatalogId());
            }

            AppInbox appInbox = AntsomiSdk.getInstanceAppInbox();
            appInbox.setPageLimit(20);
            appInbox.getListNotification(catalogIds, page, new APICallback<List<MessageInbox>>() {
                @Override
                public void onResponse(List<MessageInbox> response) {
                    messages = response;
                }

                @Override
                public void onFailure(Throwable t) {
                    Log.e(TAG, t.getMessage(), t);
                }
            });
        } catch (IllegalStateException e) {
            Log.e(TAG, e.getMessage(), e);
        }
    }
}
```

{% endtab %}
{% endtabs %}

The `MessageInbox`object is a structured data container that represents a message category within the Antsomi App Inbox. Here's a brief description of the key attributes within the `MessageInbox` object:

<table><thead><tr><th width="182">Field</th><th width="274.3333333333333">Data Type</th><th>Description</th></tr></thead><tbody><tr><td><code>itemId</code></td><td><code>String</code></td><td>The unique ID of each message.</td></tr><tr><td><code>buttonLabel1</code></td><td><code>String</code></td><td>The label of the first button is associated with the message.</td></tr><tr><td><code>buttonAppUrl1</code></td><td><code>String</code></td><td>The URL or action associated with the first button can lead to a specific destination or action when clicked.</td></tr><tr><td><code>buttonLabel2</code></td><td><code>String</code></td><td>The label of the second button associated with the message (if applicable).</td></tr><tr><td><code>buttonAppUrl2</code></td><td><code>String</code></td><td>The URL or action associated with the second button can lead to a specific destination or action when clicked (if applicable).</td></tr><tr><td><code>imageUrl</code></td><td><code>String</code></td><td>The URL of the message's cover image.</td></tr><tr><td><code>heading</code></td><td><code>String</code></td><td>The heading or title of the message.</td></tr><tr><td><code>content</code></td><td><code>String</code></td><td>The text content of the message.</td></tr><tr><td><code>templateId</code></td><td><code>String</code></td><td><p>The ID of the message template. Messages can fall into one of three templates: </p><ul><li><code>announcements</code> with no buttons</li><li><code>coupon</code> with one button</li><li><code>order_verified</code> with two buttons</li></ul></td></tr><tr><td><code>catalogIds</code></td><td><code>List&#x3C;String></code></td><td>A list of Category IDs to which this message has been categorized.</td></tr><tr><td><code>status</code></td><td><p><code>MessageStatus</code> enum</p><ul><li><code>UNREAD</code></li><li><code>READ</code></li><li><code>DELETE</code></li></ul></td><td>The status of the message.</td></tr><tr><td><code>dateCreated</code></td><td><code>String</code></td><td>The timestamp indicates when the message was created.</td></tr><tr><td><code>lastUpdated</code></td><td><code>String</code></td><td>The timestamp indicates the most recent update to the message.</td></tr><tr><td><code>expireDate</code></td><td><code>String</code></td><td>The timestamp indicates when the message is set to expire.</td></tr></tbody></table>

To provide a visual representation of the Get List Messages API's functionality, consider the examples below. The first illustrates a list of messages retrieved from the API without any filtering. In contrast, the second example demonstrates the API's advanced filtering capabilities, resulting in a tailored list of messages associated with specific catalogs.

<div align="center"><figure><img src="https://1976329911-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fi16t4WMYZYowEFalUZLL%2Fuploads%2FIlwpelCS6WHCdFj8grkl%2FIMG_98D7A150636C-1.jpeg?alt=media&#x26;token=06c5412e-7b08-4b94-a89f-b511ecb3c2a6" alt="" width="188"><figcaption><p>Sample Result: List of Messages (Without Filtering)</p></figcaption></figure> <figure><img src="https://1976329911-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fi16t4WMYZYowEFalUZLL%2Fuploads%2FVVJRIhPIhAfHYBA3QHwJ%2FImage_20230920_172429_228.png?alt=media&#x26;token=c827a22f-d4d5-4273-b916-273510f2e292" alt="" width="188"><figcaption><p>Sample Result: List of Messages (With Filtering)</p></figcaption></figure></div>

### Get a Message by ID

The Get a Message by ID API serves as a valuable tool to retrieve a specific message from your Antsomi App Inbox. By supplying the unique identifier of the desired message, you can access its content and details with ease.

To retrieve a message using its ID, you can use the following function:

{% tabs %}
{% tab title="Java" %}

```java
import com.antsomi.APICallback;
import com.antsomi.AntsomiSdk;
import com.antsomi.AppInbox.AppInbox;
import com.antsomi.AppInbox.MessageInbox;

public class InboxDetailActivity {
    // ... other fields and methods
    private String messageId;
    private MessageInbox message;

    @Override
    protected void onStart() {
        super.onStart();

        try {
            AntsomiSdk antsomiSdk = AntsomiSdk.getInstance();
            AppInbox appInbox = AntsomiSdk.getInstanceAppInbox();
            
            appInbox.getDetailMessage(messageId, new APICallback<List<MessageInbox>>() {
                @Override
                public void onResponse(MessageInbox response) {
                    message = response;
                }

                @Override
                public void onFailure(Throwable t) {
                    Log.e(TAG, t.getMessage(), t);
                }
            });
        } catch (IllegalStateException e) {
            Log.e(TAG, e.getMessage(), e);
        }
    }
}
```

{% endtab %}
{% endtabs %}

To illustrate this API's functionality, refer to the example below, showcasing a retrieved message based on its unique ID.

<figure><img src="https://1976329911-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fi16t4WMYZYowEFalUZLL%2Fuploads%2FpqTrX0naBoB6pxn2BQjx%2FImage_20230920_172453_093.png?alt=media&#x26;token=3bd37b7b-f682-4f8c-a92f-3cf497a762d8" alt="" width="188"><figcaption><p>Sample Result: Message Retrieved by ID</p></figcaption></figure>

### Change a Message status

With the 'Update Message Status' API, you can toggle a message's status between read and `unread`, allowing for precise control over how messages are presented to users.

To modify a message status, simply call this function:

{% tabs %}
{% tab title="Java" %}

```java
import com.antsomi.APICallback;
import com.antsomi.AntsomiSdk;
import com.antsomi.AppInbox.AppInbox;
import com.antsomi.AppInbox.Catalog;
import com.antsomi.AppInbox.MessageInbox;

public class InboxActivity {
    // ... other fields and methods
    private List<Catalog> catalogs;
    
    private List<MessageInbox> messages;
    private List<String> selectedMessagedIds;
    
    private int page;

    protected void handleUpdateStatusMessage() {
        try {
            AntsomiSdk antsomiSdk = AntsomiSdk.getInstance();            
            ArrayList<String> catalogIds = new ArrayList<>();
            
            for (int i = 0; i < catalogs.toArray().length; i++) {
                catalogIds.add(catalogs.get(i).getCatalogId());
            }

            AppInbox appInbox = AntsomiSdk.getInstanceAppInbox();
            appInbox.updateMessage(selectedMessagedIdseIds, MessageInbox.MessageStatus.READ);
        } catch (IllegalStateException e) {
            Log.e(TAG, e.getMessage(), e);
        }
    }
}
```

{% endtab %}
{% endtabs %}

To illustrate the functionality of this API, please refer to the example below, which showcases the process of updating a message's status from read(without the blue dot indicator) to unread(with the blue dot indicator) or vice versa.

<figure><img src="https://1976329911-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fi16t4WMYZYowEFalUZLL%2Fuploads%2FJwiD2YfXX1MrVI3XE1je%2FImage_20230920_172429_228.png?alt=media&#x26;token=c9b02409-45cc-49c3-9f92-423bf0014a65" alt="" width="188"><figcaption><p>Sample Result: Message Status Updated (Read to Unread or Vice Versa)</p></figcaption></figure>

Incorporate Antsomi's App Inbox Messaging to elevate your mobile app's communication strategy. With powerful APIs and customization options, you can deliver personalized, engaging messages tailored to your users' preferences.