@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 +208 -1
- package/dist/bundle.min.js +27 -27
- package/package.json +3 -2
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` —
|
|
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.
|