Enable proactive messages

Introduction

Proactive messages allow you to deliver targeted, timely notifications to your users through your mobile SDK channel based on pre-defined conditions. These messages can help drive engagement, provide support, and guide users through your app experience.

Proactive messaging is configured in Zendesk Admin Center and delivered as local push notifications to users who meet your campaign criteria.

See Creating proactive messages for mobile SDK channels for information on setting up a proactive messaging campaign. Complete those steps before following the integration steps below.

Use cases

Here are some common scenarios where proactive messaging can enhance user engagement:

• Targeted promotions: Notify users about special offers or discounts when they visit a specific screen or take a certain action.
• Reminders: Remind users to complete onboarding, finish a purchase, or return to an abandoned cart.
• Onboarding tips: Guide new users with helpful tips as they explore your app for the first time.
• Support nudges: Proactively offer help if a user appears stuck or visits a help-related screen.
• Feature announcements: Inform users about new features or updates relevant to their activity.

How proactive message delivery works

• Proactive messages are delivered as iOS local notifications when a user meets your campaign's conditions.
• The app must be in the foreground to receive and display proactive messages. If the app is in the background or closed, the user will not receive the proactive message notification.
• The Zendesk SDK for iOS requests notification permissions only when a proactive message is about to be displayed (if not previously prompted). If you want users to receive proactive messages earlier, request notification permissions proactively in your app flow (see code samples below).
• Proactive messaging campaigns are evaluated when triggered by the Page View Event integration. For each screen the user visits, ensure you update the page view event accordingly.

Limitations and important notes

• Proactive messages are not delivered if the app is in the background or closed.
• Notification permissions must be granted for messages to appear. On iOS, the Zendesk SDK requests notification permissions only when a proactive message is about to be displayed (if not previously prompted). If proactive messages are critical to your use case, consider requesting permissions early in your app flow (see code samples below).
• Campaigns are only evaluated when a page view event is sent from your app.
• When a user taps a proactive notification, any other existing proactive messages in the notification tray are cleared.

Example: If you have a campaign that triggers when a user is on a product screen for 30 seconds, but the user navigates away after 25 seconds and no subsequent page view event is sent, the user will not receive the proactive message notification.

Multi conversations behavior

If you enable the New conversation button in your Messaging channel in Admin Center, users will see a button in the SDK UI that allows them to start a new conversation. When this button is enabled, tapping on a new proactive message notification will create a new conversation.

If the option is disabled, tapping a proactive message notification adds the message to the most recently closed conversation instead of starting a new one.

Important: Proactive messages are only delivered when the end user has no active conversations. If the user has any active conversation sessions, proactive notifications will not be sent. For more details, see the Zendesk Proactive Messaging with multi conversations.

Code sample: Requesting notification permissions early

If you want to ensure users can receive proactive messages before a proactive message is triggered, request notification permissions proactively:

Swift (UIKit)

UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
    // Handle permission result
}

Objective-C (UIKit)

UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
[center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert + UNAuthorizationOptionSound + UNAuthorizationOptionBadge)
                      completionHandler:^(BOOL granted, NSError * _Nullable error) {
    // Handle permission result
}];

SwiftUI

import UserNotifications

@main
struct MyApp: App {
    init() {
        UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
            // Handle permission result
        }
    }
    // ...existing code...
}

Handling proactive message taps

To display the conversation view when a user taps a proactive message notification, implement the handleTap function inside your userNotificationCenter(_:didReceive:withCompletionHandler:) method. This ensures the Zendesk conversation view is presented in response to the notification tap.

Swift

PushNotifications.handleTap(userInfo) { viewController in
    // Handle displaying the returned viewController in here
}

Objective-C

[ZDKPushNotifications handleTap:userInfo completion:^(UIViewController * _Nullable viewController) {
    // Handle displaying the returned viewController in here
}];

You can find a demo app demonstrating this capability in our Zendesk SDK Demo app on GitHub.

FAQ

Q: Why aren't users receiving proactive messages when the app is in the background or closed?
A: Proactive messages are delivered as local notifications and require the app to be in the foreground. If the app is in the background or closed, the notification will not be shown.

Q: When are notification permissions requested by the Zendesk SDK?
A: By default, the SDK requests notification permissions when a proactive message is about to be displayed (if not previously prompted). If you want users to receive proactive messages earlier, request permissions proactively in your app.

Q: How are proactive message campaigns triggered?
A: Campaigns are evaluated when your app sends a page view event. If no event is sent, the campaign will not trigger, even if the user meets other criteria.

Q: Can I customize the appearance of proactive message notifications?
A: Proactive messages use standard iOS local notifications. You can customize notification appearance using standard iOS APIs and notification categories.

Q: Do proactive messages work with all iOS versions?
A: Proactive messages require notification permissions, which are handled differently on iOS 10+. Ensure you handle permission requests appropriately for your target iOS versions.

Q: Can I test proactive messages in development?
A: Yes. Set up a campaign in Zendesk Admin Center and use test users or test conditions. Make sure your app is in the foreground and sending page view events.

Related resources

• Creating proactive messages for mobile SDK channels (Zendesk Support)
• Page View Event integration
• Understanding the end-user experience with multi conversations for messaging (Zendesk Support)

For more advanced examples, see the Zendesk SDK Demo Apps.