@jokkoo/sdk-react

Official Jokkoo client embed SDK for React web applications.

Provides a floating support widget with conversation list, realtime chat, file attachments, voice messages, satisfaction rating, theming, and i18n (fr/en).

Install

pnpm add @jokkoo/sdk-react @jokkoo/sdk-web @tanstack/react-query

Peer dependencies: react >= 18, react-dom >= 18, @tanstack/react-query >= 5

Import styles once in your app entry:

import "@jokkoo/sdk-react/styles.css"

Quick start

import { JokkooProvider, JokkooWidget } from "@jokkoo/sdk-react"
import "@jokkoo/sdk-react/styles.css"

function App() {
  return (
    <JokkooProvider
      clientToken="ct_..."
      userTokenProvider={async () => {
        const res = await fetch("/api/jokkoo-token")
        const data = await res.json()
        return data.token as string
      }}
      locale="fr"
      theme={{ colors: { primary: "#1C1C1C" } }}
    >
      <JokkooWidget />
    </JokkooProvider>
  )
}

Your tenant backend signs short-lived user JWTs with @jokkoo/nodejs-server or the Java server helper.

Architecture

@jokkoo/sdk-web          Framework-agnostic core (API client, realtime,
                         token management, i18n, shared utilities)
@jokkoo/sdk-react        React bindings + UI widget (this package)

sdk-react is a thin React layer on top of sdk-web. All non-UI logic (API calls, WebSocket, token refresh, file upload, formatting) lives in sdk-web.

Public API

Components

| Export | Description | |--------|-------------| | JokkooProvider | Root context provider. Initializes SDK, QueryClient, navigation, unread state. | | JokkooWidget | Complete floating widget: launcher button + slide-up panel (request list + conversation). | | FloatingButton / JokkooButton | Standalone floating launcher with unread badge. Positions: bottom-right, bottom-left. | | WidgetPanel | Slide-up panel container with expand/close controls. Used by JokkooWidget. | | RequestListScreen | Conversation list with status badges, avatars, new-request CTA. | | ConversationScreen | Full conversation view: messages, input, voice recording, attachments, satisfaction rating. | | MessageBubble | User/agent/system message bubble with voice player and attachment support. | | MessageInput | Text input with attachment picker, send/voice-toggle button and character counter. | | MessageList | Scrollable message list with pagination, auto-scroll, new-message indicator. | | MessageAttachments | Thumbnail grid of image/document attachments. | | AttachmentPreviewModal | Full-screen in-app preview for images; action card for documents. | | PendingAttachmentList | Shows upload progress for files being attached. | | ListLoadingFooter | Loading spinner for infinite scroll lists. | | Avatar | Circular avatar with initials or image, optional unread indicator. | | StatusBadge | Color-coded conversation status badge (New, In Progress, Resolved, Ended). | | ConversationHeader | Header with back button, conversation title, and status badge. | | PanelHeader | Widget panel header with expand and close buttons. | | ActivityEvent | Centered system event text with optional timestamp. | | NewMessageIndicator | Floating "scroll to latest" button with new-message count. | | RequestCard | Conversation list item card with avatar, preview text, timestamp, unread state. | | ResolvedBanner | Banner shown for closed conversations with new-request CTA. | | SatisfactionRating | 5-point emoji rating component with submit state and thank-you message. | | VoiceMessagePlayer | Play/pause voice message with waveform visualization. | | VoiceRecordingOverlay | Recording UI with live waveform, timer, cancel/send controls. | | VoiceWaveform | Animated waveform bars for live recording or playback progress. |

Hooks

| Export | Description | |--------|-------------| | useConversations | Paginated conversation list via useInfiniteQuery. | | useMessages(conversationId) | Paginated messages for a conversation (newest-first). | | useSendMessage | Send message mutation with cache invalidation. | | useUnreadCount | Current unread conversation count. | | useRealtimeStatus | Current WebSocket connection status. | | useFileUpload | File picker, upload progress, retry, remove. | | useVoiceRecorder | Voice recording with metering, duration tracking, upload. | | useSmoothedWaveformLevels | RequestAnimationFrame-based smooth level interpolation for waveform animation. | | useClosedConversationPolicy | Fetch closed-conversation reply policy (5min stale time). | | useGlobalRealtimeListener | Unread tracking, conversation list cache updates via Socket.IO. | | useRealtimeConversations | Listen for conversation/message events and update list cache. | | useRealtimeMessages(conversationId) | Listen for new messages in a conversation, track pending count. | | jokkooQueryKeys | TanStack Query key factory: .conversations, .conversationPolicies, .messages(id). |

Context

| Export | Description | |--------|-------------| | JokkooProvider | Wraps app with QueryClient + Jokkoo context. | | useJokkooContext | Access theme, translations, API/realtime clients, navigation, unread state. | | NEW_CONVERSATION_ID | Constant (0) used to identify the "new conversation" screen. |

Theme

| Export | Description | |--------|-------------| | defaultTheme | Complete default theme object with colors, spacing, typography. | | mergeTheme(partial?) | Merge partial overrides with defaultTheme. | | themeToCssVars(theme) | Map theme to CSS custom properties (e.g. --jk-color-primary). |

Types: JokkooTheme, JokkooThemeColors, JokkooThemeSpacing, JokkooThemeTypography.

Re-exported from @jokkoo/sdk-web

| Export | Description | |--------|-------------| | Conversation, Message | API data types. | | ChatMessage | UI-oriented message type with sender (user, agent, system). | | JokkooConfig, UserTokenProvider, Translations | Config and i18n types. |

Theming

Pass a partial theme to JokkooProvider. All values map to CSS custom properties on .jokkoo-widget:

<JokkooProvider
  theme={{
    colors: {
      primary: "#0066FF",
      background: "#F8F9FA",
      userBubbleBackground: "#0066FF",
    },
    borderRadius: 8,
    typography: {
      headingSize: 22,
    },
  }}
>
  <JokkooWidget />
</JokkooProvider>

CSS custom properties

| Property | Default | Description | |----------|---------|-------------| | --jk-color-primary | #1C1C1C | Primary brand color | | --jk-color-background | #FFFFFF | Widget background | | --jk-color-surface | #F5F6F8 | Secondary surface | | --jk-color-text | #1C1C1C | Primary text | | --jk-color-text-secondary | #8A8A9A | Muted text | | --jk-color-border | #E4E4E8 | Borders and dividers | | --jk-color-on-primary | #FFFFFF | Text on primary | | --jk-color-user-bubble | #1C1C1C | User message bubble | | --jk-color-agent-bubble | #F5F6F8 | Agent message bubble | | --jk-color-header | #1C1C1C | Conversation header | | --jk-color-header-text | #FFFFFF | Header text | | --jk-color-unread | #EF4444 | Unread badge | | --jk-radius-panel | 20px | Panel border radius | | --jk-radius-bubble | 20px | Bubble border radius | | --jk-radius-card | 16px | Card border radius | | --jk-radius-badge | 8px | Badge border radius |

i18n

Supported locales: fr (default), en.

<JokkooProvider locale="en">
  <JokkooWidget />
</JokkooProvider>

Web channel origins

For channelType === "web", the Jokkoo API validates the browser Origin against the channel's allowed origins in the Jokkoo dashboard. Add your production and staging origins before embedding the widget.

Integration guide for jokkoo-business-demo

1. Create Vite app

pnpm create vite react-web-demo --template react-ts
cd react-web-demo
pnpm add @jokkoo/sdk-react @jokkoo/sdk-web @tanstack/react-query

2. Wrap app with JokkooProvider

// src/App.tsx
import { JokkooProvider, JokkooWidget } from "@jokkoo/sdk-react"
import "@jokkoo/sdk-react/styles.css"

const CLIENT_TOKEN = import.meta.env.VITE_JOKKOO_CLIENT_TOKEN
const API_URL = import.meta.env.VITE_JOKKOO_API_URL ?? "https://api.jokkoo.ai"

async function fetchUserToken(): Promise<string> {
  const res = await fetch("http://localhost:8080/auth/jokkoo-user-token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      sub: "user-1",
      name: "Amadou Diallo",
      email: "[email protected]",
    }),
  })
  const data = await res.json()
  return data.token as string
}

export default function App() {
  return (
    <JokkooProvider
      clientToken={CLIENT_TOKEN}
      baseUrl={API_URL}
      userTokenProvider={fetchUserToken}
      locale="fr"
    >
      <div style={{ padding: 24 }}>
        <h1>Jokkoo Support</h1>
        <p>Click the button to open support chat.</p>
      </div>
      <JokkooWidget position="bottom-right" />
    </JokkooProvider>
  )
}

3. User simulation (optional)

Follow the same pattern as the existing mobile demos:

// src/config/demo-users.ts
export const DEMO_USERS = [
  { sub: "user-1", name: "Amadou Diallo", email: "[email protected]" },
  { sub: "user-2", name: "Fatou Sow", email: "[email protected]" },
  { sub: "user-3", name: "John Smith", email: "[email protected]" },
]

The Spring Boot backend at apps/spring-boot/demo/ already exposes POST /auth/jokkoo-user-token — reuse it.

Manual QA checklist

| Test | Steps | Expected | |------|-------|----------| | Widget open/close | Click floating button → click close | Panel opens and closes smoothly | | Conversation list | Open widget | Conversations load with status badges | | Conversation view | Tap a conversation | Messages load, new message indicator works | | Send text | Type message → press Enter/send | Message appears optimistically, then confirmed | | File attachment | Click paperclip → select file | Upload progress shown, attachment sent | | Voice recording | Click mic → record → send | Recording uploads, voice player appears | | Attachment preview | Click image attachment | Modal opens with full-size preview | | Satisfaction rating | Rate conversation | Thank-you message shown | | Theme | Change theme colors in Provider | CSS variables update in real time | | i18n | Switch locale between fr/en | All UI labels update | | Pagination | Scroll to top of messages | Older messages load | | Unread badge | Receive message while widget closed | Badge count updates | | Closed conversation | Reply to closed conversation | Banner shows reopen/new-request option |

License

Apache-2.0