@convokitapp/chat-embed 1.0.1 → 1.1.0
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 +22 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +101 -5
- package/dist/main.js +31 -13
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -101,6 +101,10 @@ who never open chat never become chat users.
|
|
|
101
101
|
|
|
102
102
|
## Limits and billing
|
|
103
103
|
|
|
104
|
+
On ConvoKit's free plan the widget works in `guest` mode for up to 100 new
|
|
105
|
+
visitors a month and shows a small "Powered by ConvoKit" link. `uid` and
|
|
106
|
+
`authToken` modes, and removing the link, need a paid plan.
|
|
107
|
+
|
|
104
108
|
Widget users are ordinary app users and count toward monthly active users.
|
|
105
109
|
The dashboard sets a monthly cap on new widget users (default 1,000), and the
|
|
106
110
|
API rate-limits session requests per client IP. An optional list of allowed
|
|
@@ -108,6 +112,24 @@ websites stops other sites' browsers from using your key. Browsers enforce
|
|
|
108
112
|
it; a script can still fake the `Origin` header, which is why the cap and rate
|
|
109
113
|
limits always apply.
|
|
110
114
|
|
|
115
|
+
## Automatic replies
|
|
116
|
+
|
|
117
|
+
When automatic replies are turned on for your app in the ConvoKit dashboard,
|
|
118
|
+
the widget shows the cards your support agent sends:
|
|
119
|
+
|
|
120
|
+
- **Links** to your own pages or forms (Google Forms, Typeform, your site) open
|
|
121
|
+
in a new tab. Form answers go to you, never through ConvoKit.
|
|
122
|
+
- **Quick replies** are buttons the visitor can tap. A tap sends the button's
|
|
123
|
+
label as the visitor's message. The buttons stay active until the visitor
|
|
124
|
+
writes anything else.
|
|
125
|
+
- **"Talk to a person"** appears under the newest link or quick-reply card. It
|
|
126
|
+
hands the conversation to your team and pauses automatic replies for 24
|
|
127
|
+
hours.
|
|
128
|
+
- **Handoff and "submitted" notices** appear as small centred lines.
|
|
129
|
+
|
|
130
|
+
There's nothing to configure in the snippet. Older widget versions show the
|
|
131
|
+
same replies as plain text.
|
|
132
|
+
|
|
111
133
|
## Platform notes
|
|
112
134
|
|
|
113
135
|
- **Wix:** Settings → Custom Code → Add Custom Code, all pages, *Body – end*.
|
package/dist/index.d.ts
CHANGED
|
@@ -60,6 +60,7 @@ declare class ChatWidget {
|
|
|
60
60
|
private readonly headerActions;
|
|
61
61
|
private readonly backSlot;
|
|
62
62
|
private readonly body;
|
|
63
|
+
private readonly branding;
|
|
63
64
|
private readonly launcher;
|
|
64
65
|
private readonly badge;
|
|
65
66
|
private client;
|
|
@@ -94,6 +95,18 @@ declare class ChatWidget {
|
|
|
94
95
|
private openConversation;
|
|
95
96
|
private loadOlder;
|
|
96
97
|
private renderMessages;
|
|
98
|
+
/** A link to a page or form on the site owner's side. Card strings are
|
|
99
|
+
* always text; the SDK only lets https URLs through. */
|
|
100
|
+
private linkCard;
|
|
101
|
+
/** Buttons stay tappable until the visitor sends anything after the card. A
|
|
102
|
+
* tap posts the option's label as the visitor's message, which arrives
|
|
103
|
+
* through realtime like any other message. */
|
|
104
|
+
private quickReplies;
|
|
105
|
+
private escapeButton;
|
|
106
|
+
/** Runs a card request with the card disabled meanwhile. The server's reply
|
|
107
|
+
* (the visitor's quick-reply message or a handoff notice) arrives through
|
|
108
|
+
* realtime, so success only clears the busy state. */
|
|
109
|
+
private cardAction;
|
|
97
110
|
private composer;
|
|
98
111
|
private send;
|
|
99
112
|
private markThreadRead;
|
package/dist/index.js
CHANGED
|
@@ -47,7 +47,7 @@ function resolveConfig(input) {
|
|
|
47
47
|
}
|
|
48
48
|
|
|
49
49
|
// src/widget.ts
|
|
50
|
-
import { ConvoKitClient, ConvoKitError, createClientMessageId } from "@convokitapp/sdk";
|
|
50
|
+
import { ConvoKitClient, ConvoKitError, createClientMessageId, isCardAnswered, latestCardMessage } from "@convokitapp/sdk";
|
|
51
51
|
|
|
52
52
|
// src/session.ts
|
|
53
53
|
var WidgetSessionError = class extends Error {
|
|
@@ -100,6 +100,7 @@ function cachedFirst(first, renew) {
|
|
|
100
100
|
let cached = first.token;
|
|
101
101
|
return {
|
|
102
102
|
appUserId: first.appUserId,
|
|
103
|
+
showBranding: first.showBranding === true,
|
|
103
104
|
tokenProvider: async (appUserId) => {
|
|
104
105
|
if (cached) {
|
|
105
106
|
const token = cached;
|
|
@@ -136,7 +137,7 @@ async function openWidgetSession(config, fetchImpl = fetch) {
|
|
|
136
137
|
if (!response.ok || !token) throw new WidgetSessionError("Your token endpoint did not return a token", response.status);
|
|
137
138
|
return token;
|
|
138
139
|
});
|
|
139
|
-
return { appUserId: config.userId, tokenProvider };
|
|
140
|
+
return { appUserId: config.userId, tokenProvider, showBranding: false };
|
|
140
141
|
}
|
|
141
142
|
|
|
142
143
|
// src/styles.ts
|
|
@@ -181,6 +182,24 @@ header h2 { flex: 1; margin: 0; font-size: 15px; font-weight: 600; white-space:
|
|
|
181
182
|
.msg.failed .meta { color: var(--ck-danger); }
|
|
182
183
|
.msg .attachment { font-size: 12px; color: var(--ck-muted); }
|
|
183
184
|
.empty { margin: auto; color: var(--ck-muted); }
|
|
185
|
+
.card { padding: 10px 12px; border-radius: 14px; background: var(--ck-bubble); display: flex; flex-direction: column; gap: 8px; overflow-wrap: anywhere; }
|
|
186
|
+
.card-title { font-weight: 600; }
|
|
187
|
+
.card-text { margin: 0; white-space: pre-wrap; }
|
|
188
|
+
.card-action { align-self: flex-start; border-radius: 8px; padding: 6px 12px; background: var(--ck-primary); color: #fff; font-weight: 600; text-decoration: none; }
|
|
189
|
+
.card-action:focus-visible, .option:focus-visible, .escape:focus-visible { outline: 2px solid var(--ck-primary); outline-offset: 2px; }
|
|
190
|
+
.options { display: flex; flex-wrap: wrap; gap: 6px; }
|
|
191
|
+
.option { border: 1px solid var(--ck-primary); background: var(--ck-bg); color: var(--ck-primary); border-radius: 999px; padding: 4px 12px; }
|
|
192
|
+
.option.chosen { background: var(--ck-primary); color: #fff; }
|
|
193
|
+
.option:disabled { cursor: default; opacity: .6; }
|
|
194
|
+
.option.chosen:disabled { opacity: 1; }
|
|
195
|
+
.escape { align-self: flex-start; border: 0; background: transparent; padding: 2px 0; color: var(--ck-muted); font-size: 12px; text-decoration: underline; }
|
|
196
|
+
.escape:disabled { cursor: default; opacity: .6; }
|
|
197
|
+
.card-error { color: var(--ck-danger); }
|
|
198
|
+
.notice { align-self: center; max-width: 90%; text-align: center; font-size: 12px; color: var(--ck-muted); padding: 4px 10px; border: 1px solid var(--ck-border); border-radius: 999px; }
|
|
199
|
+
.notice.receipt { color: var(--ck-fg); }
|
|
200
|
+
.branding { padding: 6px; border-top: 1px solid var(--ck-border); text-align: center; font-size: 11px; color: var(--ck-muted); }
|
|
201
|
+
.branding a { color: inherit; font-weight: 600; text-decoration: none; }
|
|
202
|
+
.branding a:hover { text-decoration: underline; }
|
|
184
203
|
form { display: flex; gap: 8px; padding: 10px; border-top: 1px solid var(--ck-border); align-items: flex-end; }
|
|
185
204
|
textarea { flex: 1; resize: none; max-height: 120px; min-height: 38px; border: 1px solid var(--ck-border); border-radius: 10px; padding: 8px 10px; font: inherit; color: var(--ck-fg); background: var(--ck-bg); }
|
|
186
205
|
form .primary { height: 38px; }
|
|
@@ -208,6 +227,7 @@ var FRIENDLY = {
|
|
|
208
227
|
};
|
|
209
228
|
var OWNER_HINTS = {
|
|
210
229
|
PLAN_UPGRADE_REQUIRED: 'This ConvoKit plan only supports guest mode. Use mode: "guest", or upgrade to Starter for "uid" and "authToken".',
|
|
230
|
+
SUBSCRIPTION_REQUIRED: 'The free ConvoKit plan only supports guest mode. Use mode: "guest", or subscribe in the ConvoKit dashboard for "uid" and "authToken".',
|
|
211
231
|
PLAN_USER_LIMIT_REACHED: "This ConvoKit plan has reached its monthly active user limit. Upgrade the plan in the ConvoKit dashboard.",
|
|
212
232
|
WIDGET_USER_LIMIT_REACHED: "The monthly limit of new widget users is reached. Raise it in the ConvoKit dashboard or upgrade the plan."
|
|
213
233
|
};
|
|
@@ -257,7 +277,13 @@ var ChatWidget = class {
|
|
|
257
277
|
this.backSlot = el("span");
|
|
258
278
|
this.headerActions = el("span");
|
|
259
279
|
this.body = el("div", { className: "body" });
|
|
260
|
-
this.
|
|
280
|
+
this.branding = el(
|
|
281
|
+
"footer",
|
|
282
|
+
{ className: "branding", hidden: true },
|
|
283
|
+
"Powered by ",
|
|
284
|
+
el("a", { href: "https://convokit.app/?utm_source=chat-widget&utm_medium=referral", target: "_blank", rel: "noopener", textContent: "ConvoKit" })
|
|
285
|
+
);
|
|
286
|
+
this.panel = el("section", { className: "panel" }, el("header", {}, this.backSlot, this.heading, this.headerActions), this.body, this.branding);
|
|
261
287
|
this.panel.setAttribute("aria-label", config.title);
|
|
262
288
|
this.isOpen = !config.isDocked;
|
|
263
289
|
if (config.isDocked) {
|
|
@@ -326,6 +352,7 @@ var ChatWidget = class {
|
|
|
326
352
|
}
|
|
327
353
|
this.client = client;
|
|
328
354
|
this.session = session;
|
|
355
|
+
this.branding.hidden = !session.showBranding;
|
|
329
356
|
this.unsubscribeSession = client.subscribeSession(() => {
|
|
330
357
|
const state = client.sessionState;
|
|
331
358
|
if (state.status === "disconnected" && state.requiresReauthentication) void this.reset("Your chat session ended.");
|
|
@@ -446,7 +473,7 @@ var ChatWidget = class {
|
|
|
446
473
|
list.setAttribute("role", "log");
|
|
447
474
|
list.setAttribute("aria-live", "polite");
|
|
448
475
|
const names = new Map(conversation.participants.map((participant) => [participant.appUserId, participant.name]));
|
|
449
|
-
const thread = { conversation, messages: /* @__PURE__ */ new Map(), pending: [], nextCursor: null, list, names };
|
|
476
|
+
const thread = { conversation, messages: /* @__PURE__ */ new Map(), pending: [], nextCursor: null, list, names, cards: { busy: /* @__PURE__ */ new Set(), errors: /* @__PURE__ */ new Map(), expired: /* @__PURE__ */ new Set() } };
|
|
450
477
|
this.thread = thread;
|
|
451
478
|
this.heading.textContent = conversation.displayTitle || this.config.title;
|
|
452
479
|
this.backSlot.replaceChildren(iconButton("back", "All conversations", () => void this.showInbox()));
|
|
@@ -489,11 +516,25 @@ var ChatWidget = class {
|
|
|
489
516
|
if (thread.nextCursor) nodes.push(el("button", { type: "button", className: "older", textContent: "Load earlier messages", onclick: () => void this.loadOlder(thread) }));
|
|
490
517
|
if (ordered.length === 0 && thread.pending.length === 0) nodes.push(el("p", { className: "empty", textContent: "Say hello \u{1F44B}" }));
|
|
491
518
|
let previousSender = null;
|
|
519
|
+
const latestCard = latestCardMessage(ordered);
|
|
492
520
|
for (const message of ordered) {
|
|
521
|
+
const card = message.card;
|
|
522
|
+
if (card?.kind === "handoff" || card?.kind === "form_completed") {
|
|
523
|
+
const notice = el("div", { className: card.kind === "handoff" ? "notice" : "notice receipt", textContent: card.kind === "handoff" ? message.text ?? "" : `\u2713 ${card.title}` });
|
|
524
|
+
notice.setAttribute("role", "status");
|
|
525
|
+
nodes.push(notice);
|
|
526
|
+
previousSender = null;
|
|
527
|
+
continue;
|
|
528
|
+
}
|
|
493
529
|
const mine = message.senderId === this.me;
|
|
494
530
|
const item = el("div", { className: mine ? "msg mine" : "msg" });
|
|
495
531
|
if (!mine && message.senderId !== previousSender) item.append(el("span", { className: "who", textContent: thread.names.get(message.senderId) ?? message.senderId }));
|
|
496
|
-
if (
|
|
532
|
+
if (card?.kind === "link") item.append(this.linkCard(message, card));
|
|
533
|
+
else if (card?.kind === "quick_replies") item.append(this.quickReplies(thread, message, card, ordered));
|
|
534
|
+
else if (message.text) item.append(el("div", { className: "bubble", textContent: message.text }));
|
|
535
|
+
if (latestCard === message && (card?.kind === "link" || card?.kind === "quick_replies")) item.append(this.escapeButton(thread, message));
|
|
536
|
+
const cardError = thread.cards.errors.get(message.id);
|
|
537
|
+
if (cardError) item.append(el("span", { className: "meta card-error", textContent: cardError }));
|
|
497
538
|
if (message.media.length) item.append(el("span", { className: "attachment", textContent: `\u{1F4CE} ${message.media.length === 1 ? "1 attachment" : `${message.media.length} attachments`}` }));
|
|
498
539
|
const time = message.createdAt.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
|
|
499
540
|
item.append(el("span", { className: "meta", textContent: message.revision > 0 ? `${time} \xB7 edited` : time }));
|
|
@@ -508,6 +549,61 @@ var ChatWidget = class {
|
|
|
508
549
|
list.replaceChildren(...nodes);
|
|
509
550
|
if (stickToBottom || nearBottom) list.scrollTop = list.scrollHeight;
|
|
510
551
|
}
|
|
552
|
+
// ---------------------------------------------------------------- cards
|
|
553
|
+
/** A link to a page or form on the site owner's side. Card strings are
|
|
554
|
+
* always text; the SDK only lets https URLs through. */
|
|
555
|
+
linkCard(message, card) {
|
|
556
|
+
const action = el("a", { className: "card-action", href: card.url, target: "_blank", rel: "noopener noreferrer", textContent: card.buttonLabel ?? "Open" });
|
|
557
|
+
action.onclick = () => {
|
|
558
|
+
void this.client?.sendCardEvent(message.id, "opened").catch(() => void 0);
|
|
559
|
+
};
|
|
560
|
+
const node = el("div", { className: "card" }, el("strong", { className: "card-title", textContent: card.title }));
|
|
561
|
+
if (card.description) node.append(el("p", { className: "card-text", textContent: card.description }));
|
|
562
|
+
node.append(action);
|
|
563
|
+
return node;
|
|
564
|
+
}
|
|
565
|
+
/** Buttons stay tappable until the visitor sends anything after the card. A
|
|
566
|
+
* tap posts the option's label as the visitor's message, which arrives
|
|
567
|
+
* through realtime like any other message. */
|
|
568
|
+
quickReplies(thread, message, card, ordered) {
|
|
569
|
+
const answered = thread.cards.expired.has(message.id) || thread.pending.length > 0 || isCardAnswered(message, ordered, this.me);
|
|
570
|
+
const busy = thread.cards.busy.has(message.id);
|
|
571
|
+
const reply = answered ? ordered.slice(ordered.indexOf(message) + 1).find((item) => item.senderId === this.me) : void 0;
|
|
572
|
+
const options = el("div", { className: "options" });
|
|
573
|
+
options.setAttribute("role", "group");
|
|
574
|
+
options.setAttribute("aria-label", card.prompt);
|
|
575
|
+
for (const option of card.options) {
|
|
576
|
+
const chosen = reply?.text === option.label;
|
|
577
|
+
const button = el("button", { type: "button", className: chosen ? "option chosen" : "option", textContent: option.label, disabled: answered || busy });
|
|
578
|
+
button.setAttribute("aria-pressed", String(chosen));
|
|
579
|
+
button.onclick = () => void this.cardAction(thread, message, () => this.client.sendCardEvent(message.id, "quick_reply", option.id));
|
|
580
|
+
options.append(button);
|
|
581
|
+
}
|
|
582
|
+
return el("div", { className: "card" }, el("p", { className: "card-text", textContent: card.prompt }), options);
|
|
583
|
+
}
|
|
584
|
+
escapeButton(thread, message) {
|
|
585
|
+
const button = el("button", { type: "button", className: "escape", textContent: "Talk to a person", disabled: thread.cards.busy.has(message.id) });
|
|
586
|
+
button.onclick = () => void this.cardAction(thread, message, () => this.client.sendCardEvent(message.id, "escape"));
|
|
587
|
+
return button;
|
|
588
|
+
}
|
|
589
|
+
/** Runs a card request with the card disabled meanwhile. The server's reply
|
|
590
|
+
* (the visitor's quick-reply message or a handoff notice) arrives through
|
|
591
|
+
* realtime, so success only clears the busy state. */
|
|
592
|
+
async cardAction(thread, message, request) {
|
|
593
|
+
if (!this.client || thread.cards.busy.has(message.id)) return;
|
|
594
|
+
thread.cards.busy.add(message.id);
|
|
595
|
+
thread.cards.errors.delete(message.id);
|
|
596
|
+
this.renderMessages(false);
|
|
597
|
+
try {
|
|
598
|
+
await request();
|
|
599
|
+
} catch (error) {
|
|
600
|
+
if (errorCode(error) === "CARD_EXPIRED") thread.cards.expired.add(message.id);
|
|
601
|
+
else thread.cards.errors.set(message.id, "Could not send. Try again.");
|
|
602
|
+
} finally {
|
|
603
|
+
thread.cards.busy.delete(message.id);
|
|
604
|
+
}
|
|
605
|
+
if (this.thread === thread) this.renderMessages(false);
|
|
606
|
+
}
|
|
511
607
|
composer() {
|
|
512
608
|
const input = el("textarea", { rows: 1, placeholder: "Write a message\u2026", maxLength: 4e3 });
|
|
513
609
|
input.setAttribute("aria-label", "Message");
|