ChatProvider Component

The ChatProvider is the main entry point for integrating the Chat SDK into your React application. It wraps your app and manages all chat functionality automatically, including rendering the chat interface.

Overview

The ChatProvider manages:

• Chat message state and history
• Loading and error states
• API communication with the backend
• Conversation persistence across page reloads
• Automatic UI rendering

No additional components need to be added to your app - the chat interface appears automatically once the provider is set up.

Basic Usage

import { ChatProvider } from '@cyborg-sdk/react';

function App() {
  return (
    <ChatProvider config={{ apiKey: 'YOUR_API_KEY' }}>
      {/* Your app content */}
      <YourApp />
    </ChatProvider>
  );
}

export default App;

Props

config (required)

Configuration object for the Chat SDK.

Type:

interface ChatConfig {
  apiKey: string;           // Required: Your API key from the dashboard
  apiUrl?: string;          // Optional: Custom API endpoint
  debug?: boolean;          // Optional: Enable debug logging
}

Properties:

apiKey (required)

Your unique API key for authenticating with the backend service. Get your API key from the Admin Dashboard.

<ChatProvider config={{ apiKey: 'sk-abc123def456' }}>
  {/* ... */}
</ChatProvider>

apiUrl (optional)

Custom API endpoint URL. Defaults to http://localhost:3000/api/v1 if not specified.

<ChatProvider
  config={{
    apiKey: 'YOUR_API_KEY',
    apiUrl: 'https://api.example.com/v1'
  }}
>
  {/* ... */}
</ChatProvider>

debug (optional)

Enable debug mode to log additional information. Useful for development and troubleshooting.

<ChatProvider
  config={{
    apiKey: 'YOUR_API_KEY',
    debug: true
  }}
>
  {/* ... */}
</ChatProvider>

children (required)

Your application's React components and content.

<ChatProvider config={{ apiKey: 'YOUR_API_KEY' }}>
  <MyApp />
</ChatProvider>

Features

Automatic Chat Interface

The provider automatically renders a floating chat widget in the bottom-right corner of your screen. No additional setup required.

<ChatProvider config={{ apiKey: 'YOUR_API_KEY' }}>
  {/* Chat widget appears automatically */}
  <Dashboard />
</ChatProvider>

Conversation Persistence

Conversation IDs are automatically persisted in localStorage, so users' chat history is preserved across page reloads and sessions.

// User's conversation continues even after closing/reopening the browser
<ChatProvider config={{ apiKey: 'YOUR_API_KEY' }}>
  <App />
</ChatProvider>

Streaming Responses

Messages are streamed from the server using Server-Sent Events (SSE) for a smooth, real-time chat experience.

Example: Complete Application Setup

import React from 'react';
import { ChatProvider } from '@cyborg-sdk/react';
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import Dashboard from './pages/Dashboard';
import Products from './pages/Products';
import Settings from './pages/Settings';

function App() {
  const apiKey = process.env.REACT_APP_CHAT_SDK_API_KEY;

  if (!apiKey) {
    throw new Error('REACT_APP_CHAT_SDK_API_KEY environment variable is required');
  }

  return (
    <ChatProvider
      config={{
        apiKey,
        debug: process.env.NODE_ENV === 'development',
      }}
    >
      <Router>
        <Routes>
          <Route path="/dashboard" element={<Dashboard />} />
          <Route path="/products" element={<Products />} />
          <Route path="/settings" element={<Settings />} />
        </Routes>
      </Router>
    </ChatProvider>
  );
}

export default App;

Best Practices

1. Store API Key Securely

Never hardcode your API key. Use environment variables instead:

// .env.local
REACT_APP_CHAT_SDK_API_KEY=sk_your_api_key_here

const apiKey = process.env.REACT_APP_CHAT_SDK_API_KEY || '';

<ChatProvider config={{ apiKey }}>
  {/* ... */}
</ChatProvider>

2. Place at Top Level

Put the ChatProvider as high as possible in your component tree to ensure all components have access to chat functionality:

function App() {
  return (
    <ChatProvider config={{ apiKey: 'YOUR_API_KEY' }}>
      <Header />
      <Navigation />
      <MainContent />
      <Footer />
    </ChatProvider>
  );
}

3. Error Handling

The provider handles errors gracefully. Access errors through the useChat hook if needed:

import { useChat } from '@cyborg-sdk/react';

function MyComponent() {
  const { error } = useChat();

  if (error) {
    return <div>Chat Error: {error.message}</div>;
  }

  return <div>Chat loaded successfully</div>;
}

4. Development vs Production

Use different API endpoints for development and production:

const config = {
  apiKey: process.env.REACT_APP_CHAT_SDK_API_KEY,
  apiUrl: process.env.REACT_APP_CHAT_API_URL || 'http://localhost:3000/api/v1',
  debug: process.env.NODE_ENV === 'development',
};

<ChatProvider config={config}>
  {/* ... */}
</ChatProvider>

Accessing Chat State

While the ChatProvider manages state internally, you can access and manipulate it using the useChat hook in child components:

import { useChat } from '@cyborg-sdk/react';

function ChatStatus() {
  const { messages, isLoading, error } = useChat();

  return (
    <div>
      <p>Messages: {messages.length}</p>
      <p>Loading: {isLoading ? 'Yes' : 'No'}</p>
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}

See the useChat Hook documentation for details on accessing and using chat state.