Inbox

Inbox allows you to communicate with all active mobile users without dependency on poor push performance 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

Notice

If you'd like to use Swift Package Manager, check Integration via Swift Package Manager guide

In order to add Inbox module into your application using CocoaPods, add MobileMessaging/Inbox dependency in your Podfile:

pod 'MobileMessaging/Inbox'

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.

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, generate JSON Web Token (JWT) for inbox at App Profile configuration page by navigating to "JWT private keys for mobile app inbox" and press "Generate key".

    MobileMessaging.inbox?.fetchInbox(
        token: String,
        externalUserId: String,
        options: MMInboxFilterOptions?,
        completion: (_ inbox: MMInbox?, _ error: NSError?) -> Void)

For Sandbox App Profiles we also provide API that does not require user to be authenticated (uses application code based authorization):

    MobileMessaging.inbox?.fetchInbox(
        externalUserId: String,
        options: MMInboxFilterOptions?,
        completion: (_ inbox: MMInbox?, _ error: NSError?) -> Void)

This API has no additional requirements authorization and simple to use, but can be used only for testing and demo purposes. 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.

See more code examples in the following sections of this document.

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.inbox?.fetchInbox(
    token: <# your JWT in Base64 #>,
    externalUserId: <# some user Id #>,
    options: <# filtering options or nil #>,
    completion: { inbox, error in
        if (error.mm_code == "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.inbox.fetchInbox(token:externalUserId:options:completion:) instead of MobileMessaging.inbox.fetchInbox(externalUserId:options:completion:).

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:

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

  let now = Date()
  let calendar = Calendar.current
  let startTime = calendar.startOfDay(for: now)
  let todaysMessagesFilter = MMInboxFilterOptions(fromDateTime: startTime, toDateTime: now, topic: nil, limit: nil)
  MobileMessaging.inbox?.fetchInbox(
      token: <# your JWT in Base64 #>,
      externalUserId: <# some user Id #>,
      options: todaysMessagesFilter,
      completion: { inbox, error in
          // handle error or get inbox data:
          println("Total number of messages", inbox?.countTotal)
          println("Total number of unread messages", inbox?.countUnread)
          println("Fetched messages", inbox?.messages)
      })

• 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 nil, filter by topic is not applied.

  let promoMessagesFilter = MMInboxFilterOptions(topic: "myPromoTopic")
  MobileMessaging.inbox?.fetchInbox(
      token: <# your JWT in Base64 #>,
      externalUserId: <# some user Id #>,
      options: promoMessagesFilter,
      completion: { inbox, error in
          // handle error or get inbox data:
          println("Total number of messages", inbox?.countTotal)
          println("Total number of unread messages", inbox?.countUnread)
          println("Fetched messages", inbox?.messages)
      })

• limiting the maximum number of messages that will be returned by Infobip server. By default or in case of nil, 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:

  fileprivate var myMessages: [MM_MTMessage] = []
  
  ...
  
  let oldestMessageDate = myMessages.last?.sendDateTime
  let toDateTime = oldestMessageDate == nil ? nil : Date.init(timeIntervalSince1970: oldestMessageDate!)
  let chunkMessagesFilter = MMInboxFilterOptions(fromDateTime: nil, toDateTime: toDateTime, topic: nil, limit: 10)
  MobileMessaging.inbox?.fetchInbox(
      token: <# your JWT in Base64 #>,
      externalUserId: <# some user Id #>,
      options: chunkMessagesFilter,
      completion: { inbox, error in
          if let inbox = inbox {
              self.myMessages = self.myMessages + inbox.messages
          }
      })

Marking Inbox messages as seen/read

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

let messageIds = <# list of message Ids that you consider as seen by the end user #>
MobileMessaging.inbox?.setSeen(
    externalUserId: <# some user Id #>,
    messageIds: messageIds,
    completion: { error in
        // retry the call if error occurs
})