Mobile SDK Push Notifications

Enable push notifications to alert users when they receive new messages, even when your app is in the background.

Overview

Helplane uses OneSignal for push notifications. When an agent replies to a conversation and the user doesn't have the app open, they'll receive a push notification.

Prerequisites

• A OneSignal account (onesignal.com)
• OneSignal app configured for iOS and/or Android
• OneSignal App ID from your OneSignal dashboard
• Helplane mobile SDK integrated in your app

How It Works

• User opens chat and a session is established
• Your app registers the user with OneSignal using a special external ID
• When an agent sends a message, Helplane sends a push via OneSignal
• User taps the notification to open the conversation

The external ID format is contact_{uuid} where the UUID is the Helplane contact identifier.

iOS Setup

1. Install OneSignal

Add to your Podfile:

pod 'OneSignalXCFramework', '~> 5.0'

2. Initialize OneSignal

import OneSignalFramework
import HelpLaneSDK
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialize OneSignal
        OneSignal.initialize("YOUR_ONESIGNAL_APP_ID")
        OneSignal.Notifications.requestPermission({ accepted in
            print("Push permission: \(accepted)")
        }, fallbackToSettings: true)
        // Initialize Helplane
        HelpLane.configure(brandToken: "your-brand-token")
        return true
    }
}

3. Login After Chat Session

After the chat session is established (when you receive the contact UUID):

import HelpLaneSDK
import OneSignalFramework
// When chat session starts and you have the contact UUID
func onChatSessionStarted(contactUUID: String) {
    let externalId = HelpLanePush.login(contactUUID: contactUUID)
    OneSignal.login(externalId)
}
// On logout
func onUserLogout() {
    HelpLanePush.logout()
    OneSignal.logout()
}

4. Handle Notification Taps

class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationClickListener {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        OneSignal.Notifications.addClickListener(self)
        // ... rest of initialization
    }
    func onClick(event: OSNotificationClickEvent) {
        let data = event.notification.additionalData ?? [:]
        if HelpLanePush.isHelpLaneNotification(data) {
            if let conversationId = HelpLanePush.getConversationId(data) {
                // Navigate to chat screen
                openChat(conversationId: conversationId)
            }
        }
    }
}

Android Setup

1. Install OneSignal

Add to your build.gradle.kts:

dependencies {
    implementation("com.onesignal:OneSignal:5.1.6")
}

2. Initialize OneSignal

import com.onesignal.OneSignal
import io.helplane.sdk.HelpLane
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // Initialize OneSignal
        OneSignal.initWithContext(this, "YOUR_ONESIGNAL_APP_ID")
        // Request notification permission (Android 13+)
        CoroutineScope(Dispatchers.IO).launch {
            OneSignal.Notifications.requestPermission(true)
        }
        // Initialize Helplane
        HelpLane.configure(
            context = this,
            brandToken = "your-brand-token"
        )
    }
}

3. Login After Chat Session

import io.helplane.sdk.HelpLanePush
import com.onesignal.OneSignal
// When chat session starts
fun onChatSessionStarted(contactUUID: String) {
    val externalId = HelpLanePush.login(contactUUID)
    OneSignal.login(externalId)
}
// On logout
fun onUserLogout() {
    HelpLanePush.logout()
    OneSignal.logout()
}

4. Handle Notification Taps

import com.onesignal.notifications.INotificationClickListener
import com.onesignal.notifications.INotificationClickEvent
import io.helplane.sdk.HelpLanePush
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        OneSignal.Notifications.addClickListener(object : INotificationClickListener {
            override fun onClick(event: INotificationClickEvent) {
                val data = event.notification.additionalData ?: return
                if (HelpLanePush.isHelpLaneNotification(data)) {
                    val conversationId = HelpLanePush.getConversationId(data)
                    if (conversationId != null) {
                        // Navigate to chat screen
                        openChat(conversationId)
                    }
                }
            }
        })
    }
}

React Native Setup

1. Install OneSignal

npm install react-native-onesignal

2. Initialize and Configure

import { OneSignal } from 'react-native-onesignal';
import { HelpLaneProvider, HelpLanePush } from '@helplane/react-native';
export default function App() {
  useEffect(() => {
    // Initialize OneSignal
    OneSignal.initialize('YOUR_ONESIGNAL_APP_ID');
    OneSignal.Notifications.requestPermission(true);
    // Handle notification taps
    OneSignal.Notifications.addEventListener('click', (event) => {
      const data = event.notification.additionalData || {};
      if (HelpLanePush.isHelpLaneNotification(data)) {
        const conversationId = HelpLanePush.getConversationId(data);
        if (conversationId) {
          // Navigate to chat screen
          navigation.navigate('Chat', { conversationId });
        }
      }
    });
  }, []);
  return (
    <HelpLaneProvider
      brandToken="your-brand-token"
      onSessionStart={(contactUUID) => {
        // Login to OneSignal when chat session starts
        const externalId = HelpLanePush.login(contactUUID);
        OneSignal.login(externalId);
      }}
    >
      <YourApp />
    </HelpLaneProvider>
  );
}
// On logout
function handleLogout() {
  HelpLanePush.logout();
  OneSignal.logout();
}

Notification Data

Helplane push notifications include these data fields:

Testing

• Open your app and start a chat conversation
• Send a message to create a contact
• Close the app completely
• From the Helplane dashboard, send a reply as an agent
• You should receive a push notification

Troubleshooting

No notifications received:

• Verify OneSignal App ID is correct
• Check that OneSignal.login() was called with the correct external ID
• Verify push permissions are granted
• Check OneSignal dashboard for delivery status

Wrong user receives notification:

• Ensure you call OneSignal.logout() when users log out
• Verify the contact UUID is correct

Notifications not opening chat:

• Check that the click listener is properly configured
• Verify the notification data contains conversation_id