Custom web inbox

You can implement a custom inbox on your website using our web SDK.

The following steps describe how to retrieve the message for display in your own custom content block. In most scenarios, you first need to add your own button to your website, probably within a prominent position such as a menu bar, and use this to control the display of the message area. Finally, we recommend getting the message count, so that you can show a badge on the inbox button, to act as a visual indicator and call-to-action for the user.

Build the message inbox

You can use the message.list SDK method to retrieve the list of messages for the current user:

xtremepush('inbox', 'message.list', params, success, error);

The result object passed to the success function contains:

{
    items: array,  // Array of messages
    more: boolean, // Shows if there is more messages for this user
    badge: integer // Updated inbox badge
}

The message object contains:

{
    id: integer,  // Message id
    opened: 0/1,  // Whether the message is marked as opened or not
    clicked: 0/1, // Whether a click event was tracked on this message
    create_time: integer,     // Unix timestamp of when message was created
    expiration_time: integer, // Unix timestamp of when message is expiring. Could be null.
    message: {    // Data to render the message
        title: string,
        alert: string,
        icon: string,
        style: array
    }
}

Available params:

{
    limit: integer,    // Maximum number of messages to return
    offset: integer,   // Offset that can be used for pagination or show more functionality.
    opened: 0/1,       // Return opened or not opened messages. Skip to return all.
    clicked: 0/1,      // Return clicked or not clicked messages. Skip to return all.
    expired: 0/1,      // Return expired or not expired messages. 0 by default.
    min_time: integer, // Return messages after certain date (using unix timestamp).
    max_time: integer, // Return messages before certain date (using unix timestamp).
}

You can use the message.count method to count the number of messages for the current user:

xtremepush('inbox', 'message.count', params, success, error);

The list of parameters is the same as for message.list (see above).

The result object passed to the success function contains:

{
    count: integer // Number of messages matching criteria
}

🚧
The message.count method shouldn't be used on page load in order to display the inbox badge. You should use the badge method instead which is described below.

Handle message engagement

You can use the message.action SDK call to mark a message as opened or track clicks:

xtremepush('inbox', 'message.action', action, success, error);

The action object should contain:

{
    id: integer,   // Message id retrieved from message.list SDK method. Required.
    open: 0/1,     // Whether you want to mark message as 'opened'
    click: 0/1,    // Whether you want to track click event
    button: string // Can be used if you want to track click with the specific button ID.
}

📘
Messages clicked will be considered opened
Marking a message as click: 1 automatically marks it as open: 1 as a user cannot click on the message without first opening it.
However, marking a message as open: 1 will not automatically update the click value, as a user may open a message and then not engage with any of the CTAs within it.

The result object passed to the success function contains:

{
    badge: integer // Updated inbox badge
}

You can also use message.actions method call to mark multiple messages as opened:

xtremepush('inbox', 'message.actions', actions, success, error);

The actions object should contain an array of action objects (described above in the message.action section).

Add a badge to the inbox button

You can use the badge method call to retrieve a number to display as a badge on an inbox button as part of your website:

xtremepush('inbox', 'badge', params, success, error);

The result object passed to the success function contains the following:

{
    badge: integer // Up to date inbox badge
}

There are two different types of badges you could use for your inbox:

Number of messages that are not seen by user yet.
Number of messages that are not opened by user yet.

You can select the required type of badge for your project on the inbox settings page. Below you have more context about these options:

The message is marked as seen at the moment when it's returned in a response to the message.list SDK method. So the inbox badge is incrementing when a new message is created for a user. And the badge is reset when the recipient opens the inbox.
The message is marked as opened at the moment when you call message.action SDK method for this message. So the inbox badge is incrementing when a new message is created for a user. And the badge is decremented when the user interacts with the message (e.g., by clicking on it).

Feel free to call the badge SDK method on page load, but note that the badge could be changed during message.list or message.action SDK methods. Both methods return the updated badge so you need to consider updating your badge using these values.

Example

On page load:
xtremepush('ready', function() {
    // make sure to retrieve inbox badge inside ready callback to ensure that user is registered
    xtremepush('inbox', 'badge', {}, function(result) {
        updateMyBadge(result.badge);
    }, function(err) {
        console.log(err);
    });
});

When user clicks to open inbox:
myInboxButton.addEventListener('click', function() {
  xtremepush('inbox', 'message.list', {
    limit: 10,
    offset: 0
  }, function (result) {
    if (result.badge !== undefined) {
        updateMyBadge(result.badge);
    }

    for (var i = 0; i < result.items.length; i++) {
        var item = result.items[i];
        var element = createMyInboxMessageElement(item);

        // Handle click and track open event
        element.addEventListener('click', function () {
            xtremepush('inbox', 'message.action', {
                id: id,
                open: 1
            }, function(result) {
                if (result.badge !== undefined) {
                    updateMyBadge(result.badge);
                }
            }, function(err) {
                console.log(err);
            })
        });
    }

    if (result.more) {
        showMyLoadMoreButton();
    }
  }, function (err) {
    console.log(err);
  });
});

Build the message inbox

🚧

Handle message engagement

📘Messages clicked will be considered opened

Add a badge to the inbox button

Example

📘
Messages clicked will be considered opened