Bespoke web inbox

Follow the steps described in this guide to build your own implementation of the web inbox

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

The following steps describe how to retrieve the message for display in your own bespoke 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

  1. 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 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).
}
  1. 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 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.

  1. You can use the message.action SDK call to mark message as opened or track click events:
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.
}

The result object passed to 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 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 success function contains:

{
    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 user 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 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 badge could be changed during message.list or message.action SDK methods. Both of these 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.addEventListender('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);
  });
});

Updated 25 days ago


Bespoke web inbox


Follow the steps described in this guide to build your own implementation of the web inbox

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.