@convokitapp/chat-embed 0.0.0-stage → 1.0.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 +131 -2
- package/dist/index.d.ts +113 -0
- package/dist/index.js +589 -0
- package/dist/main.js +77 -0
- package/package.json +47 -4
package/README.md
CHANGED
|
@@ -1,3 +1,132 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ConvoKit Chat Widget
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Add ConvoKit chat to any website by pasting one snippet: plain HTML, Wix,
|
|
4
|
+
Shopify, WordPress or any site builder that accepts custom code.
|
|
5
|
+
|
|
6
|
+
```html
|
|
7
|
+
<script defer src="https://cdn.jsdelivr.net/npm/@convokitapp/chat-embed@1/dist/main.js"></script>
|
|
8
|
+
<script>
|
|
9
|
+
window.addEventListener("load", function () {
|
|
10
|
+
ConvoKitWidget.start({
|
|
11
|
+
clientId: "YOUR_CLIENT_ID",
|
|
12
|
+
mode: "guest",
|
|
13
|
+
widgetKey: "YOUR_WIDGET_KEY",
|
|
14
|
+
startConversationWith: ["support"]
|
|
15
|
+
});
|
|
16
|
+
});
|
|
17
|
+
</script>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Turn the widget on, and copy a ready-made snippet with your keys filled in,
|
|
21
|
+
from **Dashboard → your app → Chat widget**.
|
|
22
|
+
|
|
23
|
+
## Login modes
|
|
24
|
+
|
|
25
|
+
| Mode | Needs a backend | Who the visitor is | Use it for |
|
|
26
|
+
| --- | --- | --- | --- |
|
|
27
|
+
| `guest` | No | A new anonymous guest, resumed on return visits | Support chat, pre-sales, public sites |
|
|
28
|
+
| `uid` | No | Whatever `uid` the page passes; created on first use | Demos, or apps whose chats are not private |
|
|
29
|
+
| `authToken` | Yes | The user your server verified | Logged-in users with private conversations |
|
|
30
|
+
|
|
31
|
+
### `guest`
|
|
32
|
+
|
|
33
|
+
Each visitor gets a server-generated `guest_…` user. The widget stores a
|
|
34
|
+
resume token in `localStorage` (or `sessionStorage` with
|
|
35
|
+
`storageMode: "SESSION"`), so returning visitors keep their conversation. A
|
|
36
|
+
guest can never be made to log in as an existing user.
|
|
37
|
+
|
|
38
|
+
### `uid`
|
|
39
|
+
|
|
40
|
+
```js
|
|
41
|
+
ConvoKitWidget.start({ clientId, mode: "uid", widgetKey, uid: "customer_42", user: { name: "Ada" } })
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
> **Security:** the widget key is public. With `uid` mode enabled, anyone who
|
|
45
|
+
> copies it can log in as **any user ID of the app** and read that user's
|
|
46
|
+
> conversations. This matches CometChat's auth-key login. Enable it only for
|
|
47
|
+
> demos or apps without private chats, and prefer `authToken` for real
|
|
48
|
+
> accounts. It is off by default and is enabled separately from guest mode.
|
|
49
|
+
|
|
50
|
+
Shopify example (`layout/theme.liquid`), using the customer when signed in:
|
|
51
|
+
|
|
52
|
+
```liquid
|
|
53
|
+
{% if customer %}
|
|
54
|
+
<script>
|
|
55
|
+
window.addEventListener("load", function () {
|
|
56
|
+
ConvoKitWidget.start({ clientId: "…", mode: "uid", widgetKey: "…",
|
|
57
|
+
uid: "shopify_" + {{ customer.id | json }}, user: { name: {{ customer.first_name | json }} },
|
|
58
|
+
startConversationWith: ["support"] });
|
|
59
|
+
});
|
|
60
|
+
</script>
|
|
61
|
+
{% endif %}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### `authToken`
|
|
65
|
+
|
|
66
|
+
No widget key is involved. Your server signs the visitor in with your own
|
|
67
|
+
authentication, then exchanges the app's client secret for a one-hour user
|
|
68
|
+
token:
|
|
69
|
+
|
|
70
|
+
```js
|
|
71
|
+
ConvoKitWidget.start({ clientId, mode: "authToken", userId: currentUser.id, tokenUrl: "/api/convokit-token" })
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The widget sends `POST tokenUrl` with `{ "appUserId": "…" }` (cookies
|
|
75
|
+
included) and expects `{ "token": "…" }`. It calls it again to renew. You can
|
|
76
|
+
pass `tokenProvider: async (appUserId) => token` instead of `tokenUrl`.
|
|
77
|
+
|
|
78
|
+
## Options
|
|
79
|
+
|
|
80
|
+
| Option | Default | Description |
|
|
81
|
+
| --- | --- | --- |
|
|
82
|
+
| `clientId` | — | App client ID (required). |
|
|
83
|
+
| `mode` | — | `"guest"`, `"uid"` or `"authToken"` (required). |
|
|
84
|
+
| `widgetKey` | — | Publishable key; `guest`/`uid` only. |
|
|
85
|
+
| `uid`, `user` | — | `uid` mode: the user ID, and `{ name, imageUrl }` applied on creation. |
|
|
86
|
+
| `userId`, `tokenUrl` / `tokenProvider` | — | `authToken` mode. |
|
|
87
|
+
| `startConversationWith` | `[]` | User IDs to chat with. Opens the existing conversation with exactly those members, or creates it. Without it the widget shows the user's inbox. |
|
|
88
|
+
| `conversationTitle` | — | Title for a conversation the widget creates. |
|
|
89
|
+
| `mount` | — | CSS selector to render into; created on `<body>` if it does not exist. |
|
|
90
|
+
| `isDocked` | `true` | Floating launcher. `false` renders inline in `mount`. |
|
|
91
|
+
| `dockedAlignment` | `"right"` | `"left"` or `"right"`. |
|
|
92
|
+
| `width`, `height` | `"380px"`, `"560px"` | Panel size (`px`, `vh`, `vw`, `%`, `rem`, `em`). Full screen on phones. |
|
|
93
|
+
| `title` | `"Chat"` | Header title. |
|
|
94
|
+
| `theme.primaryColor` | `#4f46e5` | Hex, `rgb()` or `hsl()`. |
|
|
95
|
+
| `storageMode` | `"LOCAL"` | Where the guest resume token is kept. |
|
|
96
|
+
| `apiUrl` | `https://api.convokit.app` | For local testing or self-hosting. |
|
|
97
|
+
|
|
98
|
+
`start()` returns the widget (`open()`, `close()`, `toggle()`, `destroy()`,
|
|
99
|
+
`chatClient`), or a promise of it when called before `<body>` exists. A docked widget connects only when first opened, so visitors
|
|
100
|
+
who never open chat never become chat users.
|
|
101
|
+
|
|
102
|
+
## Limits and billing
|
|
103
|
+
|
|
104
|
+
Widget users are ordinary app users and count toward monthly active users.
|
|
105
|
+
The dashboard sets a monthly cap on new widget users (default 1,000), and the
|
|
106
|
+
API rate-limits session requests per client IP. An optional list of allowed
|
|
107
|
+
websites stops other sites' browsers from using your key. Browsers enforce
|
|
108
|
+
it; a script can still fake the `Origin` header, which is why the cap and rate
|
|
109
|
+
limits always apply.
|
|
110
|
+
|
|
111
|
+
## Platform notes
|
|
112
|
+
|
|
113
|
+
- **Wix:** Settings → Custom Code → Add Custom Code, all pages, *Body – end*.
|
|
114
|
+
Don't use an *Embed HTML* element; it runs in an iframe.
|
|
115
|
+
- **Shopify:** Online Store → Themes → Edit code → `layout/theme.liquid`, just
|
|
116
|
+
before `</body>`.
|
|
117
|
+
|
|
118
|
+
## Bundlers
|
|
119
|
+
|
|
120
|
+
```js
|
|
121
|
+
import { start } from "@convokitapp/chat-embed"
|
|
122
|
+
start({ clientId, mode: "guest", widgetKey })
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Development
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
npm install
|
|
129
|
+
npm run validate # typecheck, tests, build → dist/main.js (CDN) and dist/index.js (ESM)
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Open `examples/index.html` after `npm run build` to try a local build.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
import { ConvoKitClient } from '@convokitapp/sdk';
|
|
2
|
+
|
|
3
|
+
type WidgetMode = 'guest' | 'uid' | 'authToken';
|
|
4
|
+
interface WidgetUserProfile {
|
|
5
|
+
name?: string;
|
|
6
|
+
imageUrl?: string;
|
|
7
|
+
}
|
|
8
|
+
interface WidgetConfig {
|
|
9
|
+
/** The app's client ID from the ConvoKit dashboard. */
|
|
10
|
+
clientId: string;
|
|
11
|
+
mode: WidgetMode;
|
|
12
|
+
/** Publishable widget key; required for `guest` and `uid`. */
|
|
13
|
+
widgetKey?: string;
|
|
14
|
+
/** `uid` mode: the user to log in as, created on first use. */
|
|
15
|
+
uid?: string;
|
|
16
|
+
/** Profile applied when the widget creates the user. */
|
|
17
|
+
user?: WidgetUserProfile;
|
|
18
|
+
/** `authToken` mode: the signed-in user's ID in your app. */
|
|
19
|
+
userId?: string;
|
|
20
|
+
/** `authToken` mode: POST `{ appUserId }` → `{ token }` on your server. */
|
|
21
|
+
tokenUrl?: string;
|
|
22
|
+
/** `authToken` mode: alternative to `tokenUrl`. */
|
|
23
|
+
tokenProvider?: (appUserId: string) => Promise<string>;
|
|
24
|
+
/** User IDs to chat with. The widget opens (or creates) that conversation. */
|
|
25
|
+
startConversationWith?: string[];
|
|
26
|
+
/** Title of the conversation the widget creates. */
|
|
27
|
+
conversationTitle?: string;
|
|
28
|
+
/** CSS selector of the element to render into; created on `<body>` when missing. */
|
|
29
|
+
mount?: string;
|
|
30
|
+
/** Floating launcher button (default) or rendered inline in `mount`. */
|
|
31
|
+
isDocked?: boolean;
|
|
32
|
+
dockedAlignment?: 'left' | 'right';
|
|
33
|
+
width?: string;
|
|
34
|
+
height?: string;
|
|
35
|
+
title?: string;
|
|
36
|
+
theme?: {
|
|
37
|
+
primaryColor?: string;
|
|
38
|
+
};
|
|
39
|
+
/** Where a guest's resume token is kept: survives tabs (`LOCAL`, default) or only this tab (`SESSION`). */
|
|
40
|
+
storageMode?: 'LOCAL' | 'SESSION';
|
|
41
|
+
/** Override the ConvoKit API, for local testing or self-hosting. */
|
|
42
|
+
apiUrl?: string;
|
|
43
|
+
}
|
|
44
|
+
type ResolvedConfig = Required<Pick<WidgetConfig, 'clientId' | 'mode' | 'isDocked' | 'dockedAlignment' | 'width' | 'height' | 'title' | 'storageMode' | 'apiUrl'>> & Omit<WidgetConfig, 'isDocked' | 'dockedAlignment' | 'width' | 'height' | 'title' | 'storageMode' | 'apiUrl'> & {
|
|
45
|
+
startConversationWith: string[];
|
|
46
|
+
primaryColor: string;
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
interface WidgetDependencies {
|
|
50
|
+
fetch?: typeof fetch;
|
|
51
|
+
createClient?: (options: ConstructorParameters<typeof ConvoKitClient>[0]) => ConvoKitClient;
|
|
52
|
+
}
|
|
53
|
+
declare class ChatWidget {
|
|
54
|
+
private readonly config;
|
|
55
|
+
private readonly deps;
|
|
56
|
+
readonly host: HTMLElement;
|
|
57
|
+
private readonly root;
|
|
58
|
+
private readonly panel;
|
|
59
|
+
private readonly heading;
|
|
60
|
+
private readonly headerActions;
|
|
61
|
+
private readonly backSlot;
|
|
62
|
+
private readonly body;
|
|
63
|
+
private readonly launcher;
|
|
64
|
+
private readonly badge;
|
|
65
|
+
private client;
|
|
66
|
+
private session;
|
|
67
|
+
private connecting;
|
|
68
|
+
private inbox;
|
|
69
|
+
private inboxSubscriptions;
|
|
70
|
+
private threadSubscriptions;
|
|
71
|
+
private thread;
|
|
72
|
+
private inboxRefresh;
|
|
73
|
+
private unsubscribeSession;
|
|
74
|
+
private isOpen;
|
|
75
|
+
private destroyed;
|
|
76
|
+
constructor(config: ResolvedConfig, deps?: WidgetDependencies);
|
|
77
|
+
open(): void;
|
|
78
|
+
close(): void;
|
|
79
|
+
toggle(): void;
|
|
80
|
+
destroy(): Promise<void>;
|
|
81
|
+
/** The underlying SDK client, once connected, for advanced integrations. */
|
|
82
|
+
get chatClient(): ConvoKitClient | null;
|
|
83
|
+
private connect;
|
|
84
|
+
private doConnect;
|
|
85
|
+
private reset;
|
|
86
|
+
private get me();
|
|
87
|
+
private watchInbox;
|
|
88
|
+
private loadInbox;
|
|
89
|
+
private findOrCreateConversation;
|
|
90
|
+
private showInbox;
|
|
91
|
+
private renderInbox;
|
|
92
|
+
private updateLauncher;
|
|
93
|
+
private leaveThread;
|
|
94
|
+
private openConversation;
|
|
95
|
+
private loadOlder;
|
|
96
|
+
private renderMessages;
|
|
97
|
+
private composer;
|
|
98
|
+
private send;
|
|
99
|
+
private markThreadRead;
|
|
100
|
+
private showCenter;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
declare class WidgetSessionError extends Error {
|
|
104
|
+
readonly status: number;
|
|
105
|
+
readonly code?: string | undefined;
|
|
106
|
+
constructor(message: string, status: number, code?: string | undefined);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Renders the chat widget. Docked widgets connect when first opened, so a
|
|
110
|
+
* visitor who never opens chat never becomes a (billed) chat user. */
|
|
111
|
+
declare function start(config: WidgetConfig, deps?: WidgetDependencies): ChatWidget | Promise<ChatWidget>;
|
|
112
|
+
|
|
113
|
+
export { ChatWidget, type WidgetConfig, type WidgetMode, WidgetSessionError, type WidgetUserProfile, start };
|