Configuration

Learn how to configure the Chat SDK for your specific needs.

Configuration Basics

The Chat SDK is configured through the ChatConfig object passed to ChatProvider:

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

const config = {
  apiKey: 'YOUR_API_KEY',
  apiUrl: 'https://api.example.com/v1',
  debug: true,
};

function App() {
  return (
    <ChatProvider config={config}>
      {/* Your app */}
    </ChatProvider>
  );
}

Configuration Options

Required Options

apiKey

Your unique API key for authenticating requests to the backend service.

Type: stringRequired: Yes

<ChatProvider config={{ apiKey: 'sk_abc123def456' }}>
  {/* ... */}
</ChatProvider>

Get your API key from the Admin Dashboard.

Optional Options

apiUrl

Custom API endpoint URL for the backend service. Useful for self-hosted deployments or different environments.

Type: stringDefault: 'http://localhost:3000/api/v1'Required: No

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

debug

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

Type: booleanDefault: falseRequired: No

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

Environment-Based Configuration

Use environment variables to manage different configurations for different environments:

.env.local (Development)

REACT_APP_CHAT_SDK_API_KEY=sk_dev_abc123
REACT_APP_CHAT_API_URL=http://localhost:3000/api/v1

.env.staging

REACT_APP_CHAT_SDK_API_KEY=sk_staging_xyz789
REACT_APP_CHAT_API_URL=https://api.staging.example.com/v1

.env.production

REACT_APP_CHAT_SDK_API_KEY=sk_prod_xyz789
REACT_APP_CHAT_API_URL=https://api.example.com/v1

Usage in Code

function App() {
  const config = {
    apiKey: process.env.REACT_APP_CHAT_SDK_API_KEY || '',
    apiUrl: process.env.REACT_APP_CHAT_API_URL,
    debug: process.env.NODE_ENV === 'development',
  };

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

  return (
    <ChatProvider config={config}>
      <YourApp />
    </ChatProvider>
  );
}

Advanced Configuration Patterns

Dynamic Configuration

Load configuration from an API or remote source:

function App() {
  const [config, setConfig] = useState<ChatConfig | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadConfig() {
      try {
        const response = await fetch('/api/config/chat-sdk');
        const data = await response.json();
        setConfig(data);
      } catch (error) {
        console.error('Failed to load config:', error);
        // Fall back to environment variables
        setConfig({
          apiKey: process.env.REACT_APP_CHAT_SDK_API_KEY || '',
        });
      } finally {
        setLoading(false);
      }
    }

    loadConfig();
  }, []);

  if (loading) return <div>Loading...</div>;
  if (!config) return <div>Failed to load configuration</div>;

  return (
    <ChatProvider config={config}>
      <YourApp />
    </ChatProvider>
  );
}

Conditional Provider Setup

Enable/disable the chat widget based on feature flags:

interface AppConfig extends ChatConfig {
  enableChat: boolean;
}

function App() {
  const config: AppConfig = {
    apiKey: process.env.REACT_APP_CHAT_SDK_API_KEY || '',
    enableChat: process.env.REACT_APP_ENABLE_CHAT === 'true',
    debug: process.env.NODE_ENV === 'development',
  };

  return (
    <div>
      {config.enableChat ? (
        <ChatProvider config={config}>
          <MainApp />
        </ChatProvider>
      ) : (
        <MainApp />
      )}
    </div>
  );
}

Per-User Configuration

Customize configuration based on user properties:

function App({ user }) {
  const config = {
    apiKey: process.env.REACT_APP_CHAT_SDK_API_KEY || '',
    debug: user?.isAdmin && process.env.NODE_ENV === 'development',
    apiUrl: user?.customApiUrl || process.env.REACT_APP_CHAT_API_URL,
  };

  return (
    <ChatProvider config={config}>
      <MainApp />
    </ChatProvider>
  );
}

Styling Configuration

The SDK uses Tailwind CSS v4 with prefixed utilities. All CSS classes are prefixed with chat: to avoid conflicts.

Customizing Styles

To customize the chat interface styling, override the CSS classes:

/* styles.css */

/* Override primary color */
.chat\:bg-primary {
  background-color: #3b82f6 !important;
}

/* Override text color */
.chat\:text-primary-foreground {
  color: white !important;
}

/* Customize rounded corners */
.chat\:rounded-xl {
  border-radius: 12px !important;
}

Note: The colon (:) must be escaped with a backslash (\) in CSS selectors.

TypeScript Configuration

Using ChatConfig Type

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

const chatConfig: ChatConfig = {
  apiKey: 'YOUR_API_KEY',
  apiUrl: 'https://api.example.com/v1',
  debug: false,
};

Type-Safe Configuration Factory

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

function createChatConfig(): ChatConfig {
  const apiKey = process.env.REACT_APP_CHAT_SDK_API_KEY;

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

  return {
    apiKey,
    apiUrl: process.env.REACT_APP_CHAT_API_URL,
    debug: process.env.NODE_ENV === 'development',
  };
}

function App() {
  return (
    <ChatProvider config={createChatConfig()}>
      <YourApp />
    </ChatProvider>
  );
}

Security Best Practices

1. Store API Keys Safely

Never commit API keys to version control:

# .gitignore
.env.local
.env.*.local

2. Use Environment Variables

Always use environment variables for sensitive configuration:

// ❌ Don't do this
const config = { apiKey: 'sk_abc123def456' };

// ✅ Do this
const config = { apiKey: process.env.REACT_APP_CHAT_SDK_API_KEY };

3. Restrict API Key Usage

In your Admin Dashboard, restrict API keys to:

• Specific domains/origins
• Specific routes
• Rate limiting per user/session

4. Rotate Keys Periodically

Rotate your API keys every 90 days or after suspected exposure.

Troubleshooting Configuration

"Invalid API Key" Error

Cause: API key is missing, incorrect, or revoked.

Solution:

1. Check the key in your .env file
2. Verify the key is correct in the Admin Dashboard
3. Ensure the key hasn't been revoked or expired
4. Try generating a new key

"CORS Error" or "Unauthorized" Response

Cause: API URL is incorrect or not configured for your domain.

Solution:

1. Verify the apiUrl matches your backend endpoint
2. Check CORS settings in your backend
3. Ensure your domain is whitelisted in API settings
4. Check that authorization headers are being sent correctly

Configuration Not Applied

Cause: Provider not re-rendered with new config.

Solution:

// ✅ Correct - Config is stable
const config = useMemo(() => ({
  apiKey: process.env.REACT_APP_CHAT_SDK_API_KEY,
}), []);

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

// ❌ Wrong - Config recreated every render
return (
  <ChatProvider
    config={{
      apiKey: process.env.REACT_APP_CHAT_SDK_API_KEY,
    }}
  >
    {/* ... */}
  </ChatProvider>
);

Next Steps

• ChatProvider Documentation - Learn about the provider component
• useChat Hook - Access chat state and methods
• API Reference - Complete API documentation