Once you have the SDK set up and your local environment configured, you can begin to fetch and manage messages. This guide covers the core functions available on the Embedded Messaging SDK.

Prerequisites

You must have the Optimove Web SDK v2 configured on your website. For instructions, please see the SDK Setup & Local Development guide.

User Identification

Before fetching messages, you must identify the user to the SDK. This ensures you retrieve messages targeted specifically to them. If the user is already logged in on your site, you can skip this step.

optimoveSDK.API.setUserId('test_customer_id');

Fetching Messages

The primary method for retrieving messages is getMessageAsync().

Get All Messages

To get all messages for the logged-in user, across all of their containers, call the method with no arguments.

const allMessages = await optimoveSDK.API.embeddedMessaging.getMessageAsync();

This returns an object where keys are the containerIds and values are objects containing the messages for that container.

Example Response Shape:

{
    "Inbox": {
        "containerId": "Inbox",
        "messages": [
            {
                "id": "6a0b625d-0b0c-4145-aa99-41405ff3ec4b",
                "title": "Message 1",
                "content": "Content for message 1",
                "readAt": 1745401860892,
                "url": "[http://optimove.com](http://optimove.com)",
                "executionDateTime": "2025-04-11T14:58:39Z"
            }
        ]
    },
    "container_2": {
        "containerId": "container_2",
        "messages": [
            {
                "id": "a284bb5e-755e-401b-a804-4b883d70f07a",
                "title": "Title 2",
                "content": "Content for message 2"
            }
        ]
    }
}

Get Messages from Specific Containers

To retrieve messages from specific containers, you can pass an array of configuration objects. Each object can specify the containerId and a limit on the number of messages to return (the default limit is 50).

Get the last 2 messages from "container_1" and the default number of messages from "Inbox":

const specificMessages = await optimoveSDK.API.embeddedMessaging.getMessageAsync([
    { containerId: "container_1", limit: 2 },
    { containerId: "Inbox" }
]);

Managing Message State

Mark a Message as Read/Unread

To update the read status of a message, use setReadAsync(). You must pass the entire message object you wish to update.

Mark as Read: This will update the message's readAt timestamp and send an "open" metric to Optimove.
```
optimoveSDK.API.embeddedMessaging.setReadAsync(message, true);
```
Mark as Unread: This will set the message's readAt timestamp to null. No metric is sent.
```
optimoveSDK.API.embeddedMessaging.setReadAsync(message, false);
```

Reporting Engagement

Report a Click Metric

To report that a user has clicked on a message, use reportClickMetricAsync(). You must pass the entire message object.

optimoveSDK.API.embeddedMessaging.reportClickMetricAsync(message);

Delete a Message

To delete a message, use deleteMessageAsync(). This will mark the message as deleted, and it will no longer be returned in any future getMessageAsync calls.

optimoveSDK.API.embeddedMessaging.deleteMessageAsync(message);

Example Implementations

Here are some examples of how you might use the SDK to build common UI components.

📘
Note
Ensure you have loaded the Optimove SDK bundle before attempting to load these components.

Carousel Component

View Vanilla JS and React Code

Vanilla JS:

<script>
/**
 * Main function to initialize and render carousels
 * @param {HTMLElement} element - The container element for carousels
 */
async function initializeCarousels(element) {
    try {
        const response = await optimoveSDK.API.embeddedMessaging.getMessageAsync([
            { containerId: "carousel", limit: 2 } // default is 50
        ]);

        renderCarousels(element, response);
    } catch (error) {
        console.error('Failed to initialize carousel:', error);
        element.innerHTML = '<div class="error">Failed to load carousels</div>';
    }
}

// ... rest of carousel implementation
</script>

React:

import React, { Component } from 'react';

class Carousel extends Component {
    constructor(props) {
        super(props);
        this.state = {
            carousels: {},
            error: null
        };
    }

    async componentDidMount() {
        try {
            const response = await optimoveSDK.API.embeddedMessaging.getMessageAsync([
                { containerId: 'carousel', limit: 2 }
            ]);
            this.setState({ carousels: response });
        } catch (error) {
            console.error('Failed to initialize carousel:', error);
            this.setState({ error: 'Failed to load carousels' });
        }
    }

    // ... rest of carousel implementation
}

export default Carousel;

Hero Banner

View Vanilla JS and React Code

Vanilla JS:

<script>
async function initializeHeroBanner(element) {
    try {
        const response = await optimoveSDK.API.embeddedMessaging.getMessageAsync([
            { containerId: "hero", limit: 1 }
        ]);

        renderHeroBanner(element, response);
    } catch (error) {
        console.error('Failed to initialize hero banner:', error);
        element.innerHTML = '<div class="error">Failed to load hero banner</div>';
    }
}
// ... rest of hero banner implementation
</script>

React:

import React, { Component } from 'react';

class HeroBanner extends Component {
    constructor(props) {
        super(props);
        this.state = {
            hero: null,
            error: null
        };
    }

    async componentDidMount() {
        try {
            const response = await optimoveSDK.API.embeddedMessaging.getMessageAsync([
                { containerId: 'hero', limit: 1 }
            ]);

            if (response.hero && response.hero.messages && response.hero.messages.length > 0) {
                this.setState({ hero: response.hero.messages[0] });
            } else {
                this.setState({ error: 'No hero content available' });
            }
        } catch (error) {
            console.error('Failed to initialize hero banner:', error);
            this.setState({ error: 'Failed to load hero banner' });
        }
    }
    
    // ... rest of hero banner implementation
}

export default HeroBanner;