Skill Level: Beginner

Customizing your inbox notifications with templates.


There are three templates you can choose from to customize your inbox notifications. Keep in mind that you only need to implement the templates that you want to support.

  • MCEInboxActionPlugin: An incoming mobile app message that includes the openInboxMessage action, which opens up the specified message.
  • MCEInboxPostTemplate: A post-style message with the following features: optional title image, title, message, optional video or image, and optional extra text to follow the video or image. An optional set of up to three action buttons is included in this plug-in.
  • MCEInboxDefaultTemplate: A simple HTML message with a subject and date display.

To implement inbox notifications, the template classes should be NSObject subclasses that implement the MCETemplate protocol. They register with MCETemplateRegistry in the application:didFinishLaunchingWithOptions: method of the AppDelegate as plug-ins that register with MCEActionRegistry in the same place. The template class is responsible for providing UITableViewCell subclass objects that implement the MCETemplatePreview protocol to display message previews. The template class also must supply UIViewController subclass objects that implement the MCETemplateDisplay protocol to display the full page content of the messages. The task of listing the messages and navigating to the full page view of them is handled by the MCEInboxTableViewController.

Server limits on inbox sync API calls

The server limits the frequency of inbox sync API calls. This limit can vary per customer. For the exact value for your organization, contact IBM Support. 

SDK limits on inbox sync API calls

  • The inbox sync rules are enforced by the server. Additional limits are enforced on inbox sync API calls by the SDK. If you use the inbox sync API to sync inbox messages, the minimum interval between calls is 5 minutes for a regular sync. For example, if you use the SDK API to sync inbox messages every time the mobile user opens the inbox, the SDK allows only one call to the server every 5 minutes, regardless of the number of times the API is called.
  • If you call the inbox sync too often, the SDK returns the following error:

    userInfo : { ‘error’: ’empty’}

  • There are no limits for notifications with an openInboxMessage action that contains a message that is not in the SDK database.

 For information about other mobile app messages features in iOS apps, see the Documentation.



  1. Initialize files in the AppDelegate.

    Drag all the files in the inbox plugin folder into the project, and initialize them in the AppDelegate.

    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [MCEInboxActionPlugin registerPlugin];
    [MCEInboxPostTemplate registerTemplate];
    [MCEInboxDefaultTemplate registerTemplate];
  2. Set view controller class

    Set one of the view controller classes to MCEInboxTableViewController. The rest of the interactions are automatically handled by that class. You can customize the templates or create new templates based on the protocol and class requirements.Set

  3. To restrict expired messages from displaying in the inbox, use the following code:

    MCEInboxDefaultTemplate.m class
    -(BOOL)shouldDisplayInboxMessage: (MCEInboxMessage*)inboxMessage
    /* This would not allow the inbox to open messages that are expired */
    //if([inboxMessage isExpired])
    // return FALSE;
    return TRUE;
  4. To remove expired messages from the inbox, add the following code to MCEInboxTableViewController.m:


    in method -(void)smartUpdateMessages:(NSMutableArray*)inboxMessages
    // create a single unified list of all the messages
    NSMutableArray * allMessages;
    allMessages = [inboxMessages mutableCopy];
    allMessages = [NSMutableArray array];
    for (MCEInboxMessage * message in inboxMessages)
    if([message isExpired])
    [message delete];
    [allMessages addObject:message];
    inboxMessages = [allMessages mutableCopy];

  5. Example: payload template

    Inbox template for images and videos:

    The following payload example shows you an inbox notification template that supports images and videos.

    "template": "post",
    "contentVideo":"video stream url here",
    "contentImage":"content image url here",
    "header":"Header here",
    "subHeader":"sub header here",
    "headerImage":"header image url here",
    "contentText":"content text",
    "actions":[{"name":"ibm.co", "type":"url", "value":"http://ibm.co"}, {"name":"dial", "type":"dial", "value":"18884266840"}, {"name":"yahoo", "type":"url", "value":"http://yahoo.com"}] }

    Inbox default template:

    The following payload example shows you the default inbox notification template.

    "template": "default",
    "subject": "Subject here",
    "previewContent": "Preview content here"
    "richContent": "<b>html message here</b><br><br><a href='actionid:offer-link-1'>Click here!</a>",
    "actions": { "offer-link-1" : {"type": "url", "value": "http://ibm.com/offer" } }

Expected outcome

Supporting larger screens with inbox notifications:
On the iPhone 6 Plus and larger screens, you might not want to have a full page display of the message, which MCEInboxTableViewController navigates. You may want to have the selection of a message open in a different view controller and not navigate from the message list. This can be accomplished by sending an NSNotification message with the name setContentViewController and UIViewController subclass you want to display full page messages in as the object. This overrides the navigation in MCEInboxTableViewController and adds the content to the specified UIViewController subclass object.

For information about other mobile app messages features in iOS apps, see the Documentation.

Go Back to the Mobile App Messaging home page.

Join The Discussion

Your email address will not be published. Required fields are marked *