expo-hubspot-chat

An Expo module that integrates the HubSpot Mobile Chat SDK (iOS | Android) into React Native apps. Provides a native chat experience on both iOS and Android with full support for user identification, push notifications, and chat lifecycle events.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Usage
• API Reference
• Push Notifications
• Contributing
• License

Features

• Native HubSpot chat UI on both platforms (SwiftUI on iOS, WebView Activity on Android)
• User identification via HubSpot's Visitor Identification API
• Custom chat properties
• Push notification support (APNs on iOS, FCM on Android)
• Chat lifecycle events (chatOpened, chatClosed, chatError)
• Configurable presentation style on iOS
• Expo config plugin for zero-manual-setup native configuration

Note: This module is in early release and may evolve. Feedback and issues are welcome.

Requirements

| Requirement | Version | | -------------- | ------- | | Expo SDK | >= 51 | | React Native | >= 0.74 | | iOS | >= 15.0 | | Android minSdk | >= 26 |

Native SDK Versions

This module bundles/depends on the following native SDK versions:

| Platform | Dependency | Version | | -------- | --------------------------------------------------- | ------- | | Android | com.hubspot.mobilechatsdk:mobile-chat-sdk-android | 1.0.8 | | Android | com.google.firebase:firebase-bom | 33.7.0 | | iOS | HubspotMobileSDK.xcframework | Bundled |

⚠️ Important: This module contains native iOS and Android code and requires a development build. It does not work with Expo Go.

Installation

1. Install the package:

npx expo install expo-hubspot-chat

Configuration

Add the plugin to your app.config.ts (or app.json):

export default {
  expo: {
    plugins: [
      [
        "expo-hubspot-chat",
        {
          portalId: "12345678",
          hublet: "na1",
          environment: "production", // optional, defaults to "production"
          defaultChatFlow: "support", // optional
        },
      ],
    ],
  },
};

Then create a new development build:

npx expo prebuild --clean

# For iOS
npx expo run:ios

# For Android
npx expo run:android

The native configuration is automatically applied during the build step.

Plugin Props

| Prop | Type | Required | Default | Description | | ----------------- | ---------------------- | -------- | -------------- | --------------------------------------------- | | portalId | string | Yes | — | Your HubSpot portal ID | | hublet | string | Yes | — | HubSpot hublet region (e.g. "na1", "eu1") | | environment | "production" \| "qa" | No | "production" | HubSpot environment | | defaultChatFlow | string | No | — | Default chat flow identifier |

What the plugin does

The config plugin automates native project configuration at prebuild time:

iOS:

• Writes Hubspot-Info.plist with portal/hublet/environment config
• Adds the plist as a resource file to the Xcode project

Android:

• Writes hubspot-info.json to android/app/src/main/assets/
• Registers HubspotWebActivity in AndroidManifest.xml
• Registers HubspotChatMessagingService for Firebase Cloud Messaging
• Adds packaging exclusion for META-INF/versions/9/OSGI-INF/MANIFEST.MF conflicts

Usage

Initialize the SDK

Call initialize() once at app startup. All configuration (portalId, hublet, environment, defaultChatFlow) is read from the native config files generated by the plugin -- no parameters needed:

import { initialize } from "expo-hubspot-chat";

initialize();

Identify a user

Identify the user with an email and a server-generated identity token from HubSpot's Visitor Identification API:

import { setUserIdentity } from "expo-hubspot-chat";

setUserIdentity("[email protected]", identityToken);

Set chat properties

Send custom metadata visible to HubSpot agents:

import { setChatProperties } from "expo-hubspot-chat";

setChatProperties({
  "user-name": "Jane Doe",
  plan: "enterprise",
});

Open the chat

import { openChat } from "expo-hubspot-chat";

// Open with default chat flow
openChat();

// Open a specific chat flow
openChat({ chatFlow: "billing" });

// iOS: open as full screen modal
openChat({ presentationStyle: "fullScreen" });

The openChat function also accepts a plain string for backwards compatibility:

openChat("support");

Close the chat programmatically

import { closeChat } from "expo-hubspot-chat";

closeChat();

Listen to chat events

import { addChatEventListener } from "expo-hubspot-chat";

const subscription = addChatEventListener((event) => {
  switch (event.type) {
    case "chatOpened":
      console.log("Chat opened");
      break;
    case "chatClosed":
      console.log("Chat closed");
      break;
    case "chatError":
      console.error("Chat error:", event.error);
      break;
  }
});

// Cleanup when done
subscription.remove();

Check initialization status

import { isInitialized } from "expo-hubspot-chat";

if (isInitialized()) {
  openChat();
}

Clear user on sign-out

Always call clearUser() when the user logs out to prevent data leaking between sessions:

import { clearUser } from "expo-hubspot-chat";

async function signOut() {
  await clearUser();
  // ... rest of sign-out logic
}

API Reference

Functions

| Function | Signature | Description | | ---------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- | | initialize | () => void | Initialize the SDK. Reads config from native files set by plugin. | | isInitialized | () => boolean | Check if the SDK has been initialized. | | setUserIdentity | (email: string, identityToken: string) => void | Identify the current user. | | openChat | (options?: OpenChatOptions \| string) => void | Open the chat UI. | | closeChat | () => void | Programmatically close the chat UI. | | setChatProperties | (properties: Record<string, string>) => void | Set custom chat properties. | | clearUser | () => Promise<void> | Clear user data and end session. | | addChatEventListener | (listener: (event: HubspotChatEvent) => void) => EventSubscription | Subscribe to chat lifecycle events. |

Push Notifications

This module includes built-in push notification support for HubSpot chat messages.

iOS

The module automatically forwards APNs device tokens to HubSpot via an AppDelegateSubscriber. No additional setup is required beyond enabling push notifications in your Apple Developer account and Xcode capabilities.

Android

The module registers a HubspotChatMessagingService that extends Firebase Cloud Messaging. It automatically filters and handles HubSpot-specific push notifications.

Prerequisites:

• Firebase must be configured in your project (e.g. via @react-native-firebase/app)
• A google-services.json file must be present in your Android project

Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change.

License

MIT