React Native SDK

This guide covers native mobile integration using @oxvo/messenger-reactnative.

What it is

React Native SDK renders OXVO Messenger in a modal WebView and supports:

• authenticated identity
• custom attributes
• conversation context
• runtime event callbacks

Where to find it in OXVO

• Settings → Inboxes → [Your inbox] → Installation
• Use your inbox websiteToken and OXVO baseUrl.

When to use it

Use this guide when adding in-app support chat to iOS and Android apps built with React Native.

Install

Common dependencies

npm i @oxvo/messenger-reactnative react-native-webview react-native-modal @react-native-async-storage/async-storage

iOS

npx pod-install
# or
cd ios && pod install

Android

# No CocoaPods step on Android.
# Rebuild the app after dependency install.
npx react-native run-android

Basic usage

import React, { useState } from 'react';
import { SafeAreaView, Text, TouchableOpacity } from 'react-native';
import { OxvoMessengerWidget } from '@oxvo/messenger-reactnative';

export default function SupportScreen() {
  const [visible, setVisible] = useState(false);

  return (
    <SafeAreaView style={{ flex: 1 }}>
      <TouchableOpacity onPress={() => setVisible(true)}>
        <Text>Open chat</Text>
      </TouchableOpacity>

      <OxvoMessengerWidget
        baseUrl="https://OXVO_BASE_URL"
        websiteToken="YOUR_WEBSITE_TOKEN"
        isVisible={visible}
        onClose={() => setVisible(false)}
        locale="en"
        theme="auto"
      />
    </SafeAreaView>
  );
}

Authenticated user and context

<OxvoMessengerWidget
  baseUrl="https://OXVO_BASE_URL"
  websiteToken="YOUR_WEBSITE_TOKEN"
  isVisible={visible}
  onClose={() => setVisible(false)}
  user={{
    identifier: 'USER_ID_123',
    name: 'Jane Doe',
    email: 'jane@example.com',
    identifier_hash: 'SERVER_GENERATED_HASH',
  }}
  customAttributes={{ plan: 'pro', platform: 'react-native' }}
  conversationCustomAttributes={{ checkout_step: 'payment' }}
  labels={['mobile', 'vip']}
/>

Useful props

Prop	Purpose
isVisible / isModalVisible	Controls widget modal visibility
onClose / closeModal	Close callback aliases
persistSession	Persists conversation token to storage
onEvent	Receives Messenger runtime events
onLoaded	Called after widget reports loaded
spinnerText, spinnerColor	Loading state customization
modalProps, webViewProps	Advanced control for modal/webview behavior

Environment tips

• Local Android emulator typically cannot use 127.0.0.1 for host machine services. Use host-mapped IP when required by your setup.
• Keep baseUrl environment-specific (staging, production) and never hardcode test endpoints in release builds.

Use the exact baseUrl from Settings → Inboxes → [Your inbox] → Installation for each app environment.

Validation checklist

1. Open and close widget on both platforms.
2. Validate authenticated user data appears in Inbox contact/conversation.
3. Confirm onEvent receives runtime events.
4. Confirm session persistence works after app restart.

Related guides

• Visitor identification and properties
• Listeners and events
• SDK recipes

📷 Image (optional): React Native Messenger integration layout
Why: Shows how the in-app support button, modal widget, and callback handling fit together on mobile screens.
File: docs/images/sdk-react-native-widget-flow.png
AI prompt: "Clean documentation mobile UI mock for OXVO React Native Messenger integration showing app screen with Open chat button, modal messenger view, and event log panel; modern SaaS style, neutral palette with primary accent, sharp typography, OXVO branding only, synthetic data, 1600x1000."