@askly/widget 2.9.0 → 2.10.0

package/README.md

@@ -163,8 +163,8 @@ Askly.init({ appId: "YOUR_APP_ID", greeting: { message: "Need a hand?", delayMs:
 <script src="…/widget.js" data-app-id="YOUR_APP_ID" data-greeting="false" async></script>
 ```
 
-The widget dispatches `askly:greeting:shown`, `askly:greeting:clicked` and
-`askly:greeting:dismissed` on `window` for analytics.
+For analytics, listen for `greeting:shown`, `greeting:clicked` and `greeting:dismissed` with
+`Askly.on()` (see the JavaScript API below).
 
 ### Live replies
 
@@ -227,7 +227,63 @@ Notes:
 - **Optimized:** on non-matching pages the path check runs *before* anything mounts, so there's no DOM node, no React root, and no config network request — the SDK does essentially nothing.
 - The decision is evaluated once at init; it's a UX targeting tool, not a security boundary (the script can still be loaded on any page).
 
-## Lifecycle Callbacks
+## JavaScript API
+
+Everything below is on the global `Askly` (script tag) or the default export (npm). Calls made
+straight after `Askly.init()` are held and carried out once the widget has mounted.
+
+### Controlling the widget
+
+| Method | What it does |
+| :--- | :--- |
+| `Askly.open()` / `Askly.show()` | Open the chat panel. |
+| `Askly.close()` / `Askly.hide()` | Close it. |
+| `Askly.toggle()` | Open if closed, close if open. |
+| `Askly.showSpace(space)` | Open on `"home"`, `"messages"` or `"help"`. |
+| `Askly.showNewMessage(text?)` | Open the chat with the message box focused, optionally pre-filled. Nothing is sent. |
+| `Askly.sendMessage(text)` | Open the chat and send `text` as the visitor. It passes the same checks as a typed message; if one is pending (email required, security check) it waits in the message box. |
+| `Askly.showArticle(id)` | Open a help article by id. |
+| `Askly.update(config)` | Change display settings without re-initialising, e.g. `{ themeColor, theme, organizationName, welcomeMessage, buttonShape }`. |
+| `Askly.isOpen()` | `true` while the panel is open. |
+| `Askly.getUnreadCount()` | Agent replies the visitor has not seen (the launcher badge). |
+| `Askly.getVisitorId()` | This browser's anonymous visitor id (`""` before mount). |
+| `Askly.ready()` | A promise that resolves once the widget has mounted and applied its configuration. |
+
+```javascript
+document.querySelector("#contact-sales").addEventListener("click", () => {
+  Askly.showNewMessage("Hi, I'd like to talk about the Business plan.");
+});
+```
+
+### Events
+
+`Askly.on(name, handler)` returns a function that removes the listener; `Askly.off(name, handler)`
+and `Askly.once(name, handler)` are also available. A handler that throws is logged and does not
+affect the widget.
+
+| Event | Payload | When |
+| :--- | :--- | :--- |
+| `ready` | `{ visitorId }` | The widget has mounted and applied its configuration. |
+| `open` / `close` | none | The panel was opened or closed. |
+| `message:sent` | `{ text, conversationId }` | The visitor sent a message. |
+| `message:received` | `{ text, conversationId, from, messageId }` | A reply arrived; `from` is `"ai"` or `"agent"`. |
+| `unread` | `{ count }` | The number of unseen agent replies changed. |
+| `escalated` | `{ conversationId }` | The conversation was handed to a human. |
+| `lead:captured` | none | The visitor left an email address. |
+| `identify:success` / `identify:error` | `{ userId, status? }` | The server accepted or refused `identify()`. |
+| `greeting:shown` / `greeting:clicked` / `greeting:dismissed` | none | Greeting bubble activity. |
+| `error` | `{ message, status? }` | A message could not be sent. |
+
+```javascript
+Askly.on("message:received", ({ from }) => analytics.track("support_reply", { from }));
+Askly.on("unread", ({ count }) => { document.title = count ? `(${count}) Acme` : "Acme"; });
+```
+
+TypeScript users can import the payload types: `import type { AsklyEventMap } from "@askly/widget"`.
+
+### Callbacks at init (older style)
+
+These still work and are called alongside the events above.
 
 Callbacks are functions, so they can only be attached in code (not from the portal):
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type AsklyEventMap, type AsklyEventName, type AsklyEventHandler, type AsklySpace } from "./core/events";
 import { type AsklyIdentity } from "./identity";
 export interface AsklyConfig {
     appId?: string;
@@ -75,5 +76,42 @@ declare const Askly: {
     close: () => void;
     /** Toggle the chat panel. */
     toggle: () => void;
+    /** Aliases of open() / close(). */
+    show: () => void;
+    hide: () => void;
+    /** Whether the chat panel is open right now. */
+    isOpen: () => boolean;
+    /** Agent replies the visitor has not seen yet (the number on the launcher badge). */
+    getUnreadCount: () => number;
+    /** This browser's anonymous visitor id, or "" before the widget has mounted. */
+    getVisitorId: () => string;
+    /**
+     * Listen for a widget event. Returns a function that removes the listener.
+     *
+     *   Askly.on("message:received", ({ text, from }) => analytics.track("support_reply", { from }));
+     *   Askly.on("unread", ({ count }) => setBadge(count));
+     */
+    on: <K extends keyof AsklyEventMap>(name: K, handler: AsklyEventHandler<K>) => (() => void);
+    off: <K_1 extends keyof AsklyEventMap>(name: K_1, handler: AsklyEventHandler<K_1>) => void;
+    once: <K_2 extends keyof AsklyEventMap>(name: K_2, handler: AsklyEventHandler<K_2>) => (() => void);
+    /** Resolves when the widget has mounted and applied its configuration. */
+    ready: () => Promise<void>;
+    /** Open the widget on a section: "home", "messages" or "help". */
+    showSpace: (space: AsklySpace) => void;
+    /** Open the chat with the composer ready, optionally pre-filled. Nothing is sent. */
+    showNewMessage: (text?: string) => void;
+    /**
+     * Open the chat and send a message as the visitor. It goes through the same checks as a
+     * typed message; if one is pending (email required, security check) it waits in the composer.
+     */
+    sendMessage: (text: string) => void;
+    /** Open a help article by id, as listed in the Help tab. */
+    showArticle: (articleId: string) => void;
+    /**
+     * Change display settings on the mounted widget without re-initialising: the fields the
+     * portal controls, e.g. `{ themeColor, theme, organizationName, welcomeMessage, buttonShape }`.
+     */
+    update: (config: Record<string, any>) => void;
 };
 export default Askly;
+export type { AsklyIdentity, AsklyEventMap, AsklyEventName, AsklyEventHandler, AsklySpace };