Documentation > Cordova

Inbox

Inbox is an optional feature. If you're interested, please contact us.

Introduced in Batch 2.0, the Inbox API allows you to fetch and process notifications that this user has previously received, even if their device was offline.
You can then do anything you want with the data, such as making a "notification center", where the user can catch up with previous notifications in a list:

Inbox android example

This screenshot is an example of what you can achieve with the Inbox API, but Batch does not include any UI.

The API gives you access to the entire notification, including its raw payload. It also lets you know if the notification has already been read.

Note: Just keep in mind that, once received/stored in the inbox your push notifications will remain for a 3 months period.

Let's get started!

Picking the right mode

The Inbox API has two modes:

  • Installation
    This mode will fetch notifications that the current app installation, and nothing else. If the user clears the app's data, this inbox will be cleared.
    This is great for applications where your users don't have to log in.
    This may cause privacy issues if your app has an identification system.
  • User
    This mode will fetch notifications for the specified custom user ID, even if they just installed the application and already got notifications on another device logged in with the same user identifier.
    If your application has a login system, this is the mode you should use.

Installation mode

In this mode, you can simply call the Inbox fetch method:

batch.inbox.fetchNotifications(function (error, notifications) {
    // error is an optional Error instance
    // notifications is an optional array of InboxNotification, as described below

    if (!error && notifications) {
        notifications.forEach(n => {
            console.log("Got a notification", n.title, n.body);
        });
    }
})

Custom User ID mode

Since notifications can have sensitive content, you cannot get a user's notifications simply with their user identifier: Batch requires you to authenticate your request.

Getting your authentification key

First, you will need your inbox secret key. You will find that in your dashboard, below your API Keys. It is unique for every app.

Inbox secret dashboard screenshot

The authentification key is generated by computing a sha256 hmac hash of the API Key and the user identifier, using the secret as the key. Then, you have to encode the hash in a hexadecimal string.

For example, in PHP, that would be:

hash_hmac("sha256", $APP_API_KEY . $USER_ID, $INBOX_SECRET)

For the API Key "abcdef", user identifier "paul", and secret of "foobar", the expected authentication key would be 796f1ab5d119d1b2eab8201e60335b56d1befff40c0f80263d64a169a8fd2e45.

Important note: This hash HAS to be computed on your server. If you bundle the inbox secret in your application to compute the hash, attackers will be able to extract it, and read the notifications of any of your users

Fetching notifications

Now, call the fetchNotificationsForUserIdentifier method, with your Custom User ID and authentification key:

batch.inbox.fetchNotificationsForUserIdentifier("paul",
  "796f1ab5d119d1b2eab8201e60335b56d1befff40c0f80263d64a169a8fd2e45",
  function (error, notifications) {
    // error is an optional Error instance
    // notifications is an optional array of InboxNotification, as described below

    if (!error && notifications) {
        notifications.forEach(n => {
            console.log("Got a notification", n.title, n.body);
        });
    }
})

Reading notification content

Once you've fetched notifications, you will end up with a list of InboxNotification objects.

These objects have everything you need to display these notifications:

  • Title
  • Body
  • Send Date
  • Read state
  • Source (Campaign API/Dashboard or Transactional API)
  • Payload, in both Raw and Batch wrapped forms

Here is their typescript definition:

/**
 * Notification model from the Inbox module
 */
interface InboxNotification {
  /**
   * Unique notification identifier. Do not make assumptions about its format: it can change at any time.
   */
  identifier: string;

  /**
   * Notification title (if present)
   */
  title?: string;

  /**
   * Notification alert body
   */
  body: string;

  /**
   * URL of the rich notification attachment (image/audio/video) - iOS Only
   */
  iOSAttachmentURL?: string;

  /**
   * Raw notification user data (also called payload)
   */
  payload: any;

  /**
   * Date at which the push notification has been sent to the device
   */
  date: Date;

  /**
   * Flag indicating whether this notification is unread or not
   */
  isUnread: boolean;

  /**
   * The push notification's source, indicating what made Batch send it. It can come from a push campaign via the API or the dashboard, or from the transactional API, for example.
   */
  source: InboxNotificationSource;
}

/**
 * Inbox Notification Source enum.
 * A notification source represents how the push was sent from Batch: via the Transactional API, or using a Push Campaign
 *
 * To be used with batch.inbox fetched notifications. This enum's implementation is available on batch.inbox.NotificationSource.
 */
enum InboxNotificationSource {
  UNKNOWN = 0,
  CAMPAIGN = 1,
  TRANSACTIONAL = 2
}

Note: The raw payload should be used carefully on keys you do not control:
- "com.batch" is Batch's internal payload: You should not make any assumption about its content, nor depend on it. We reserve the right to change it at anytime, without warning.
- Standard parsing good practices apply: Make sure to check every type and handle errors gracefully, and never assume anything about the payload's content.