Inbox

Inbox allows you to communicate with all active mobile users without dependency on possible poor push deliverability or users not paying attention to their push notifications.

Notice

Method for fetching the inbox uses authorization. Secure authorization is required for production applications. Read about the details of inbox authorization in the following article

Installing Inbox components

Since Cordova version 5.0.0 Inbox is supported by default.

Fetching Inbox messages

Inbox messages can be fetched only by personalized users (learn more about personalization here). It is important to mention that only personalization by External User Id is supported, however, since this Id can be any meaningful string, you can specify a unique users Phone number or Email as an External User Id but keep in mind that this is the case-sensitive data.

Mobile Messaging Inbox SDK provides two APIs for fetching messages:

• API that requires user to be authenticated (uses access token based authorization)

  MobileMessaging.fetchInboxMessages(
      "<# token - your JWT in Base64 #>", 
      "<# externalUserId - some user Id #>", 
      null, // for more details about this field visit Filtering options section below
      function(data) {}, //success callback
      function(err) {});  //error callback

  This API is more secure and should be used in production although it requires additional effort to be used. This API requires a securely signed JWT (JSON Web Token encoded in Base64 format) in order to pass authentication on Infobip's server side (See how to generate JWT). In order to enable this API, choose the "JSON Web Token (JWT)" radio button in "Inbox authorization type" section on your App Profile configuration page.

• API that does not require user to be authenticated (uses application code based authorization)

  MobileMessaging.fetchInboxMessagesWithoutToken(
      "<# externalUserId - some user Id #>", 
      null, // filterOptions
      function(data) {}, //success callback
      function(err) {}); //error callback

  This API only works for Sandbox App Profiles (make sure you have created a Sandbox App Profile on Infobip Portal and should be used only for testing and demo purposes. It has no additional requirements and it's simple to use. In order to enable this API for your App Profile choose the "Application code" radio button in "Inbox authorization type" section on your App Profile's configuration page.

Structure of response data

As a return for a call to fetchInboxMessages or fetchInboxMessagesWithoutToken you will get a JSON object with the following structure:

    {
      "messages": "<# list of messages #>",
      "countTotal":1,
      "countUnread":0
  }

So, as a result, aside of list of messages, you will also receive two additional fields: countTotal and countUnread.

You can access fields in response as:

    MobileMessaging.fetchInboxMessages(
        "<# token - your JWT in Base64 #>",
        "<# externalUserId - some user Id #>",
        null, // filterOptions
        function(data) {
            console.log(data.countTotal);
            console.log(data.countUnread);
            console.log(data.messages); //list of messages
        },
        function(err) {});  //error callback

Possible errors responses

You need to be very cautious about the Infobip server response when fetching users messages using JWT token based authorization.

"UNAUTHORIZED"

There are many reasons why you might get "UNAUTHORIZED" error response from Infobip backend. For security reasons, we don't disclose any details about the error, so you need to be even more cautious. One of the most common reasons for that error are:

• Expiration of the JWT token. You always have to use "fresh" token and reissue the new one in case of expiration happened or is about to happen.
• Invalid JWT token payload (missing mandatory claims or headers, typos).
• Wrong Application Code that is used to generate the JWT token. It's easy to make mistake when you have multiple App Profiles.
• Invalid secret key used for signing (a typo occurred or the key could have been revoked by you/your colleagues on App Profile page).

The complete information about the JWT token requirements and implementation details can be found here.

The following example demonstrates, how you can recognize and handle the "UNAUTHORIZED" error:

    MobileMessaging.fetchInboxMessages(
        "<# token - your JWT in Base64 #>",
        "<# externalUserId - some user Id #>",
        null, // filterOptions
        function(data) {}, function(err) {
          if (err === "UNAUTHORIZED") {
            //TODO: I'm pretty sure the JWT token payload is correct here,
            // it's just the token got expired,
            // I will call my backend to reissue the fresh token for me and try again.")
          }
        });

"ACCESS_TOKEN_MISSING"

Another error response that you might face is "ACCESS_TOKEN_MISSING". This error means that in your App Profile page it has been set up to use "JSON Web Token (JWT)" for Inbox authorization, thus in your mobile app, you need to switch to the JWT token based Inbox API: use MobileMessaging.fetchInboxMessages(token:externalUserId:filters:callback:errorCallback:) instead of MobileMessaging.fetchInboxMessagesWithoutToken(externalUserId:filters:callback:errorCallback:).

The complete information about the JWT token requirements and implementation details can be found here.

Filtering options

You can specify the following filtering options to fetch Inbox messages. Expected date format is yyyy-MM-dd'T'HH:mm:ssZZZZZ:

• filtering by particular time interval to get messages with sendDateTime greater than or equal MobileInboxFilterOptions.fromDateTime and less than MobileInboxFilterOptions.toDateTime. By default or in case of null, filter by date/time is not applied. For example the following fetchInboxMessages call would return Inbox messages sent for one day:

    const filterOptions = {
        fromDateTime: "2024-03-11T12:00:00+01:00",
        toDateTime: "2024-03-20T12:00:00+01:00",
        topic: null,
        limit: null
    };
    
    MobileMessaging.fetchInboxMessages(
        "<# token - your JWT in Base64 #>",
        "<# externalUserId - some user Id #>",
        filterOptions,
        function(data) {}, //success callback
        function(err) {});  //error callback

• filtering by a specific topic can be handy if you have a specific UI/UX approach to separate messages by different topics. By default or in case of null, filter by topic is not applied.

    const filterOptions = {
      fromDateTime: null,
      toDateTime: null,
      topic: "myPromoTopic",
      limit: null
    };

    MobileMessaging.fetchInboxMessages(
       "<# token - your JWT in Base64 #>",
       "<# externalUserId - some user Id #>",
       filterOptions,
       function(data) {}, //success callback
       function(err) {});  //error callback

• limiting the maximum number of messages that will be returned by Infobip server. By default or in case of null, server returns 20 messages as maximum. This one together with filtering by toDateTime is useful when you need to implement pagination that might help reducing mobile data usage and fetch messages by chunks. For example, the following listing shows how to fetch whole inbox by chunks of 10 messages, one by one, from the most recent to the oldest:

    const inboxMessages = [];
    const toDateTime = "2024-01-01T12:00:00+01:00"; //for example: if we take as this date to be oldest message timestamp
    const chunkMessagesFilter = {
      fromDateTime: null,
      toDateTime: toDateTime,
      topic: null,
      limit: 10
    };

    MobileMessaging.fetchInboxMessages(
            "<# token - your JWT in Base64 #>",
            "<# externalUserId - some user Id #>",
            chunkMessagesFilter,
            function(data) {
              inboxMessages = [];
              for (var i = 0; i < data.messages.length; i++) {
                inboxMessages.push(data.messages[i]);
              }
                // Further processing with inboxMessags
            },
            function(err) {});  //error callback

Marking Inbox messages as seen/read

You can mark Inbox messages as seen/read using the following API:

    const messageIds = ['messageId_1', 'messageId_2', 'messageId_3']; //list of message Ids that you consider as seen by the end user
    
    MobileMessaging.setInboxMessagesSeen(
       "<# externalUserId - some user Id #>",
       messageIds,
       function(data) {}, //success callback
       function(err) {});  //error callback