react-native-newinstance-livechat

Embed a fully featured live chat into your React Native app in minutes. react-native-newinstance-livechat gives you a production-ready, drop-in chat screen that connects your users directly to live support agents — no backend wiring needed.

Powered by New Instance, a customer support platform that lets teams manage live conversations, automate routing, and track analytics from a single agent dashboard.

Why use this?

• One component, full support stack — authentication, real-time messaging, typing indicators, session persistence, and agent handoff are all built in.

• Works on iOS and Android — native modules handle storage, connectivity, and haptics on each platform.

• Fully themeable — match your brand with built-in light/dark themes or a fully custom color palette.

• Session continuity — users can close the app and come back; their conversation picks up where they left off.

• Zero server setup — point it at your New Instance appId and apiKey and you're live.

Installation

npm install react-native-newinstance-livechat
# or
yarn add react-native-newinstance-livechat

iOS Setup

cd ios && pod install

Android Setup

No extra steps needed. Native modules are auto-linked.

Quick Start

import { StyleSheet, View } from 'react-native';
import { ChatScreen, type WidgetConfig } from 'react-native-newinstance-livechat';

const config: WidgetConfig = {
  appId: 'YOUR_APP_ID',
  apiKey: 'lc_YOUR_API_KEY',
  theme: {
    primaryColor: '#8178E8',
    backgroundColor: '#FFFFFF',
    textColor: '#1F2937',
  },
};

export default function App() {
  return (
    <View style={styles.container}>
      <ChatScreen
        config={config}
        onClose={() => console.log('Chat closed')}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
});

ChatScreen handles authentication, session restoration, agent connection, and the full chat UI.

Configuration

WidgetConfig

Get your appId and apiKey from the agent dashboard at cinstance.com.

| Property | Type | Required | Description | |---|---|---|---| | appId | string | Yes | Your application ID | | apiKey | string | Yes | Your live chat API key (prefixed lc_) | | customerName | string | No | Pre-fill customer name (skips the info form) | | customerEmail | string | No | Pre-fill customer email | | customerId | string | No | Custom identifier for the customer | | initialMessage | string | No | Initial message to start the conversation | | theme | WidgetTheme \| 'dark' \| 'light' | No | Theme configuration (auto-detects if omitted) |

Pre-filling Customer Info

If you already know the user's identity, pass it in the config to skip the customer info form:

const config: WidgetConfig = {
  appId: 'YOUR_APP_ID',
  apiKey: 'lc_YOUR_API_KEY',
  customerName: 'Jane Doe',
  customerEmail: '[email protected]',
};

ChatScreen Props

| Prop | Type | Default | Description | |---|---|---|---| | config | WidgetConfig | — | Required. Widget configuration. | | showHeader | boolean | true | Show the header bar with back/close buttons. | | onBack | () => void | — | Called when the back button is pressed. | | onClose | () => void | — | Called when the chat ends or close is pressed. |

<ChatScreen
  config={config}
  showHeader={false}
  onBack={() => navigation.goBack()}
  onClose={() => navigation.navigate('Home')}
/>

Theming

Built-in Themes

// Use 'light' or 'dark'
const config: WidgetConfig = {
  appId: 'YOUR_APP_ID',
  apiKey: 'lc_YOUR_API_KEY',
  theme: 'dark',
};

If theme is omitted, the library auto-detects the device color scheme.

Custom Theme

Pass a WidgetTheme object. Any properties you omit fall back to defaults:

const config: WidgetConfig = {
  appId: 'YOUR_APP_ID',
  apiKey: 'lc_YOUR_API_KEY',
  theme: {
    primaryColor: '#8178E8',
    secondaryColor: '#6964D3',
    accentColor: '#9333EA',
    backgroundColor: '#FFFFFF',
    textColor: '#1F2937',
    fontFamily: 'Inter',
    messageUserBg: '#8178E8',
    messageUserText: '#FFFFFF',
    messageSupportBg: '#F3F4F6',
    messageSupportText: '#1F2937',
    inputBg: '#FFFFFF',
    inputText: '#1F2937',
    inputBorder: '#D1D5DB',
  },
};

Theme Properties

| Property | Description | |---|---| | primaryColor | Brand color for buttons and accents | | primaryColorHover | Hover/press state for primary elements | | secondaryColor | Secondary brand color | | accentColor | Accent highlights | | buttonColor | Button background override | | buttonTextColor | Button text color | | bubbleColor | Default message bubble color | | iconColor | Icon tint color | | fontFamily | Font family name | | messageUserBg | User message bubble background | | messageUserText | User message text color | | messageSupportBg | Agent message bubble background | | messageSupportText | Agent message text color | | inputBg | Input field background | | inputText | Input field text color | | inputBorder | Input field border color | | backgroundColor | Screen background | | textColor | Primary text color | | secondaryTextColor | Muted text color | | borderColor | General border color | | placeholderColor | Input placeholder text color | | disabledBackgroundColor | Disabled element background | | disabledTextColor | Disabled element text | | errorColor | Error state color | | successColor | Success state color | | warningColor | Warning state color |

Session Persistence

Live chat sessions survive app kills and restarts automatically:

• Sessions expire after 24 hours of inactivity
• When the user returns, the session is restored and message history is fetched from the server
• Sessions are cleared when the agent closes the conversation or the session times out

No configuration needed.

Controlling the Input Field

Use the useChatInput hook to read, write, or clear the message input programmatically — useful for canned responses, quick-reply buttons, or pre-filling text from a deep link.

import { useChatInput, ChatScreen, type WidgetConfig } from 'react-native-newinstance-livechat';

function SupportScreen({ config }: { config: WidgetConfig }) {
  const { value, setValue, append, clear } = useChatInput();

  return (
    <View style={{ flex: 1 }}>
      {/* Quick reply buttons above the chat */}
      <View style={{ flexDirection: 'row', padding: 8, gap: 8 }}>
        <Button title="Hi" onPress={() => setValue('Hi, I need help with my order')} />
        <Button title="Order #" onPress={() => append(' Order #12345')} />
        <Button title="Clear" onPress={clear} />
      </View>

      <ChatScreen config={config} />
    </View>
  );
}

useChatInput API

| Property / Method | Type | Description | |---|---|---| | value | string | Current text in the input field (reactive). | | setValue(text) | (text: string) => void | Replace the input text entirely. | | append(text) | (text: string) => void | Append text to the current input. | | clear() | () => void | Clear the input field. |

The hook is reactive — value updates whenever the user types or when you call setValue / append / clear.

You can also set the input from outside React (e.g. a native module callback) via the store directly:

import { useChatStore } from 'react-native-newinstance-livechat';

useChatStore.getState().setInputValue('Hello from native');

File Attachments

The built-in chat screen supports file attachments out of the box — images, PDFs, documents, spreadsheets, archives, and text files. Users can pick files from their device and send them alongside messages.

Attaching Files from Outside the Chat

If you need to attach files programmatically (e.g. from a share extension, a camera capture, or your own file picker), use the useFileAttachment hook:

import {
  useFileAttachment,
  ChatScreen,
  type WidgetConfig,
} from 'react-native-newinstance-livechat';

function MyScreen({ config }: { config: WidgetConfig }) {
  const { attachFile, attachFiles, attachBase64, count } = useFileAttachment();

  // Attach a single file by URI
  const handlePickedFile = (uri: string) => {
    const result = attachFile(uri, 'photo.jpg', 204800, 'image/jpeg');
    if (!result.success) console.warn(result.error);
  };

  // Attach multiple files at once
  const handleMultiple = (files: Array<{ uri: string; name: string; size: number; mimeType: string }>) => {
    const results = attachFiles(files);
    results.forEach((r) => { if (!r.success) console.warn(r.error); });
  };

  return (
    <>
      <Button title={`Attach (${count})`} onPress={pickSomething} />
      <ChatScreen config={config} />
    </>
  );
}

Queued attachments are uploaded automatically when the user sends their next message. Uploads run in parallel.

Base64 Attachments

Pass a data URI or raw base64 string. The library decodes the data, writes it to a temp file on disk via native code, and queues it:

const { attachBase64 } = useFileAttachment();

// Data URI — MIME type is parsed automatically
await attachBase64(
  'data:image/png;base64,iVBORw0KGgo...',
  'screenshot.png',
);

// Raw base64 — provide the MIME type explicitly
await attachBase64(
  'JVBERi0xLjQK...',
  'invoice.pdf',
  'application/pdf',
);

File Type Detection

Determine the category and label for any supported MIME type:

import { getFileTypeInfo } from 'react-native-newinstance-livechat';

const info = getFileTypeInfo('application/pdf');
// { label: 'PDF Document', abbreviation: 'PDF', category: 'pdf' }

const docInfo = getFileTypeInfo('application/vnd.openxmlformats-officedocument.wordprocessingml.document');
// { label: 'Word Document', abbreviation: 'DOC', category: 'word' }

Categories: image, pdf, word, spreadsheet, archive, text, file.

FileTypeIcon Component

A pure React Native component that renders a document-style icon with a colored abbreviation badge. No emoji, no third-party icon library:

import { FileTypeIcon } from 'react-native-newinstance-livechat';

<FileTypeIcon mimeType="application/pdf" size={28} />
// Red badge with "PDF"

<FileTypeIcon mimeType="image/jpeg" size={28} />
// Blue badge with "IMG"

Supported File Types

| Category | MIME Types | |---|---| | Images | image/jpeg, image/png, image/gif, image/webp, image/heic | | PDF | application/pdf | | Word | .doc, .docx | | Spreadsheet | .xls, .xlsx | | Archive | application/zip | | Text | text/plain |

Maximum file size: 10 MB per file, up to 5 files at once.

useFileAttachment API

| Method | Description | |---|---| | attachFile(uri, name, size, mimeType) | Queue a single file. Returns { success, error?, id? }. | | attachFiles(files) | Queue multiple files. Returns an array of results. | | attachBase64(dataOrUri, fileName, mimeType?) | Decode base64 to a temp file and queue it. Returns a promise. | | removeFile(id) | Remove a queued file by its ID. | | clearFiles() | Remove all file attachments. | | attachText(content, label?) | Attach a text snippet. Returns the attachment ID. | | removeText(id) | Remove a text attachment. | | clearTexts() | Remove all text attachments. | | clearAll() | Clear all files, texts, and close the drawer. | | getFileType(mimeType) | Returns { label, abbreviation, category } for the MIME type. | | count | Total number of queued file + text attachments. | | attachments | Current file attachment array. | | textAttachments | Current text attachment array. | | isDrawerOpen | Whether the attachment drawer is visible. | | openDrawer() / closeDrawer() / toggleDrawer() | Drawer visibility controls. |

License

MIT