@convokitapp/chat-embed 1.0.2 → 1.2.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
@@ -112,6 +112,29 @@ websites stops other sites' browsers from using your key. Browsers enforce
112
112
  it; a script can still fake the `Origin` header, which is why the cap and rate
113
113
  limits always apply.
114
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
+ - **The welcome message**, if you set one up, is posted when a visitor opens a
126
+ new chat: your greeting with up to three options shown as tiles, two per
127
+ row. Tapping a tile sends that card straight away.
128
+ - **"Talk to a person"** appears under the newest link or quick-reply card. It
129
+ hands the conversation to your team and pauses automatic replies for 24
130
+ hours.
131
+ - **Handoff and "submitted" notices** appear as small centred lines, as does
132
+ the reply sent when nothing matches ("Our support team will get back to
133
+ you.", or your own wording).
134
+
135
+ There's nothing to configure in the snippet. Older widget versions show the
136
+ same replies as plain text.
137
+
115
138
  ## Platform notes
116
139
 
117
140
  - **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,26 @@ 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
+ .options.grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 6px; }
196
+ .options.grid .option { border-radius: 10px; padding: 10px 8px; min-height: 44px; font-weight: 600; text-align: center; overflow-wrap: anywhere; }
197
+ .escape { align-self: flex-start; border: 0; background: transparent; padding: 2px 0; color: var(--ck-muted); font-size: 12px; text-decoration: underline; }
198
+ .escape:disabled { cursor: default; opacity: .6; }
199
+ .card-error { color: var(--ck-danger); }
200
+ .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; }
201
+ .notice.receipt { color: var(--ck-fg); }
202
+ .branding { padding: 6px; border-top: 1px solid var(--ck-border); text-align: center; font-size: 11px; color: var(--ck-muted); }
203
+ .branding a { color: inherit; font-weight: 600; text-decoration: none; }
204
+ .branding a:hover { text-decoration: underline; }
184
205
  form { display: flex; gap: 8px; padding: 10px; border-top: 1px solid var(--ck-border); align-items: flex-end; }
185
206
  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
207
  form .primary { height: 38px; }
@@ -208,6 +229,7 @@ var FRIENDLY = {
208
229
  };
209
230
  var OWNER_HINTS = {
210
231
  PLAN_UPGRADE_REQUIRED: 'This ConvoKit plan only supports guest mode. Use mode: "guest", or upgrade to Starter for "uid" and "authToken".',
232
+ SUBSCRIPTION_REQUIRED: 'The free ConvoKit plan only supports guest mode. Use mode: "guest", or subscribe in the ConvoKit dashboard for "uid" and "authToken".',
211
233
  PLAN_USER_LIMIT_REACHED: "This ConvoKit plan has reached its monthly active user limit. Upgrade the plan in the ConvoKit dashboard.",
212
234
  WIDGET_USER_LIMIT_REACHED: "The monthly limit of new widget users is reached. Raise it in the ConvoKit dashboard or upgrade the plan."
213
235
  };
@@ -257,7 +279,13 @@ var ChatWidget = class {
257
279
  this.backSlot = el("span");
258
280
  this.headerActions = el("span");
259
281
  this.body = el("div", { className: "body" });
260
- this.panel = el("section", { className: "panel" }, el("header", {}, this.backSlot, this.heading, this.headerActions), this.body);
282
+ this.branding = el(
283
+ "footer",
284
+ { className: "branding", hidden: true },
285
+ "Powered by ",
286
+ el("a", { href: "https://convokit.app/?utm_source=chat-widget&utm_medium=referral", target: "_blank", rel: "noopener", textContent: "ConvoKit" })
287
+ );
288
+ this.panel = el("section", { className: "panel" }, el("header", {}, this.backSlot, this.heading, this.headerActions), this.body, this.branding);
261
289
  this.panel.setAttribute("aria-label", config.title);
262
290
  this.isOpen = !config.isDocked;
263
291
  if (config.isDocked) {
@@ -326,6 +354,7 @@ var ChatWidget = class {
326
354
  }
327
355
  this.client = client;
328
356
  this.session = session;
357
+ this.branding.hidden = !session.showBranding;
329
358
  this.unsubscribeSession = client.subscribeSession(() => {
330
359
  const state = client.sessionState;
331
360
  if (state.status === "disconnected" && state.requiresReauthentication) void this.reset("Your chat session ended.");
@@ -446,7 +475,7 @@ var ChatWidget = class {
446
475
  list.setAttribute("role", "log");
447
476
  list.setAttribute("aria-live", "polite");
448
477
  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 };
478
+ 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
479
  this.thread = thread;
451
480
  this.heading.textContent = conversation.displayTitle || this.config.title;
452
481
  this.backSlot.replaceChildren(iconButton("back", "All conversations", () => void this.showInbox()));
@@ -489,11 +518,25 @@ var ChatWidget = class {
489
518
  if (thread.nextCursor) nodes.push(el("button", { type: "button", className: "older", textContent: "Load earlier messages", onclick: () => void this.loadOlder(thread) }));
490
519
  if (ordered.length === 0 && thread.pending.length === 0) nodes.push(el("p", { className: "empty", textContent: "Say hello \u{1F44B}" }));
491
520
  let previousSender = null;
521
+ const latestCard = latestCardMessage(ordered);
492
522
  for (const message of ordered) {
523
+ const card = message.card;
524
+ if (card?.kind === "handoff" || card?.kind === "form_completed") {
525
+ const notice = el("div", { className: card.kind === "handoff" ? "notice" : "notice receipt", textContent: card.kind === "handoff" ? message.text ?? "" : `\u2713 ${card.title}` });
526
+ notice.setAttribute("role", "status");
527
+ nodes.push(notice);
528
+ previousSender = null;
529
+ continue;
530
+ }
493
531
  const mine = message.senderId === this.me;
494
532
  const item = el("div", { className: mine ? "msg mine" : "msg" });
495
533
  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 }));
534
+ if (card?.kind === "link") item.append(this.linkCard(message, card));
535
+ else if (card?.kind === "quick_replies") item.append(this.quickReplies(thread, message, card, ordered));
536
+ else if (message.text) item.append(el("div", { className: "bubble", textContent: message.text }));
537
+ if (latestCard === message && (card?.kind === "link" || card?.kind === "quick_replies")) item.append(this.escapeButton(thread, message));
538
+ const cardError = thread.cards.errors.get(message.id);
539
+ if (cardError) item.append(el("span", { className: "meta card-error", textContent: cardError }));
497
540
  if (message.media.length) item.append(el("span", { className: "attachment", textContent: `\u{1F4CE} ${message.media.length === 1 ? "1 attachment" : `${message.media.length} attachments`}` }));
498
541
  const time = message.createdAt.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
499
542
  item.append(el("span", { className: "meta", textContent: message.revision > 0 ? `${time} \xB7 edited` : time }));
@@ -508,6 +551,61 @@ var ChatWidget = class {
508
551
  list.replaceChildren(...nodes);
509
552
  if (stickToBottom || nearBottom) list.scrollTop = list.scrollHeight;
510
553
  }
554
+ // ---------------------------------------------------------------- cards
555
+ /** A link to a page or form on the site owner's side. Card strings are
556
+ * always text; the SDK only lets https URLs through. */
557
+ linkCard(message, card) {
558
+ const action = el("a", { className: "card-action", href: card.url, target: "_blank", rel: "noopener noreferrer", textContent: card.buttonLabel ?? "Open" });
559
+ action.onclick = () => {
560
+ void this.client?.sendCardEvent(message.id, "opened").catch(() => void 0);
561
+ };
562
+ const node = el("div", { className: "card" }, el("strong", { className: "card-title", textContent: card.title }));
563
+ if (card.description) node.append(el("p", { className: "card-text", textContent: card.description }));
564
+ node.append(action);
565
+ return node;
566
+ }
567
+ /** Buttons stay tappable until the visitor sends anything after the card. A
568
+ * tap posts the option's label as the visitor's message, which arrives
569
+ * through realtime like any other message. */
570
+ quickReplies(thread, message, card, ordered) {
571
+ const answered = thread.cards.expired.has(message.id) || thread.pending.length > 0 || isCardAnswered(message, ordered, this.me);
572
+ const busy = thread.cards.busy.has(message.id);
573
+ const reply = answered ? ordered.slice(ordered.indexOf(message) + 1).find((item) => item.senderId === this.me) : void 0;
574
+ const options = el("div", { className: card.layout === "grid" ? "options grid" : "options" });
575
+ options.setAttribute("role", "group");
576
+ options.setAttribute("aria-label", card.prompt);
577
+ for (const option of card.options) {
578
+ const chosen = reply?.text === option.label;
579
+ const button = el("button", { type: "button", className: chosen ? "option chosen" : "option", textContent: option.label, disabled: answered || busy });
580
+ button.setAttribute("aria-pressed", String(chosen));
581
+ button.onclick = () => void this.cardAction(thread, message, () => this.client.sendCardEvent(message.id, "quick_reply", option.id));
582
+ options.append(button);
583
+ }
584
+ return el("div", { className: "card" }, el("p", { className: "card-text", textContent: card.prompt }), options);
585
+ }
586
+ escapeButton(thread, message) {
587
+ const button = el("button", { type: "button", className: "escape", textContent: "Talk to a person", disabled: thread.cards.busy.has(message.id) });
588
+ button.onclick = () => void this.cardAction(thread, message, () => this.client.sendCardEvent(message.id, "escape"));
589
+ return button;
590
+ }
591
+ /** Runs a card request with the card disabled meanwhile. The server's reply
592
+ * (the visitor's quick-reply message or a handoff notice) arrives through
593
+ * realtime, so success only clears the busy state. */
594
+ async cardAction(thread, message, request) {
595
+ if (!this.client || thread.cards.busy.has(message.id)) return;
596
+ thread.cards.busy.add(message.id);
597
+ thread.cards.errors.delete(message.id);
598
+ this.renderMessages(false);
599
+ try {
600
+ await request();
601
+ } catch (error) {
602
+ if (errorCode(error) === "CARD_EXPIRED") thread.cards.expired.add(message.id);
603
+ else thread.cards.errors.set(message.id, "Could not send. Try again.");
604
+ } finally {
605
+ thread.cards.busy.delete(message.id);
606
+ }
607
+ if (this.thread === thread) this.renderMessages(false);
608
+ }
511
609
  composer() {
512
610
  const input = el("textarea", { rows: 1, placeholder: "Write a message\u2026", maxLength: 4e3 });
513
611
  input.setAttribute("aria-label", "Message");