@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 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.panel = el("section", { className: "panel" }, el("header", {}, this.backSlot, this.heading, this.headerActions), this.body);
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 (message.text) item.append(el("div", { className: "bubble", textContent: message.text }));
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");