@telnyx/ai-agent-widget 0.30.0 → 0.31.1

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.
Files changed (3) hide show
  1. package/README.md +104 -2
  2. package/dist/bundle.min.js +22 -22
  3. package/package.json +12 -13
package/README.md CHANGED
@@ -1,18 +1,43 @@
1
1
  # Telnyx Voice AI Widget
2
2
 
3
+ [![npm version](https://img.shields.io/npm/v/@telnyx/ai-agent-widget.svg)](https://www.npmjs.com/package/@telnyx/ai-agent-widget)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@telnyx/ai-agent-widget.svg)](https://www.npmjs.com/package/@telnyx/ai-agent-widget)
5
+
3
6
  ## Overview
4
7
 
5
8
  The Telnyx Voice AI Widget is a web component that allows you to easily integrate voice capabilities into your web applications. It provides a simple interface for making and receiving calls, as well as handling voice interactions using Telnyx's Voice AI services.
6
9
 
7
- ## Usage
10
+ ## Installation
8
11
 
9
- To use the Telnyx Voice AI Widget, you need to include the widget script in your HTML file and initialize it with your Telnyx AI Assistant ID
12
+ ### Via CDN (recommended for quick start)
10
13
 
11
14
  ```html
12
15
  <telnyx-ai-agent agent-id="assistant-xxx"></telnyx-ai-agent>
13
16
  <script async src="https://unpkg.com/@telnyx/ai-agent-widget"></script>
14
17
  ```
15
18
 
19
+ ### Via npm/yarn
20
+
21
+ ```bash
22
+ npm install @telnyx/ai-agent-widget
23
+ # or
24
+ yarn add @telnyx/ai-agent-widget
25
+ ```
26
+
27
+ Then import in your application:
28
+
29
+ ```javascript
30
+ import '@telnyx/ai-agent-widget';
31
+ ```
32
+
33
+ ## Usage
34
+
35
+ To use the Telnyx Voice AI Widget, add the custom element to your HTML:
36
+
37
+ ```html
38
+ <telnyx-ai-agent agent-id="assistant-xxx"></telnyx-ai-agent>
39
+ ```
40
+
16
41
  ### Call Options
17
42
 
18
43
  You can customize the call options by adding attributes to the `<telnyx-ai-agent>` tag:
@@ -23,6 +48,83 @@ You can customize the call options by adding attributes to the `<telnyx-ai-agent
23
48
  - [`call-custom-headers`](https://developers.telnyx.com/development/webrtc/js-sdk/interfaces/icalloptions#customheaders)
24
49
  - [`call-audio`](https://developers.telnyx.com/development/webrtc/js-sdk/interfaces/icalloptions#audio)
25
50
 
51
+ ### VAD (Voice Activity Detection) Options
52
+
53
+ Configure Voice Activity Detection for speech detection and latency measurement by passing a JSON object to the `vad` attribute:
54
+
55
+ ```html
56
+ <telnyx-ai-agent
57
+ agent-id="assistant-xxx"
58
+ vad='{"volumeThreshold": 10, "silenceDurationMs": 500, "minSpeechDurationMs": 100}'
59
+ ></telnyx-ai-agent>
60
+ ```
61
+
62
+ **Available VAD options:**
63
+
64
+ | Option | Type | Default | Description |
65
+ | --------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
66
+ | `volumeThreshold` | `number` | `10` | Volume threshold (0-255) for detecting speech. Audio levels above this value are considered speech. |
67
+ | `silenceDurationMs` | `number` | `1000` | Duration of silence (ms) before triggering "thinking" state. Lower values = faster response but may cut off natural pauses. |
68
+ | `minSpeechDurationMs` | `number` | `100` | Minimum speech duration (ms) to count as real user speech. Filters out brief noise spikes. |
69
+ | `maxLatencyMs` | `number` | `undefined` | Maximum latency (ms) to report. Values above this are considered stale and won't be reported. |
70
+
71
+ **Example configurations:**
72
+
73
+ ```html
74
+ <!-- Fast-paced conversation (aggressive turn detection) -->
75
+ <telnyx-ai-agent
76
+ agent-id="assistant-xxx"
77
+ vad='{"silenceDurationMs": 500, "minSpeechDurationMs": 80}'
78
+ ></telnyx-ai-agent>
79
+
80
+ <!-- Thoughtful conversation (tolerant of pauses) -->
81
+ <telnyx-ai-agent
82
+ agent-id="assistant-xxx"
83
+ vad='{"silenceDurationMs": 1500, "minSpeechDurationMs": 150}'
84
+ ></telnyx-ai-agent>
85
+
86
+ <!-- Noisy environment -->
87
+ <telnyx-ai-agent
88
+ agent-id="assistant-xxx"
89
+ vad='{"volumeThreshold": 20, "minSpeechDurationMs": 200}'
90
+ ></telnyx-ai-agent>
91
+ ```
92
+
93
+ ### Latency Display Options
94
+
95
+ Control whether latency measurements are included in transcript messages. Both options default to `false`.
96
+
97
+ | Attribute | Type | Default | Description |
98
+ | ----------------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------ |
99
+ | `show-user-perceived-latency` | `boolean` | `false` | Include `userPerceivedLatencyMs` in transcript items (time from user stop speaking to agent response). |
100
+ | `show-greeting-latency` | `boolean` | `false` | Include `greetingLatencyMs` in transcript items (time for initial agent greeting). |
101
+
102
+ ```html
103
+ <!-- Enable latency tracking in transcript messages -->
104
+ <telnyx-ai-agent
105
+ agent-id="assistant-xxx"
106
+ show-user-perceived-latency
107
+ show-greeting-latency
108
+ ></telnyx-ai-agent>
109
+ ```
110
+
111
+ When enabled, latency values are attached to assistant transcript items and can be accessed via the `transcript.item` event:
112
+
113
+ ```javascript
114
+ widget.addEventListener('transcript.item', function (event) {
115
+ const { role, content, userPerceivedLatencyMs, greetingLatencyMs } =
116
+ event.detail;
117
+ if (role === 'assistant') {
118
+ if (userPerceivedLatencyMs !== undefined) {
119
+ console.log('Response latency:', userPerceivedLatencyMs, 'ms');
120
+ }
121
+ if (greetingLatencyMs !== undefined) {
122
+ console.log('Greeting latency:', greetingLatencyMs, 'ms');
123
+ }
124
+ }
125
+ });
126
+ ```
127
+
26
128
  ## Events and Callbacks
27
129
 
28
130
  The widget emits DOM CustomEvents that you can listen to for tracking analytics, updating UI, or integrating with your application logic. Event names match `@telnyx/ai-agent-lib` for consistency.