@telnyx/ai-agent-widget 0.35.0 → 0.36.0-beta.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
@@ -49,7 +49,66 @@ You can customize the call options by adding attributes to the `<telnyx-ai-agent
49
49
  - [`call-audio`](https://developers.telnyx.com/development/webrtc/js-sdk/interfaces/icalloptions#audio)
50
50
  - `trickle-ice` — enable/disable trickle ICE. Defaults to `true`; set `trickle-ice="false"` to disable.
51
51
  - `prefetch-ice-candidates` — enable/disable ICE candidate prefetching. Defaults to `true`; set `prefetch-ice-candidates="false"` to disable.
52
- - `chat-mode` — enable text-only mode (no microphone). See [Chat Mode](#chat-mode) below.
52
+ - `chat-mode` — hide the audio but still place a call. See [Chat Mode](#chat-mode) below.
53
+ - `text-only` — a typing-only widget with no call at all. See [Text-Only Mode](#text-only-mode) below.
54
+
55
+ ### Text-Only Mode
56
+
57
+ `text-only` is the right choice when the visitor should only ever type. There is
58
+ no call: no microphone permission prompt, no audio, no WebRTC, and no voice
59
+ minutes. Turns go to the assistant over a WebSocket to voice-sdk-proxy and the
60
+ answer streams back as text.
61
+
62
+ ```html
63
+ <telnyx-ai-agent agent-id="assistant-xxx" text-only></telnyx-ai-agent>
64
+ ```
65
+
66
+ The widget opens straight into the transcript panel — there is no "Start Call"
67
+ button and no collapsed state, since a visitor who is typing is already engaged
68
+ and collapsing would only offer something this mode cannot do.
69
+
70
+ The page still needs nothing but the assistant id. The assistant chat API
71
+ requires a Telnyx API key, which public page JavaScript cannot hold, so
72
+ voice-sdk-proxy performs the same trust move it already performs for anonymous
73
+ voice logins and no credential reaches the browser.
74
+
75
+ #### Requirements
76
+
77
+ The assistant must have `telephony_settings.supports_unauthenticated_web_calls`
78
+ enabled — the same opt-in the voice widget requires. It is what marks an
79
+ assistant as reachable by anonymous web visitors.
80
+
81
+ #### Events
82
+
83
+ The documented DOM events fire on a text-only widget the same as on a voice one:
84
+ `agent.connected` (its detail carries the `conversationId` rather than the
85
+ voice path's `dc` / `region` / `callReportId`, which have no counterpart here),
86
+ `agent.disconnected`, `agent.error`, `transcript.item` and
87
+ `conversation.agent.state`.
88
+
89
+ `client.tools.configured` is deliberately not dispatched: the assistant chat API
90
+ is request/response, so a tool announced on this path could never be invoked.
91
+
92
+ #### Connection loss
93
+
94
+ If the connection to the assistant drops, the widget shows its error state with
95
+ a retry control rather than sitting on a loading spinner. Retrying reconnects and
96
+ resumes the same conversation.
97
+
98
+ #### text-only vs chat-mode
99
+
100
+ | | `chat-mode` | `text-only` |
101
+ | -------------------------- | ----------- | ----------- |
102
+ | Microphone prompt | no | no |
103
+ | Audio played | no | no |
104
+ | Places a WebRTC call | **yes** | no |
105
+ | Voice minutes / TTS billed | **yes** | no |
106
+ | Image attachments | yes | no |
107
+ | Client-side tools | yes | no |
108
+ | Barge-in / interrupt | yes | n/a |
109
+
110
+ Use `chat-mode` when the visitor may switch to speaking, or when you need
111
+ attachments or client-side tools. Use `text-only` when they never will.
53
112
 
54
113
  ### Chat Mode
55
114
 
@@ -96,6 +155,10 @@ This means the transcript and conversation context are **not preserved** across
96
155
 
97
156
  After a conversation ends in chat mode, the widget will **not** auto-restart even if `chat-mode` remains set. The user must interact again or you must remove and re-add the element.
98
157
 
158
+ Note that `chat-mode` still places a full WebRTC call underneath — the
159
+ assistant's speech is synthesized and then discarded. If the visitor will only
160
+ ever type, [`text-only`](#text-only-mode) avoids that entirely.
161
+
99
162
  ### Region
100
163
 
101
164
  Pin signalling to a specific region with the `region` attribute. When set, the WebRTC SDK routes the connection through `<region>.rtc.telnyx.com` instead of the default anycast `rtc.telnyx.com`. Useful when anycast DNS routes a client to a sub-optimal datacenter.
@@ -315,3 +378,147 @@ To develop the Telnyx Voice AI Widget, you can clone the repository and run the
315
378
  yarn install --immutable
316
379
  yarn dev
317
380
  ```
381
+
382
+ ### Linked library development
383
+
384
+ The library exports `dist/index.js`. After linking, rebuild the library whenever
385
+ its source changes; linking alone does not compile it.
386
+
387
+ ```sh
388
+ # In telnyx-voice-ai-lib
389
+ yarn build
390
+ npm link
391
+
392
+ # In telnyx-voice-ai-widget
393
+ npm link @telnyx/ai-agent-lib
394
+ yarn dev --force
395
+ ```
396
+
397
+ Reload the browser after rebuilding. `--force` refreshes Vite's dependency cache
398
+ after switching from an installed package to a link. The development config also
399
+ excludes the library from dependency optimization so subsequent builds are loaded
400
+ directly. Use either this link workflow or `setup:local-library`; that setup command
401
+ replaces the link with a copied build.
402
+
403
+ ### Force an audio RTC gateway
404
+
405
+ Pass `rtc-ip` and `rtc-port` together to select the upstream voice gateway through
406
+ VSP. These map to the SDK's `rtcIp` (lowercase `p`) and numeric `rtcPort` options,
407
+ which become `rtc_ip` and `rtc_port` in the WebSocket URL. The browser still connects
408
+ to VSP; these attributes do not replace its public hostname. They apply to audio
409
+ and legacy `chat-mode`; text-only conversations do not use a voice gateway.
410
+
411
+ ```html
412
+ <telnyx-ai-agent
413
+ agent-id="assistant-xxx"
414
+ environment="production"
415
+ rtc-ip="10.0.0.1"
416
+ rtc-port="14938"
417
+ ></telnyx-ai-agent>
418
+ ```
419
+
420
+ Omit both attributes for normal gateway discovery. `rtc-port` must be a valid
421
+ integer port number. Updating either attribute recreates the voice connection.
422
+
423
+ ### Text-only transcript, errors and retry
424
+
425
+ The typing-only widget renders the library's `transcript.updated` snapshots.
426
+ Each DOM `transcript.updated` event has the complete `TranscriptItem[]` as its
427
+ `detail`; replace the displayed array. It includes final corrections, empty
428
+ replacements, user revisions and deletions. The existing DOM `transcript.item`
429
+ event retains the actual library fragment payload. Do not append snapshots to a
430
+ fragment-based transcript or consume both events as new messages.
431
+
432
+ ```js
433
+ widget.addEventListener('transcript.updated', ({ detail }) => {
434
+ renderTranscript(detail); // Replace the displayed transcript.
435
+ });
436
+ widget.addEventListener('agent.error', ({ detail }) => {
437
+ console.log(detail.scope, detail.reason, detail.message);
438
+ });
439
+ ```
440
+
441
+ For text mode, `agent.error` detail includes `message`, `name`, and `scope`
442
+ (`connection`, `response`, or `send`). Response errors also retain the backend
443
+ `reason`, including `stream_truncated`, `stream_failed`, and `assistant_error`.
444
+ These errors leave partial replies visible. Connection failures offer Reconnect
445
+ inside the chat. Retry reuses the same agent, transcript and server-issued
446
+ conversation ID; changing the assistant, environment, version, conversation ID,
447
+ region, debug setting or URL starts a fresh session and clears its draft.
448
+
449
+ A send clears its draft only after proxy acceptance. A rejected send retains the
450
+ draft with an error. Further sending is disabled until `response.text.done` or
451
+ `response.error`, not merely until acceptance or the first fragment. Visitors can
452
+ compose their next draft while a reply streams. Voice and the older `chat-mode`
453
+ retain their existing call-based sending behavior.
454
+
455
+ ### Ending and starting a text chat
456
+
457
+ **End chat** closes the text WebSocket, including during login or an active
458
+ reply, and shows a compact start button with the Telnyx logo, with no input or
459
+ live connection. The chat stays
460
+ ended until the visitor explicitly starts it again; changing attributes while
461
+ ended does not reconnect it. Ending closes this widget session; it does not
462
+ delete the server's conversation record. Saying goodbye in the transcript does
463
+ not automatically end the connection.
464
+
465
+ **Start new chat** creates a new agent, clears the displayed transcript and draft,
466
+ and requests a fresh server conversation ID. If the embed explicitly supplies
467
+ `conversation-id`, the control instead says **Start chat**: the new agent respects
468
+ that configured ID and resumes its server context with an empty local transcript.
469
+ Remove or change that attribute to select a different conversation.
470
+
471
+ **Reconnect** after an unexpected network interruption still preserves the same
472
+ agent, server conversation ID, transcript and draft. Intentional ending emits the
473
+ normal final state/disconnected events once for an established session, without
474
+ an unexpected-loss error; cancelling an uncompleted login does not announce a
475
+ connected/disconnected pair.
476
+
477
+ ### Local text-only development
478
+
479
+ The published dependency pin remains unchanged until the library fixes have been
480
+ released. This branch requires the updated text library API; a plain install of
481
+ an older package is not sufficient. After installing dependencies in both sibling
482
+ repositories, run these commands from the widget repository:
483
+
484
+ ```sh
485
+ yarn install --frozen-lockfile
486
+ yarn setup:local-library
487
+ yarn test
488
+ yarn typecheck
489
+ yarn lint:check
490
+ yarn build
491
+ ```
492
+
493
+ `setup:local-library` builds `../telnyx-voice-ai-lib` and copies its built package
494
+ into the widget's `node_modules`. It does not change either repository's source,
495
+ the widget's dependency pin, or its lockfile. To use another checkout, pass its
496
+ path: `yarn setup:local-library ../another-library-checkout`. Run setup again after
497
+ a dependency install or library change. The copied package avoids bringing a
498
+ second React/Preact dependency tree into the bundle. The predev, pretest and
499
+ prebuild checks reject an installed library missing the required snapshot API.
500
+ Before merge/release, publish the library fixes and update the widget's dependency
501
+ pin and lockfile to that real released version. No publication is part of local
502
+ setup.
503
+
504
+ To run the widget locally against VSP:
505
+
506
+ ```sh
507
+ yarn dev --host 127.0.0.1 --port 5173 --strictPort
508
+ ```
509
+
510
+ Open `http://127.0.0.1:5173/`. In `index.html`, set `agent-id` to the assistant
511
+ being tested and enable `text-only="true"`.
512
+
513
+ For a DEV run, use a public DEV assistant enabled for anonymous access, set
514
+ `environment="development"`, and omit `version-id`. The library uses
515
+ `wss://rtcdev.telnyx.com`. That endpoint must run the VSP text-login, keepalive and
516
+ stream-termination changes and be able to reach the private Assistants service.
517
+ A successful WebSocket upgrade alone does not establish text-login readiness.
518
+
519
+ For a configured local or alternate DEV VSP, set `text-chat-url` to its WebSocket
520
+ URL. This attribute applies only to `text-only` and overrides environment/region
521
+ URL selection. Use an endpoint you control: chat content is sent to that URL.
522
+ Use `wss://` from an HTTPS embedding page; HTTP localhost development can use
523
+ `ws://`. A local VSP still needs its private dependencies, TLS and internal-service
524
+ configuration.