@netomi.com/netomi-chat-react-native

A React Native wrapper for the Netomi Mobile Chat SDK, enabling seamless integration of Netomi’s Agentic AI Chat Interface into Android and iOS applications.

Features

• ✅ iOS & Android native SDK bridge
• ✅ Typed configuration APIs (TypeScript)
• ✅ JWT-based authentication & reauthorization flow
• ✅ Custom UI theming (header, footer, bubbles, alerts, terms)
• ✅ Push notifications (FCM / APNs)
• ✅ Session control (hide / resume / destroy)
• ✅ SDK → App event bridge
• ✅ Animation control
• ✅ Optional iOS audio-session control

Requirements

Platform Requirements

| Platform | Minimum Version | | ---------------- | -------------------------- | | iOS | 16.0+ | | Android | API 26+ (Android 8.0 Oreo) | | React Native | 0.60+ |

iOS Requirements

• iOS Deployment Target: 16.0 or higher
• Xcode: 26.0 or newer
• Swift: 5.9+
• CocoaPods: For dependency management

Note: The Netomi Mobile Chat SDK requires iOS 16.0 or later. Ensure your app's deployment target meets this requirement.

Optional iOS Analytics

The React Native package installs NetomiChatReactNative/Core by default. To include optional Netomi analytics on iOS, add the analytics subspec in your app's ios/Podfile:

pod 'NetomiChatReactNative/Analytics'

Android Requirements

• Android Studio: 2022.2 (Chipmunk) or newer
• minSdkVersion: 26 or higher (Android 8.0 Oreo)
• Gradle Version: 8.6 or higher
• Kotlin: The Netomi SDK is written in Kotlin
• Java: JDK 11 or higher

Prerequisites

• Bot Credentials: You must have a botRefId and environment (e.g., us, sg, eu, qa, etc.) provided by Netomi

Installation

npm install @netomi.com/netomi-chat-react-native

Environment Constants (Recommended)

import NetomiChat, {
  NETOMI_ENV,
  type NetomiEnvironment,
} from '@netomi.com/netomi-chat-react-native';

const env: NetomiEnvironment = NETOMI_ENV.QA;

Supported values:

'us' | 'sg' | 'eu' | 'qa' | 'qaint' | 'dev';

Basic Usage

import NetomiChat from '@netomi.com/netomi-chat-react-native';

// Initialize once (e.g. App.tsx)
NetomiChat.initialize('botRefId', 'qa');

// Optional dynamic environment initialization
NetomiChat.initialize('botRefId', 'qa', true);

// Check initialization state
const initialized = await NetomiChat.isInitialized('botRefId', 'qa');
const dynamicInitialized = await NetomiChat.isInitialized(
  'botRefId',
  'qa',
  true
);

// Launch chat
await NetomiChat.launch(null);

// Launch with query
await NetomiChat.launchWithQuery('hello', null);

Authentication (JWT)

await NetomiChat.launch('your-jwt-token');

JWT can also be sent dynamically during runtime via SDK events (see Events section).

Push Notifications

NetomiChat.setPushToken('your-fcm-or-apns-token');

Tracking Consent

NetomiChat.setTrackingConsent('granted'); // pending | granted | not_granted

This API is currently iOS-only. It is safely ignored on Android.

Initial Menu

Call before launch or launchWithQuery to override the initial menu.

NetomiChat.setInitialMenu({
  header: 'How can we help?',
  menuItems: [
    { name: 'orders', label: 'Orders' },
    { name: 'returns', label: 'Returns' },
  ],
});

NetomiChat.clearInitialMenu();

UI Configuration APIs

Header

NetomiChat.updateHeaderConfiguration({
  backgroundColor: '#123456',
  gradientColors: ['#FF0000', '#00FF00'],
  isGradientApplied: true,
  iconBackgroundColor: '#CCCCCC',
  isBackPressPopupEnabled: false,
  tintColor: '#FFFFFF',
});

Chat Window

NetomiChat.updateChatWindowConfiguration({
  chatWindowBackgroundColor: '#000000',
});

Message Bubble

NetomiChat.updateBubbleConfiguration({
  borderRadius: 16,
  timeStampColor: '#333333',
});

Bot Messages

NetomiChat.updateBotConfiguration({
  backgroundColor: '#F1F1F1',
  botImage: 'https://example.com/bot.png',
  textColor: '#000000',
  quickReplyBackgroundColor: '#E0E0E0',
  quickReplyBorderColor: '#CCCCCC',
  quickReplyTextColor: '#333333',
});

User Messages

NetomiChat.updateUserConfiguration({
  backgroundColor: '#D1ECF1',
  textColor: '#0C5460',
});

Footer

NetomiChat.updateFooterConfiguration({
  backgroundColor: '#FFFFFF',
  inputBoxBackgroundColor: '#F0F0F0',
  inputBoxTextColor: '#000000',
  isFooterHidden: false,
  isNetomiBrandingEnabled: true,
  netomiBrandingText: 'Powered by Netomi',
  netomiBrandingTextColor: '#888888',
  tintColor: '#00AEEF',
});

Other UI

NetomiChat.updateOtherConfiguration({
  titleColor: '#111111',
  descriptionColor: '#444444',
  backgroundColor: '#FFFFFF',
  returnLaterEnabled: true,
  openLinkInWebview: true,
});

Alerts & Terms UI

NetomiChat.updateAlertsConfiguration({
  highAlert: { titleColor: '#ff0000' },
  mediumAlert: { titleColor: '#ffaa00' },
});

NetomiChat.updateTermsConfiguration({
  titleColor: '#000',
  confirmButtonTextColor: '#fff',
});

API Headers

NetomiChat.updateApiHeaderConfiguration({
  sdkVersion: '1.0.0',
  customHeaders: {
    'x-tenant-id': 'tenant123',
    'x-feature-flag': 'true',
  },
});

Session Control

Hide vs Destroy

• hide → closes UI, keeps session alive
• destroy → closes UI + clears session

await NetomiChat.hideChat('hide');
await NetomiChat.hideChat('destroy');
await NetomiChat.resumeChat();
NetomiChat.clearChatSession();

Check visibility:

const visible = await NetomiChat.isChatVisible();

Animations

await NetomiChat.launch(null, {
  animationType: 'fade', // system | fade | slide | scale | none
  durationMs: 300,
});

Default:

{ animationType: 'system', durationMs: 300 }

Events (SDK → App)

const stop = NetomiChat.getEventUpdatesFromSDK((event) => {
  console.log('SDK Event:', event);
});

// unsubscribe
stop();

Common Events

• reauthorization_request
• reauthorization_success
• reauthorization_failure
• custom

Send events to SDK:

await NetomiChat.sendEventToSdk('reauthorization_success', 'jwt-token', null, {
  source: 'app',
});

await NetomiChat.sendEventToSdk('custom', null, 'html_state_update', {
  status: 'submitted',
  custom_attributes: {
    formId: 'feedback_form',
  },
});

Custom Parameters

NetomiChat.sendCustomParameter('key', 'value');

NetomiChat.setCustomParameters({
  a: '1',
  b: '2',
});

setCustomParameters replaces the existing custom parameter map.

Logging

NetomiChat.setupLogging('info'); // none | error | info

iOS Audio Session (iOS only)

NetomiChat.configureAudioSession({
  forceSpeakerOutput: true,
  disableSessionControl: false,
});

⚠️ No-op on Android.

ProGuard / R8 (Android)

If you are using ProGuard or R8 in your React Native Android project, make sure to include the following rules in your proguard-rules.pro file to prevent essential classes from being obfuscated or removed. These rules ensure proper functioning of React Native, Netomi Chat SDK, Retrofit, Kotlin coroutines, and MQTT logging.

Add to android/app/proguard-rules.pro:

# React Native
-keep class com.facebook.react.** { *; }
-keep class com.facebook.hermes.** { *; }

# Netomi Chat SDK
-keep class com.netomi.** { *; }
-keep class com.netomichat.** { *; }

# SSL / Conscrypt
-keep class org.conscrypt.** { *; }
-dontwarn org.conscrypt.**

# Retrofit / Coroutines
-keep,allowobfuscation,allowshrinking class retrofit2.Response
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation

#MQTT Logging used by AWS
-keepclassmembers class org.eclipse.paho.client.mqttv3.logging.** { *; }

# Gson
-keepnames class * {
  @com.google.gson.annotations.SerializedName <fields>;
}

Why this is needed:

1. Netomi SDK classes must be preserved to ensure chat functionality and SDK integration.
2. Retrofit and Kotlin coroutine rules allow async API communication without breaking due to class shrinking or obfuscation.
3. Gson rules ensure JSON serialization and deserialization work correctly using annotations.
4. MQTT logging is required for debug and diagnostic messages related to chat services.

Add this to your android/app/proguard-rules.pro file if ProGuard or R8 is enabled.

Troubleshooting

Linking error

• run pod install
• rebuild app
• ensure native module is linked
• do not use Expo Go

Chat not opening

• ensure initialize() is called first
• verify botRefId + env
• check logs with setupLogging('info')

License

MIT