@askly/widget 2.9.0 → 2.11.0

package/README.md

@@ -13,7 +13,7 @@ Askly is an **embeddable AI support chat widget** for React and plain HTML. Drop
 
 - 🤖 **AI-powered answers** — resolves customer questions automatically from your knowledge base.
 - 📚 **RAG (docs-grounded)** — replies grounded in your own documentation, not hallucinated.
-- 🎙️ **Voice chat** — customers can talk to the assistant, not just type.
+- 🎙️ **Voice input** — customers can speak their message; it is transcribed and sent as text.
 - 🙋 **Human handoff** — one-click escalation to a live agent when needed.
 - ⚛️ **React + CDN** — use as an npm module, or a single `<script>` tag on any site (no React required).
 - 🎨 **Fully themeable** — colors, logo, position, and copy configured in the portal.
@@ -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
 
@@ -179,6 +179,48 @@ or a self-hosted server older than this feature) the widget falls back to checki
 seconds while the chat is open, as before. If your site sets a Content Security Policy, the Askly
 API origin must be in `connect-src`.
 
+### Voice input
+
+Visitors can press the microphone button, speak, and have their words turned into a message. The
+recording stops when they press done, after about two seconds of silence, or at 60 seconds;
+Escape cancels it. It works in current Chrome, Edge, Safari and Firefox.
+
+The clip is sent to the Askly server, transcribed there in the language spoken, and not stored.
+The browser's own speech recognition is not used, so the audio goes to Askly and nowhere else.
+
+| Mode | What happens to the transcript |
+| :--- | :--- |
+| `"review"` | It is placed in the message box for the visitor to check, edit and send. |
+| `"auto-send"` | It is sent straight away. |
+| off | No microphone button. |
+
+Set the mode in the portal under **Widget**. An embed can narrow it, never widen it:
+
+```javascript
+Askly.init({ appId: "…", voiceInput: "auto-send" }); // or "review", or false to turn it off here
+```
+
+```html
+<script src="…/widget.js" data-app-id="…" data-voice-input="review" async></script>
+```
+
+Each organization has a monthly allowance of transcription minutes, shown in the portal. When it
+is used up, or a visitor records too many clips in a short time, the visitor is asked to type
+instead.
+
+Requirements on the host page:
+
+- It must be served over **https** (browsers refuse the microphone otherwise).
+- If you send a `Permissions-Policy` header, it must allow `microphone` for your own origin, and
+  an iframe that contains the widget needs `allow="microphone"`.
+- With a Content Security Policy, the Askly API origin must be in `connect-src`.
+
+`enableVoiceChat` is the older on/off switch: `false` still turns voice input off for the embed,
+`true` leaves the choice to the portal. Voice input needs a server that offers transcription; with
+an older self-hosted server the microphone button is not shown. The
+`readAloud` option, which spoke replies with the browser's speech synthesis, was removed in
+2.11.0 and is ignored.
+
 ### Asking visitors for their email
 
 Anonymous visitors can't be replied to once they close the tab — the answer just waits in a widget
@@ -227,7 +269,68 @@ 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.startVoiceInput()` / `Askly.stopVoiceInput()` | Open the chat and start recording a voice message; finish the recording and transcribe it. The browser may ask the visitor for the microphone. |
+| `Askly.update(config)` | Change display settings without re-initialising, e.g. `{ themeColor, theme, organizationName, welcomeMessage, buttonShape }`. `voiceInput` can be narrowed here too. |
+| `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. |
+| `voice:start` | none | Voice input started recording. |
+| `voice:stop` | `{ durationMs }` | Recording ended and the clip is being transcribed. |
+| `voice:transcript` | `{ text, language? }` | The transcript arrived, before it is placed in the message box or sent. |
+| `voice:error` | `{ code }` | Voice input failed: `insecure`, `unsupported`, `denied`, `no-microphone`, `no-speech`, `no-audio`, `limit`, `disabled`, `network` or `failed`. |
+| `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/core/events.d.ts

@@ -45,6 +45,21 @@ export interface AsklyEventMap {
     "greeting:shown": undefined;
     "greeting:clicked": undefined;
     "greeting:dismissed": undefined;
+    /** Voice input started recording. */
+    "voice:start": undefined;
+    /** Recording ended; the clip is about to be transcribed. */
+    "voice:stop": {
+        durationMs: number;
+    };
+    /** The transcript, before it is placed in the message box or sent. */
+    "voice:transcript": {
+        text: string;
+        language?: string;
+    };
+    /** Voice input failed: insecure, unsupported, denied, no-microphone, no-speech, no-audio, limit, disabled, network, failed. */
+    "voice:error": {
+        code: string;
+    };
     /** A request failed in a way the visitor was told about. */
     error: {
         message: string;
@@ -76,6 +91,10 @@ export type AsklyCommand = {
 } | {
     type: "showArticle";
     articleId: string;
+} | {
+    type: "startVoiceInput";
+} | {
+    type: "stopVoiceInput";
 } | {
     type: "update";
     config: Record<string, any>;

package/dist/core/speech.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Microphone capture for voice input.
+ *
+ * Records one short clip with MediaRecorder; the widget posts it to the Askly server, which
+ * returns the transcript. Nothing here touches the browser's own speech recognition, so the
+ * audio goes to Askly and nowhere else.
+ */
+export type VoiceInputMode = "off" | "review" | "auto-send";
+/** Why voice input could not start or finish. */
+export type VoiceErrorCode = "insecure" | "unsupported" | "denied" | "no-microphone" | "no-speech" | "no-audio" | "limit" | "disabled" | "network" | "failed";
+export interface VoiceClip {
+    blob: Blob;
+    durationMs: number;
+    /**
+     * "no-speech": recording gave up because nobody spoke. "no-audio": the microphone delivered
+     * silence throughout. Otherwise "ok", which includes every clip the visitor ended themselves:
+     * whether it contains words is then for the transcription to say, not for a level meter.
+     */
+    outcome: "ok" | "no-speech" | "no-audio";
+}
+export interface Recording {
+    /** Finish and hand the clip to `onDone`. */
+    stop(): void;
+    /** Throw the clip away. `onDone` is not called. */
+    cancel(): void;
+}
+export interface RecordingOptions {
+    maxMs: number;
+    /** Stop this long after the speaker goes quiet. */
+    silenceMs: number;
+    /** Stop when nothing has been said for this long from the start. */
+    noSpeechMs: number;
+    /** About ten times a second while recording. `level` is 0 to 1. */
+    onMeter: (level: number, elapsedMs: number) => void;
+    onDone: (clip: VoiceClip) => void;
+}
+export declare function normalizeVoiceInputMode(value: any): VoiceInputMode | undefined;
+/** Why recording cannot work on this page, or null when it can. */
+export declare function voiceInputBlocker(): VoiceErrorCode | null;
+/** Ask for the microphone and start recording. Rejects with `{ code: VoiceErrorCode }`. */
+export declare function startRecording(options: RecordingOptions): Promise<Recording>;
+/** What to tell the visitor. */
+export declare function voiceErrorMessage(code: VoiceErrorCode): string;

package/dist/core/types.d.ts

@@ -7,7 +7,10 @@ export interface ChatWidgetProps {
     theme?: "light" | "dark" | "auto";
     position?: "left" | "right";
     orgServerRoute: string;
+    voiceInput?: false | "review" | "auto-send";
+    /** @deprecated use `voiceInput`. `false` turns voice input off for this embed. */
     enableVoiceChat?: boolean;
+    /** @deprecated removed in 2.11.0; ignored. */
     readAloud?: boolean;
     welcomeMessage?: string;
     placeholderText?: string;

package/dist/icons.d.ts

@@ -8,9 +8,6 @@ export declare const X: ({ size, color, strokeWidth, ...rest }: IconProps) => Re
 export declare const Minus: ({ size, color, strokeWidth, ...rest }: IconProps) => React.ReactSVGElement;
 export declare const ArrowUp: ({ size, color, strokeWidth, ...rest }: IconProps) => React.ReactSVGElement;
 export declare const Mic: ({ size, color, strokeWidth, ...rest }: IconProps) => React.ReactSVGElement;
-export declare const MicOff: ({ size, color, strokeWidth, ...rest }: IconProps) => React.ReactSVGElement;
-export declare const Volume2: ({ size, color, strokeWidth, ...rest }: IconProps) => React.ReactSVGElement;
-export declare const VolumeX: ({ size, color, strokeWidth, ...rest }: IconProps) => React.ReactSVGElement;
 export declare const Home: ({ size, color, strokeWidth, ...rest }: IconProps) => React.ReactSVGElement;
 export declare const Compass: ({ size, color, strokeWidth, ...rest }: IconProps) => React.ReactSVGElement;
 export declare const MessageSquare: ({ size, color, strokeWidth, ...rest }: IconProps) => React.ReactSVGElement;

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;
@@ -8,7 +9,10 @@ export interface AsklyConfig {
     position?: "left" | "right";
     themeColor?: string;
     theme?: "light" | "dark" | "auto";
+    voiceInput?: false | "review" | "auto-send";
+    /** @deprecated use `voiceInput`. */
     enableVoiceChat?: boolean;
+    /** @deprecated removed in 2.11.0; ignored. */
     readAloud?: boolean;
     welcomeMessage?: string;
     placeholderText?: string;
@@ -75,5 +79,46 @@ 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;
+    /** Open the chat and start recording a voice message. The browser may ask for the microphone. */
+    startVoiceInput: () => void;
+    /** Finish the recording in progress and transcribe it. */
+    stopVoiceInput: () => 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 };