Enabling 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 Android 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 Android requests notification permissions only when the user opens the conversation screen (if not previously prompted). If you want proactive messages to display before the conversation screen is opened, request notification permissions earlier in your app flow.
• 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. Consider requesting permissions early if proactive messages are critical to your use case.
• 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 opening the conversation screen, request notification permissions proactively:

Kotlin (Jetpack Compose)

val context = LocalContext.current as Activity

LaunchedEffect(Unit) {
    ActivityCompat.requestPermissions(
        context,
        arrayOf(Manifest.permission.POST_NOTIFICATIONS),
        REQUEST_CODE_NOTIFICATIONS
    )
}

Kotlin (Classic Views)

// In your Activity or Fragment
ActivityCompat.requestPermissions(
    this,
    arrayOf(Manifest.permission.POST_NOTIFICATIONS),
    REQUEST_CODE_NOTIFICATIONS
)

Java

// In your Activity or Fragment
ActivityCompat.requestPermissions(
    this,
    new String[]{Manifest.permission.POST_NOTIFICATIONS},
    REQUEST_CODE_NOTIFICATIONS
);

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 the user opens the conversation screen. If you want users to receive proactive messages earlier, request permissions proactively in your app (see code samples above).

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 Android local notifications. You can customize notification channels and appearance using standard Android APIs.

Q: Do proactive messages work with all Android versions? A: Proactive messages require notification permissions, which are handled differently on Android 13+ (API 33+). Ensure you handle permission requests appropriately for your target API levels.

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.