Set up web message inbox

Prerequisites

Make sure you’ve implemented Pushwoosh Web SDK on your website. To do so, please follow our guide.

Message Inbox for websites allows you to store web push notifications so users can revisit them later, ensuring important messages are seen.

How it works

Here’s a typical workflow with InboxMessages:

Step	Method
Page load
Synchronizing messages with the server	InboxMessagesModel.updateMessages Executed while the SDK is initialized
Deleting outdated messages	InboxMessagesModel.updateMessages Executed while the SDK is initialized
Receiving the number of unread messages to update a badge	Pushwoosh.pwinbox.unreadMessagesCount Executed manually (after the onUpdateInboxMessagesevent triggers)
Loading messages to be displayed in Inbox	Pushwoosh.pwinbox.loadMessages Executed manually (after the onUpdateInboxMessagesevent triggers)
Marking messages got in the viewport as read	Pushwoosh.pwinbox.readMessagesWithCodes Executed manually
Performing an action assigned to the message opened	Pushwoosh.pwinbox.performActionForMessageWithCode Executed manually
Deleting messages by click on a delete icon or swipe-right a message	Pushwoosh.pwinbox.performActionForMessageWithCode Executed manually

Event listeners

onUpdateInboxMessages

// Executed after the Inbox is updated automatically while the page is loading.
Pushwoosh.push(['onUpdateInboxMessages', function(api, pwinbox) {
  pwinbox.loadMessages().then(function(messages) {
    console.log('EVENT: onUpdateInboxMessages', messages);
  });
}]);

onPutNewMessageToInboxStore

// Executed by ServiceWorker after the Inbox Message is received and saved to indexedDB.
Pushwoosh.push(['onPutNewMessageToInboxStore', function(api, message) {
  console.log('EVENT: onPutNewMessageToInboxStore', message);
}]);

Public module

WebSDK InboxMessagesPublic module presents a public interface to implement Web Inbox.

Model

type TInboxMessageTypePlain = 0;
type TInboxMessageTypeRichmedia = 1;
type TInboxMessageTypeURL = 2;
type TInboxMessageTypeDeeplink = 3;
type TInboxMessageType = TInboxMessageTypePlain  // depends on action_params
  | TInboxMessageTypeRichmedia
  | TInboxMessageTypeURL
  | TInboxMessageTypeDeeplink;

type TInboxLayout = 'classic' | 'banner' | 'captioned' | 'carousel';

interface IInboxMessageSlide {
  imageUrl: string;
  caption: string;  // caption overlaid on the slide; empty when the slide has none
  link: string;  // where a tap on the slide goes; empty when the slide has none, and the message's own action applies instead
}

interface IInboxMessagePublic {
  code: string;  // inbox_id
  title: string;  // title
  message: string; // body
  imageUrl: string;  // image
  sendDate: string;  // send_date, ISO 8601 in UTC
  type: TInboxMessageType;  // depends on action_params
  isRead: boolean;  // true if status is "read" or "open"
  link: string; // Deeplink | URL | "/"
  isActionPerformed: boolean;  // true if status is "open"
  layout: TInboxLayout;  // cell layout to draw, already degraded to one this message can render
  iconUrl: string;  // small round avatar; same value as imageUrl, under the name the layouts use
  heroUrl: string;  // hero image; falls back to iconUrl when the message has no banner, so it's set for classic messages too
  carousel: Array<IInboxMessageSlide>;  // slides of the carousel layout; empty for every other layout
  customData: Record<string, unknown>;  // the campaign's own custom data, as sent from the control panel
}

sendDate is now a true UTC instant (v3.75.0+)

sendDate used to carry local wall-clock time labeled Z. Code that compensated for the old value by applying a timezone offset will now be off by that same offset — drop the compensation. The built-in widget is unaffected.

Cell layouts. A message renders as one of four layouts — classic, banner, captioned, or carousel — the same layouts the campaign preview in the control panel shows. A layout that can’t render with what the message carries degrades to classic: banner needs a hero image, captioned needs a hero image plus both a title and a body, and carousel needs at least one slide plus both a title and a body. layout on the public message is always the one actually drawn, already degraded.

Checking layout is the only reliable way to tell what a message will render as — heroUrl is set for classic messages too (see the field note above), so an integration must not use its presence to decide whether to draw a hero.

Public methods

Check out public methods’ descriptions in the Web Push SDK 3.0 guide.

Pushwoosh.pwinbox.syncMessages() pulls the current inbox from the server; call it to force a refresh outside the built-in widget’s own polling.