Chat SDK

Installation

npm install react-chat-agent

Prerequisites

  • React 18 or higher
  • A session token from oblien

Basic Setup

1. Create Session (Backend)

Use oblien to create a session:

// app/api/session/create/route.ts
import { OblienClient, OblienChat } from 'oblien';

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

const chat = new OblienChat(client);

export async function POST(req) {
  const { agentId, userId } = await req.json();
  
  const session = await chat.createSession({
    agentId,
    namespace: userId
  });
  
  return Response.json(session);
}

2. Get Session (Frontend)

const [authConfig, setAuthConfig] = useState(null);

useEffect(() => {
  async function createSession() {
    const response = await fetch('/api/session/create', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        agentId: 'your-agent-id',
        userId: 'user-123'
      })
    });
    
    const session = await response.json();
    setAuthConfig({
      sessionId: session.sessionId,
      accessToken: session.token
    });
  }
  
  createSession();
}, []);

3. Add ChatProvider

import { ChatProvider, ChatPanel } from 'react-chat-agent';
import 'react-chat-agent/ui.css';

function App() {
  if (!authConfig) return <div>Loading...</div>;

  return (
    <ChatProvider authConfig={authConfig}>
      <ChatPanel />
    </ChatProvider>
  );
}

Complete Example

Next.js App Router

// app/chat/page.tsx
'use client';

import { useState, useEffect } from 'react';
import { ChatProvider, ChatPanel } from 'react-chat-agent';
import 'react-chat-agent/ui.css';

export default function ChatPage() {
  const [authConfig, setAuthConfig] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    createSession();
  }, []);

  const createSession = async () => {
    try {
      const res = await fetch('/api/session/create', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          agentId: 'agent-123',
          userId: 'user-456'
        })
      });
      
      const session = await res.json();
      setAuthConfig({
        sessionId: session.sessionId,
        accessToken: session.token
      });
    } catch (error) {
      console.error('Failed to create session:', error);
    } finally {
      setLoading(false);
    }
  };

  if (loading) return <div>Loading chat...</div>;
  if (!authConfig) return <div>Failed to initialize chat</div>;

  return (
    <div className="h-screen">
      <ChatProvider authConfig={authConfig}>
        <ChatPanel onCreateSession={createSession} />
      </ChatProvider>
    </div>
  );
}

Create React App

// src/App.jsx
import { useState, useEffect } from 'react';
import { ChatProvider, ChatPanel } from 'react-chat-agent';
import 'react-chat-agent/ui.css';

function App() {
  const [authConfig, setAuthConfig] = useState(null);

  useEffect(() => {
    fetch('/api/session/create', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ agentId: 'agent-123' })
    })
      .then(res => res.json())
      .then(session => {
        setAuthConfig({
          sessionId: session.sessionId,
          accessToken: session.token
        });
      });
  }, []);

  if (!authConfig) return <div>Loading...</div>;

  return (
    <ChatProvider authConfig={authConfig}>
      <div className="app">
        <ChatPanel />
      </div>
    </ChatProvider>
  );
}

export default App;

Environment Setup

Environment Variables

# .env.local
NEXT_PUBLIC_API_URL=https://api.oblien.com
OBLIEN_API_KEY=your_api_key
OBLIEN_API_SECRET=your_api_secret

Import Styles

Add the CSS import to your main file:

import 'react-chat-agent/ui.css';

Or in your global CSS:

@import 'react-chat-agent/ui.css';

Configuration Options

ChatProvider Props

<ChatProvider
  authConfig={authConfig}           // Required
  debug={false}                     // Enable debug logs
  enableHistory={true}              // Load message history
  initialWelcome={<Welcome />}      // Custom welcome screen
  agentId="unique-id"              // For multi-instance
  onError={(error) => {}}          // Error handler
>
  {children}
</ChatProvider>

ChatPanel Props

<ChatPanel
  onCreateSession={() => {}}       // New session handler
  isDark={false}                   // Dark theme
  allowEditMessage={true}          // Allow message editing
/>

Testing Your Setup

Test that everything works:

import { useChatContext } from 'react-chat-agent';

function TestComponent() {
  const { sendMsg, messages, isStreaming } = useChatContext();

  const test = async () => {
    await sendMsg({ message: 'Hello!' });
  };

  return (
    <div>
      <button onClick={test}>Send Test Message</button>
      <p>Messages: {messages.length}</p>
      <p>Streaming: {isStreaming ? 'Yes' : 'No'}</p>
    </div>
  );
}

Common Issues

Session Not Creating

  • Verify API keys are correct
  • Check agent ID exists
  • Ensure backend route is accessible

Styles Not Loading

  • Import CSS file: import 'react-chat-agent/ui.css'
  • Check bundler configuration

CORS Errors

Configure CORS on your backend:

// Express
app.use(cors({
  origin: process.env.FRONTEND_URL,
  credentials: true
}));

Next Steps