React SDK

Drop-in component, provider, and headless hooks. Use what you need — skip what you don't.

@helpway/react exposes three integration layers, in order of control:

<HelpwayWidget> — one-line drop-in. Renders the default themed chat UI. 90% of integrations stop here.
<SupportProvider> + <DefaultWidget> — same default UI, but split so you can mount the provider higher and access widget APIs via hooks.
<SupportProvider> + headless hooks — bring your own UI. Conversation list, timeline, composer, presence — all exposed as plain React hooks.

Layer 1: HelpwayWidget

Simplest path. Mount once at the root of your app.

import { HelpwayWidget } from "@helpway/react";
 
<HelpwayWidget apiKey="pk_live_xxx" />

Props

Prop	Type	Default	Notes
`apiKey`	`string`	—	Required. Public key from Settings → API Keys.
`apiUrl`	`string`	`https://api.helpway.ai`	Override for staging / self-hosted.
`locale`	`string`	auto-detect	`"tr"`, `"en"`, `"de"`… Falls back to `Accept-Language`.
`initialConversationId`	`string`	—	Deep link: auto-open a specific conversation.
`onReady`	`(api) => void`	—	Fired once bootstrap finishes. Gives `{ identify, openConversation }`.

Programmatic control via onReady

<HelpwayWidget
  apiKey="pk_live_xxx"
  onReady={(api) => {
    api.identify({
      userId: "u_12345",
      email: "user@acme.com",
      name: "Jane Doe",
    });
  }}
/>

Layer 2: Provider + Default UI

Useful when you want the default chat UI and want to call widget APIs from deeper in the tree.

import { SupportProvider, DefaultWidget, useWidget } from "@helpway/react";
 
function App() {
  return (
    <SupportProvider apiKey="pk_live_xxx">
      <YourApp />
      <DefaultWidget />
    </SupportProvider>
  );
}

Layer 3: Headless hooks

Build your own chat UI. Helpway handles auth, transport, caching, and realtime — you handle rendering.

import { SupportProvider, useTimeline, useComposer } from "@helpway/react";
 
function ChatPanel({ conversationId }) {
  const { items, isLoading } = useTimeline(conversationId);
  const { send, isSending } = useComposer(conversationId);
 
  return (
    <div>
      {items.map((item) => <Message key={item.id} item={item} />)}
      <MyComposer onSubmit={send} disabled={isSending} />
    </div>
  );
}

Available hooks

Hook	Purpose
`useWidget()`	The imperative API: `identify`, `openConversation`, `open`, `close`.
`useConversations()`	List of the visitor's conversations, paginated.
`useTimeline(id)`	Messages + events for one conversation, realtime-updated.
`useComposer(id)`	`send`, `isSending`, attachment helpers.
`usePresence()`	Is a teammate currently online?
`useUnread()`	Total unread count — hook into your own notification bell.
`useRealtime()`	Low-level: subscribe to raw realtime events.