@helpway/react

Official React SDK for Helpway — AI-powered customer support widget with full programmatic control.

📚 Full documentation: https://helpway.ai/docs · Quick start · React SDK · Customization & theming · Widget API · Integration notes (CSP, SSR, multi-tenant)

Install

npm install @helpway/react

Peer dependencies: react ≥ 18 and react-dom ≥ 18.

Quick start

import { HelpwayWidget } from "@helpway/react";

export default function App() {
  return (
    <>
      <YourApp />
      <HelpwayWidget apiKey="pk_live_xxx" />
    </>
  );
}

Programmatic API (window.Helpway)

After the widget bootstraps, a type-safe global API is available:

window.Helpway.open()                        // open panel
window.Helpway.close()                       // close panel
window.Helpway.toggle()                      // toggle open/close
window.Helpway.dismiss()                     // hide launcher + panel
window.Helpway.show()                        // re-show after dismiss
window.Helpway.shutdown()                    // full session reset

window.Helpway.identify({                    // link visitor to contact
  externalId: "u_123",
  email: "[email protected]",
  name: "Jane Doe",
})

window.Helpway.newConversation("Help!")      // open new conversation
window.Helpway.openConversation("conv_abc")  // open specific conversation

window.Helpway.unreadCount                   // getter: number
window.Helpway.isOpen                        // getter: boolean

window.Helpway.on("open", () => {})          // subscribe to events
window.Helpway.on("unreadChange", (n) => {})
window.Helpway.on("messageReceived", (msg) => {})
window.Helpway.off("open", handler)          // unsubscribe

TypeScript users get full auto-complete — the package augments Window automatically.

Props

| Prop | Type | Default | Description | |---|---|---|---| | apiKey | string | — | Required. Public key from dashboard. | | apiUrl | string | https://api.helpway.ai | Override for staging / self-hosted. | | locale | string | auto-detect | Widget language ("en", "tr", "de"…). | | hideLauncher | boolean | false | Hide the default floating bubble. | | customLauncherSelector | string | — | CSS selector for custom trigger element. | | onReady | (api: HelpwayAPI) => void | — | Full API object after bootstrap. | | onOpen | () => void | — | Panel opened. | | onClose | () => void | — | Panel closed. | | onUnreadChange | (count: number) => void | — | Unread count changed. |

Custom launcher

<HelpwayWidget
  apiKey="pk_live_xxx"
  hideLauncher
  customLauncherSelector="#my-btn"
/>

<button id="my-btn">Support</button>

Headless hooks

Build your own chat UI with the same realtime backend:

import { SupportProvider, useConversations, useTimeline, useComposer } from "@helpway/react";

function Chat() {
  const { conversations } = useConversations();
  const { items } = useTimeline(conversations[0]?.id);
  const { text, setText, submit } = useComposer(conversations[0]?.id);
  // ...render your own UI
}

<SupportProvider apiKey="pk_live_xxx">
  <Chat />
</SupportProvider>

Available hooks: useWidget, useConversations, useTimeline, useComposer, usePresence, useUnread, useRealtime.

Docs

Full documentation: helpway.ai/docs

License

MIT © Helpway