@askly/widget 2.10.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.
@@ -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
@@ -243,7 +285,8 @@ straight after `Askly.init()` are held and carried out once the widget has mount
 | `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.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). |
@@ -272,6 +315,10 @@ affect the widget.
 | `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

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

@@ -9,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;
@@ -107,6 +110,10 @@ declare const Askly: {
     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 }`.