Interactive notifications

Interactive notifications are push notifications that provide an option for end user to interact with application through button tap action. This interaction can be accomplished by using our predefined categories or creating your own.

Each category has its own ID and actions with their IDs. mm_ prefix is reserved for all predefined IDs and cannot be used for custom actions. Actions may bring app to foreground or leave it in the background.

Sending interactive notification

Interactive notifications can be tested through our Single PUSH message and Multiple PUSH messages APIs by using category parameter.

Mobile Originated (MO) messages

With Mobile Messaging SDK you can send messages to arbitrary destinations from mobile device. These messages are also known as Mobile Originated (MO) messages. Actionable notifications are one of use-cases for the MO service, meaning that you can trigger outgoing MO message with any of notification actions. For instance, if user taps the "Vote" button, a specific MO message is sent to your backend service. In order to create a notification action that triggers MO message, you should use moRequired: true for action within your category:

let voteAction = {
    identifier: 'vote',
    title: 'Vote',
    moRequired: true
};

Predefined categories

Mobile Messaging SDK provides one predefined interaction category for now, but this list will be extended.

Displaying of Interactive Notifications with predefined categories can be tested without any additional implementation on application side by sending message through Push API. Action handling needs to be implemented as described in the Notification action handling.

A = action

Category.id	A.id	A.title	A.foreground	A.authenticationRequired	A.destructive	A.moRequired
mm_accept_decline	mm_accept	Accept	true	true	false	true
	mm_decline	Decline	false	true	true	true

Notice

Mobile Messaging SDK provides localization for action button titles of predefined categories. Titles are localized for the following languages: Arabic, Czech, Danish, German, English, Spanish (Latin America), Spanish, Finnish, French, Hebrew, Croatian, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Norwegian, Dutch, Polish, Portuguese (Portugal), Portuguese, Romanian, Russian, Slovak, Swedish, Thai, Turkish, Vietnamese, Chinese (Simplified), Chinese (Traditional), Hindi.

Custom categories

Setting up custom categories enables you to configure interactive notification categories along with their actions.

System UI behaviour

• On Android/Huawei maximum of three (3) actions are shown in the default notification layout.
• On iOS
  • for the alert-style, maximum of four (4) actions are shown in the default notification mode. If there are more than four action objects provided, the system displays only the first four.
  • for the banner-style, notifications (on iOS 8-9) the system shows up the first two actions only.

For more details of how specific for platform actions looks like in UI, you can check native platforms docs: iOS, Android

Actions are displayed in the order they've been set (in the Creating custom category example, "cancel" action will be on the left, "share" action will be on the right).

Creating custom category

let cancelAction = { 
    identifier: 'cancel', 
    title: 'Cancel', 
    destructive: true 
};
let shareAction = { 
    identifier: 'share', 
    title: 'Share', 
    foreground: true, 
    authenticationRequired: true 
};
let replyAction = { 
    identifier: 'reply', 
    title: 'Reply', 
    foreground: true, 
    authenticationRequired: true,
    textInputActionButtonTitle: 'Send',
    textInputPlaceholder: 'Your message'
};
let category_share_cancel = { 
    identifier: 'category_share_cancel', 
    actions: [cancelAction, shareAction] 
};
let category_reply_cancel = { 
    identifier: 'category_reply_cancel', 
    actions: [cancelAction, replyAction] 
};
// Interactive notifications should be registered at the SDK initialization step by providing 'notificationCategories' configuration:
MobileMessaging.init({
    applicationCode: ...,
    android: ...,
    ios: ...,
    notificationCategories: [category_share_cancel, category_reply_cancel]
    },
    function(error) {
        console.log('Init error: ' + error.description);
    }
);

In order to handle the action or text input for 'reply' action, please take a look on Notification action handling.

API description

MobileMessaging.init({
    applicationCode: ...,
    android: ...,
    ios: ...,
    notificationCategories: [{ // a list of custom interactive notification categories that your application has to support
        identifier: <String; a unique category string identifier>,
        actions: [ // a list of actions that a custom interactive notification category may consist of
            {
                identifier: <String; a unique action identifier>,
                title: <String; an action title, represents a notification action button label>,
                foreground: <Boolean; to bring the app to foreground or leave it in background state (or not)>,
                textInputPlaceholder: <String; custom input field placeholder>,
                moRequired: <Boolean; to trigger MO message sending (or not)>,
                
                // iOS only
                authenticationRequired: <Boolean; to require device to be unlocked before performing (or not)>,
                destructive: <Boolean; to be marked as destructive (or not)>,
                textInputActionButtonTitle: <String; custom label for a sending button>,
                
                // Android only
                icon: <String; a resource name for a special action icon>
            }
            ...
        ]
    }]
    },
    function(error) {
        console.log('Init error: ' + error.description);
    }
);
...

Notification action handling

Tapping the action will trigger actionTapped event where you can act upon the received action identifier.

For predefined category 'mm_accept_decline' you can handle 'mm_accept' action like this:

MobileMessaging.register('actionTapped', function (message, actionId, text) {
    // handle 'mm_accept' action of predefined category
    if (message.category === 'mm_accept_decline' && actionId === 'mm_accept') {
        utils.log('Accept button was pressed for message: ' + JSON.stringify(message));
        return;
    }
    // handle 'share' action of custom category
    if (message.category === 'category_share_cancel' && actionId === 'share') {
        utils.log('Share button was pressed for message: ' + JSON.stringify(message));
        return;
    }
    // handle text input action
    if (message.category === 'category_reply_cancel' && actionId === 'reply') {
        utils.log('User responded with text: ' + text);
        return;
    }
});