@clivly/chat-widget 0.8.0 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +90 -13
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,22 +1,66 @@
|
|
|
1
1
|
# `@clivly/chat-widget`
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An embeddable chat surface for your app's visitors. Messages land in your Clivly
|
|
4
|
+
workspace under **Conversations**, where your team replies in real time.
|
|
4
5
|
|
|
5
|
-
> **
|
|
6
|
-
>
|
|
7
|
-
>
|
|
8
|
-
> design-partner quality while the conversations UX settles.
|
|
9
|
-
|
|
10
|
-
> **New here?** Start with
|
|
11
|
-
> [Adding the chat widget](../../docs/guides/adding-the-chat-widget.md) — the
|
|
12
|
-
> end-to-end integration guide (widget record, session route, embed, operator
|
|
6
|
+
> **New here? Start with
|
|
7
|
+
> [Adding the chat widget](../../docs/guides/adding-the-chat-widget.md)** — the
|
|
8
|
+
> canonical end-to-end guide (widget record, session route, embed, operator
|
|
13
9
|
> inbox). This README is the API-level reference for the package's entrypoints.
|
|
14
10
|
|
|
15
|
-
|
|
16
|
-
|
|
11
|
+
> **Preview-quality surface.** The end-to-end path (SDK session handler,
|
|
12
|
+
> `/widget.js` serving, operator inbox) is implemented and covered by
|
|
13
|
+
> integration tests; treat it as design-partner quality while the conversations
|
|
14
|
+
> UX settles.
|
|
15
|
+
|
|
16
|
+
## Prerequisites
|
|
17
|
+
|
|
18
|
+
| Requirement | Version / note |
|
|
19
|
+
| --- | --- |
|
|
20
|
+
| Node.js | **≥ 22** |
|
|
21
|
+
| `react` / `react-dom` | **≥ 18** — peer dependencies, for the React entrypoints only. The script-tag build bundles its own |
|
|
22
|
+
| **A backend** | Required. The widget never holds your API key; it calls a route on your origin that does. Static-only sites (plain HTML, WordPress, Webflow) cannot install it |
|
|
23
|
+
| A widget record | Created in the dashboard under **Settings → Chat widget** |
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install @clivly/chat-widget
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Published on npm's `latest` tag. Use `@next` only for prerelease testing.
|
|
32
|
+
|
|
33
|
+
The **host-side session route** comes from `clivly/sdk`, not from this package —
|
|
34
|
+
see [Host-side pairing](#host-side-pairing) below. `npx clivly add widget`
|
|
35
|
+
scaffolds it for you.
|
|
36
|
+
|
|
37
|
+
## Five-minute quick start
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npx clivly add widget # scaffolds the session route on your backend
|
|
41
|
+
npm install @clivly/chat-widget
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
```tsx
|
|
45
|
+
import { ChatWidget, createSessionFetcher } from "@clivly/chat-widget";
|
|
46
|
+
|
|
47
|
+
<ChatWidget
|
|
48
|
+
widgetId="support"
|
|
49
|
+
getSession={createSessionFetcher({
|
|
50
|
+
sessionUrl: "/api/clivly/widget/session",
|
|
51
|
+
})}
|
|
52
|
+
/>;
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`widgetId` is the **public slug** you set on the widget record — it is not a
|
|
56
|
+
credential. `sessionUrl` must be the path where you mounted the session route on
|
|
57
|
+
your own origin; `/api/clivly/widget/session` is what `clivly add widget`
|
|
58
|
+
writes.
|
|
17
59
|
|
|
18
60
|
## Entrypoints
|
|
19
61
|
|
|
62
|
+
This package exposes four stable entrypoints with different intended use cases.
|
|
63
|
+
|
|
20
64
|
### `@clivly/chat-widget`
|
|
21
65
|
|
|
22
66
|
Use the package root for app-side integration code.
|
|
@@ -38,7 +82,7 @@ import {
|
|
|
38
82
|
} from "@clivly/chat-widget";
|
|
39
83
|
|
|
40
84
|
const getSession = createSessionFetcher({
|
|
41
|
-
sessionUrl: "/api/clivly/
|
|
85
|
+
sessionUrl: "/api/clivly/widget/session",
|
|
42
86
|
});
|
|
43
87
|
```
|
|
44
88
|
|
|
@@ -84,7 +128,7 @@ that serves the bundled widget directly.
|
|
|
84
128
|
|
|
85
129
|
The widget ships light and dark palettes and follows the host app by default.
|
|
86
130
|
For integration recipes (Tailwind, next-themes, a custom toggle) see
|
|
87
|
-
[the guide's theming section](../../docs/guides/adding-the-chat-widget.md#theming).
|
|
131
|
+
[the guide's theming section](../../docs/guides/adding-the-chat-widget.md#5-theming).
|
|
88
132
|
|
|
89
133
|
### `theme`
|
|
90
134
|
|
|
@@ -208,3 +252,36 @@ Use the handler rather than hand-writing the proxy: it puts `origin` in the
|
|
|
208
252
|
request body (the backend requires it there, and only falls back to the `Origin`
|
|
209
253
|
header), accepts `visitorToken: null` for a first-time visitor, and turns an
|
|
210
254
|
unreachable Clivly into a JSON `502` instead of a thrown `fetch`.
|
|
255
|
+
|
|
256
|
+
## Verify the integration
|
|
257
|
+
|
|
258
|
+
1. Load a page that embeds the widget, from an origin in the widget record's
|
|
259
|
+
**allowed origins** list.
|
|
260
|
+
2. Open the launcher and submit the pre-chat form.
|
|
261
|
+
3. The conversation should appear in your Clivly workspace under
|
|
262
|
+
**Conversations** within a second or two.
|
|
263
|
+
|
|
264
|
+
## Common errors and troubleshooting
|
|
265
|
+
|
|
266
|
+
| Symptom | Cause | Fix |
|
|
267
|
+
| --- | --- | --- |
|
|
268
|
+
| Widget mounts but every session is `403` | The origin is not in the widget record's allowlist. It is **exact-match**: `https://example.com` does not cover `https://www.example.com` | Add every embedding origin, with scheme, under **Settings → Chat widget** |
|
|
269
|
+
| A brand-new widget refuses everything | An empty origin list permits nothing | Add at least one origin |
|
|
270
|
+
| `503 widget_not_configured` | The Clivly server has no `CLIVLY_WIDGET_TOKEN_SECRET` | Only relevant when self-hosting — set it, or set `CLIVLY_MASTER_KEY` |
|
|
271
|
+
| Session request returns an opaque `400` | The route was hand-written and omits `origin` from the **body**, or rejects `visitorToken: null` | Use `createChatSessionHandler` from `clivly/sdk` |
|
|
272
|
+
| `404` on the session request | `sessionUrl` does not match where you mounted the route | `clivly add widget` writes `/api/clivly/widget/session` — match it, or set `sessionUrl` to your path |
|
|
273
|
+
| Bundle throws on `node:fs` / `node:child_process` | Something imported the `clivly` package root | Import the handler from `clivly/sdk` |
|
|
274
|
+
| A returning visitor starts a fresh thread on another device | By design — conversations resume by opaque `visitorToken` in `localStorage`, never by the (unverified) email | Not a bug; resuming by email would leak a known customer's history |
|
|
275
|
+
| Brand colour looks wrong on the dark panel | `brandColor` overrides `--clivly-chat-accent` in **both** themes | Pick a lighter accent, or override the token per theme in a React host |
|
|
276
|
+
| Deep CSS overrides do nothing on the script-tag embed | It mounts into a Shadow DOM, so host CSS cannot reach it | Use `brandColor` and the two themes there, or switch to the React embed |
|
|
277
|
+
|
|
278
|
+
## Related documentation
|
|
279
|
+
|
|
280
|
+
- **[Adding the chat widget](../../docs/guides/adding-the-chat-widget.md)** — the canonical end-to-end guide
|
|
281
|
+
- [Connecting to Clivly Cloud](../../docs/guides/connecting-to-clivly-cloud.md) — the overall integration guide
|
|
282
|
+
- [`@clivly/sdk` README](../sdk/README.md) — `createChatSessionHandler` and the rest of the runtime
|
|
283
|
+
- [`clivly` CLI README](../cli/README.md) — `clivly add widget`
|
|
284
|
+
|
|
285
|
+
## License
|
|
286
|
+
|
|
287
|
+
MIT
|