At the moment Filum does not offer a React Native SDK. We however are open to feature requests from our customers. In the meantime, if you want to use Webchat inside your React Native/Expo app, react-native-webview is required.

1. Obtain the chat URL

To open the webchat inside a react-native-webview instance, you first need to have a URL that contains all the necessary information such as your organization ID, installedSourceId, extra confgis and so on. We have prepared the following function that you can paste in your code to construct the URL:

export type LiveChatSessionData = {
  user?: {
    name?: string;
    email?: string;
    phone?: string | null;
  };
  conversationId?: string;
  sessionId: string;
  sessionToken: string;
  sessionTokenExpiration: string;
  userId: string;
};

function constructWebchatUrl(props: {
  orgId: string;
  installedSourceId: number;
  sessionData?: LiveChatSessionData;
  defaultUser?: {
    email?: string;
    name?: string;
    phone?: string | null;
  };
  locale?: 'en' | 'vi';
}): string {
  const params = new URLSearchParams();
  params.append('organizationId', props.orgId);
  params.append('installedSourceId', String(props.installedSourceId));
  params.append('mode', 'webview');
  params.append('hideHeader', 'true'); // 'true' if you want to hide the chat header
  params.append('hideRefreshButton', 'true'); // 'true' to hide the "refresh session" button in the chat header
  params.append('locale', props.locale || 'en');

  if (props.defaultUser) {
    if (props.defaultUser.name) params.append('_defaultUserName', props.defaultUser.name);
    if (props.defaultUser.email) params.append('_defaultUserEmail', props.defaultUser.email);
    if (props.defaultUser.phone) params.append('_defaultUserPhone', props.defaultUser.phone);
  }
  if (props.sessionData) {
    for (const data of Object.entries(props.sessionData)) {
      const [key, obj] = data;
      if (typeof obj === 'object') {
        if (obj.name) params.append('userName', obj.name);
        if (obj.email) params.append('userEmail', obj.email);
        if (obj.phone) params.append('userPhone', obj.phone);
      } else {
        params.append(key, obj);
      }
    }
  }

  return `https://chat-widget.filum.ai/?${params.toString()}`;
}

Note: to learn more about the defaultUser prop, see: Bring your own Auth

_defaultUserName vs userName — what's the difference?

The URL above carries two sets of user params. They look similar but serve very different purposes:

_defaultUserName / _defaultUserEmail / _defaultUserPhone — comes from your defaultUser prop. This is the authenticated identity from your app (e.g. the user is already logged in on your end). When provided, the webchat skips the info collection form entirely and uses these values as the user identity.
userName / userEmail / userPhone — comes from sessionData.user, i.e. the user attached to a previously saved chat session that you're restoring from storage. This only prefills the info collection form; it does not skip it. If your infoCollection config has required fields that aren't satisfied, the form will still appear.

Rule of thumb: if you have authenticated the user on your side and want to bypass the form, pass them via defaultUser. If you're just rehydrating a prior session from AsyncStorage, pass them via sessionData.

Usage

const webchatUrl = constructWebchatUrl({
  orgId: 'your-org-id',
  installedSourceId: yourInstalledSourceId,
  sessionData: yourSessionData, // see: [Retain chat session data] below
  defaultUser: yourUserData,
  locale: 'vi', // or 'en'
});

<WebView
  source={{
    uri: webchatUrl,
  }}
  style={{ flex: 1 }}
/>;

2. Retain chat session data

Filum webchat is headless when it comes to storing the users chat sessions. Which means you can use any storage solution you prefer, whether it's AsyncStorage or SecureStorage. The webchat will emit an event containing the sessionData with its latest value. Below is an example to store a user's session using AsyncStorage:

import AsyncStorage from '@react-native-async-storage/async-storage';

...
<WebView
  source={{
    uri: webchatUrl,
  }}
  style={{ flex: 1 }}

  // Listen to events emitted from the webchat
  onMessage={async (event) => {
    const data = JSON.parse(event.nativeEvent.data);
    if (data.type === 'update_session') {
      const sessionData = data.data;
      AsyncStorage.setItem(
        'filum-auth-data', // or choose any unique key you want
        JSON.stringify(sessionData),
      );
    }
  }}
/>

Once you have saved the data, everytime the webchat is loaded, you can pass the data into its URL using the constructWebchatUrl mentioned above.

3. Webchat loading state

Filum webchat emits an event called "webchat_loaded", indicating that the environment is set up and ready. You can listen to that event to manage the loading state on your React Native app.

const [webchatLoaded, setWebchatLoaded] = useState(false)

<WebView
  source={{
    uri: webchatUrl
  }}
  style={{ flex: 1 }}
  onMessage={async (event) => {
    const data = JSON.parse(event.nativeEvent.data)
    if (data.type === 'update_session') {
      const sessionData = data.data
      AsyncStorage.setItem('filum-auth-data', JSON.stringify(sessionData))
    } else if (data.type === 'webchat_loaded') {
      setWebchatLoaded(true)
    }
  }}
/>

Usage​

2. Retain chat session data

3. Webchat loading state

Usage