React Native SDK

The kipps-react-native-chatbot package lets you embed a fully functional Kipps.AI chatbot directly into any React Native or Expo application. Unlike iframe or WebView approaches, this SDK renders using native primitives (View, Text, FlatList, TextInput) — delivering 60 FPS scrolling, fluid animations, and a truly native feel on both iOS and Android.

Key Features

• 100% Native UI — No WebView. Built with View, Text, FlatList, and TextInput.
• Streaming Responses — Zero-dependency SSE parser via XMLHttpRequest, matching web client speed on the Hermes engine.
• Automatic Config Sync — Display name, theme, colors, placeholder text, and suggested messages are pulled directly from your Kipps.AI dashboard.
• Lead Generation Forms — Renders inline contact capture forms (name, email, phone) with native validation.
• Light & Dark Mode — Full theme support, configurable per component or inherited from the dashboard.
• Conversation Persistence — Uses AsyncStorage to persist conversation sessions across app restarts.
• TypeScript Support — Fully typed props and exported interfaces.

Installation

Install the package and its required peer dependencies:

# Using npm
npm install kipps-react-native-chatbot

# Install required peer dependency
npm install @react-native-async-storage/async-storage

Expo users: If you are using Expo, also run:

npx expo install @react-native-async-storage/async-storage

Basic Usage

Import KippsChatbot and render it inside any screen. It fills its parent container (flex: 1).

import React from 'react';
import { View, StyleSheet } from 'react-native';
import KippsChatbot from 'kipps-react-native-chatbot';

export default function ChatScreen() {
  return (
    <View style={styles.container}>
      <KippsChatbot
        chatbotId="YOUR_CHATBOT_ID"
        theme="light"
      />
    </View>
  );
}

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

Replace YOUR_CHATBOT_ID with the chatbot ID found in your Kipps.AI Dashboard → AI Chat Agent → Embed.

Component Props

Passing User Information

Use customInfo to attach authenticated user data to every conversation. This data is forwarded to the session registry and is visible in your Kipps.AI analytics dashboard.

<KippsChatbot
  chatbotId="YOUR_CHATBOT_ID"
  customInfo={{
    userId: 'user-123',
    name: 'Jane Doe',
    email: 'jane@example.com',
    plan: 'pro',
  }}
/>

Theme Configuration

Force Light or Dark Mode

// Always light
<KippsChatbot chatbotId="YOUR_CHATBOT_ID" theme="light" />

// Always dark
<KippsChatbot chatbotId="YOUR_CHATBOT_ID" theme="dark" />

Use Dashboard Theme (Default)

Omitting the theme prop will let the component inherit the theme set in your Kipps.AI dashboard. The primary color (button, avatar, accents) also comes from the dashboard's Appearance settings automatically.

Full-Screen Chat in React Navigation

To present the chatbot as a dedicated screen using React Navigation:

// ChatScreen.tsx
import React from 'react';
import { View, StyleSheet } from 'react-native';
import KippsChatbot from 'kipps-react-native-chatbot';

export default function ChatScreen({ route }) {
  const { userId, userName } = route.params ?? {};

  return (
    <View style={styles.container}>
      <KippsChatbot
        chatbotId="YOUR_CHATBOT_ID"
        theme="light"
        customInfo={{ id: userId, name: userName }}
      />
    </View>
  );
}

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

Register it in your navigator:

// App.tsx (or Navigator file)
import ChatScreen from './ChatScreen';

<Stack.Screen
  name="Chat"
  component={ChatScreen}
  options={{ title: 'Support Chat', headerShown: true }}
/>

Using the useChatbot Hook (Advanced)

For custom UI layouts, import the useChatbot hook directly instead of using the pre-built component:

import { useChatbot } from 'kipps-react-native-chatbot';

function MyCustomChat() {
  const {
    config,       // ChatbotConfig — dashboard settings (colors, name, etc.)
    messages,     // ChatMessage[] — full conversation history
    isLoading,    // boolean — config is loading
    isGenerating, // boolean — bot is streaming a reply
    error,        // string | null — any initialization error
    leadFormCompleted, // boolean — whether lead capture is done
    sendMessage,  // (text: string) => void
    submitLead,   // (name, email, phone) => Promise<void>
    resetChat,    // () => Promise<void> — starts a new conversation
  } = useChatbot({
    chatbotId: 'YOUR_CHATBOT_ID',
    customInfo: { userId: 'abc' },
  });

  // Build your own UI here...
}

Hook Return Values

TypeScript Interfaces

The package exports all key types. Import them for typed usage in your custom components:

import {
  ChatbotConfig,
  ChatMessage,
  Citation,
  StreamCallbacks,
} from 'kipps-react-native-chatbot';

ChatMessage

interface ChatMessage {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  created_at: Date;
  citations?: Citation[];     // Source references in AI responses
  images?: string[];          // Image URLs if present
  isPending?: boolean;        // true while the stream is in progress
  statusText?: string;        // e.g. "Thinking...", "Scanning resources..."
}

ChatbotConfig

interface ChatbotConfig {
  id: string;
  display_name?: string;            // Bot name shown in the header
  chat_option_color?: string;       // Primary brand color (hex)
  message_placeholder?: string;     // Input placeholder text
  theme?: 'light' | 'dark';        // Dashboard theme setting
  chat_header_icon?: string;        // Avatar image URL
  initial_message?: string;         // Welcome message
  lead_generation_name?: boolean;   // Collect name in lead form
  lead_generation_email?: boolean;  // Collect email in lead form
  lead_generation_phone?: boolean;  // Collect phone in lead form
  watermark_text?: string;          // Footer watermark label
  suggested_messages?: string;      // Comma-separated quick replies
}

How It Works

1. Mount — The component calls the Kipps.AI API to fetch your chatbot's config (colors, name, lead form settings).
2. Session — A conversation ID is registered and stored in AsyncStorage, so sessions persist between app restarts.
3. Lead Form — If your dashboard requires name/email/phone, the lead form is shown before the chat input is unlocked.
4. Streaming — User messages are sent via POST. The assistant's reply streams back over Server-Sent Events parsed by a native XMLHttpRequest — compatible with the Hermes JS engine used in production React Native apps.
5. Reset — Tapping the refresh icon (⟳) in the header clears the current session and starts a new conversation.

Customization Notes

All visual customization (primary color, bot name, avatar, welcome message, suggested messages, and watermark) is managed from your Kipps.AI Dashboard → AI Chat Agent → Appearance. Changes sync automatically to the SDK on the next app mount.

• Primary Color — Used for the send button, avatar background, and accent colors.
• Dark Mode — Set theme="dark" or configure it in the dashboard. The SDK adjusts all background, text, border, and input colors automatically.
• Watermark — Displayed at the bottom of the chat. Configurable in Appearance settings.

Troubleshooting

The chatbot shows a blank screen or spinner that never resolves. Verify your chatbotId is correct. Check that the chatbot is in an Active (not paused) state in your dashboard. Confirm network access to https://backend.kipps.ai from the device.

AsyncStorage warning about not being installed. Run npm install @react-native-async-storage/async-storage and rebuild your native app. For Expo, run npx expo install @react-native-async-storage/async-storage instead.

Chat input is not appearing after mount. If your chatbot has lead generation fields enabled (name, email, phone), the input is locked until the lead form is submitted. Check your Lead settings in the Kipps.AI dashboard.

The theme prop is ignored. The theme prop overrides the dashboard config only when explicitly passed. If you pass theme="dark", it takes precedence. If you omit it, the SDK uses the value from config.theme returned by the API.

Streaming responses stop or produce partial text. This can occur if the device switches networks mid-stream. The SDK uses XMLHttpRequest which has no built-in reconnection. Call resetChat() to start a fresh session. Implement your own retry logic with the useChatbot hook if needed.

Frequently Asked Questions

Does this package work with Expo? Yes. The package uses only standard React Native APIs and @react-native-async-storage/async-storage, both of which are fully compatible with Expo managed and bare workflows.

Can I use this in a modal or bottom sheet instead of a full-screen view? Yes. The KippsChatbot component fills its parent with flex: 1. Wrap it inside any container — a Modal, a bottom sheet library like @gorhom/bottom-sheet, or any View.

Can the same chatbot ID be used on both web and React Native? Yes. The chatbotId is universal. The same agent, knowledge base, appearance settings, and analytics work across all deployment channels simultaneously.

Is conversation history stored permanently? Conversation sessions are persisted per device using AsyncStorage. Clearing app data or calling resetChat() will start a new session. Server-side history is managed according to your Kipps.AI plan's data retention settings.

Can I customize the chat bubble styles? The pre-built component does not expose style overrides for individual bubbles. For full UI control, use the useChatbot hook to access messages and render your own ChatBubble components.

Is there an Expo Snack or demo I can try? Contact Kipps.AI support for access to a demo project. The package tarball (kipps-ai-react-native-chatbot-1.0.0.tgz) can also be installed locally for testing before publishing to npm.