@skippr/live-agent-sdk 0.22.0 → 0.24.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 +146 -18
- package/dist/types/hooks/usePhaseUpdates.d.ts +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,16 +2,52 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://skippr.ai) [](https://www.npmjs.com/package/@skippr/live-agent-sdk)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Embed an autonomous product specialist that sees, speaks, and acts in real time — handling demos, onboarding, training, and support inside your app with a single React component or script tag.
|
|
6
|
+
|
|
7
|
+
## Key Features
|
|
8
|
+
|
|
9
|
+
- **Real-time voice** — two-way audio with live transcription
|
|
10
|
+
- **Screen sharing** — user shares their screen so the agent can see and guide
|
|
11
|
+
- **Chat + transcript** — text messaging with voice transcripts merged into one thread
|
|
12
|
+
- **Session agenda** — structured phases with progress tracking
|
|
13
|
+
- **Flexible auth** — email OTP (direct auth) or backend-signed JWT (secret mode)
|
|
14
|
+
- **Drop-in integration** — one React component or script tag, no WebRTC code needed
|
|
15
|
+
- **Host-safe styles** — prefixed CSS that won't conflict with your app
|
|
16
|
+
|
|
17
|
+
## Prerequisites
|
|
18
|
+
|
|
19
|
+
You need an `agentId` and `appKey` from the [Skippr Platform](https://specialist.skippr.ai/).
|
|
20
|
+
|
|
21
|
+
1. **Sign up** at [specialist.skippr.ai](https://specialist.skippr.ai/)
|
|
22
|
+
2. **Create an agent** and copy the `agentId` from the agent details page
|
|
23
|
+
3. **Create an App Key** in Settings and copy the `appKey` — one App Key works for all your agents
|
|
6
24
|
|
|
7
25
|
## Installation
|
|
8
26
|
|
|
27
|
+
### React
|
|
28
|
+
|
|
9
29
|
```bash
|
|
10
30
|
npm install @skippr/live-agent-sdk
|
|
11
31
|
```
|
|
12
32
|
|
|
33
|
+
### Script Tag
|
|
34
|
+
|
|
35
|
+
No install needed. Add this to any webpage:
|
|
36
|
+
|
|
37
|
+
```html
|
|
38
|
+
<script src="https://unpkg.com/@skippr/live-agent-sdk/dist/skippr-sdk.js"></script>
|
|
39
|
+
<script>
|
|
40
|
+
Skippr.initialize({
|
|
41
|
+
agentId: 'your_agent_id',
|
|
42
|
+
appKey: 'pk_live_your_key',
|
|
43
|
+
});
|
|
44
|
+
</script>
|
|
45
|
+
```
|
|
46
|
+
|
|
13
47
|
## Quick Start
|
|
14
48
|
|
|
49
|
+
### React
|
|
50
|
+
|
|
15
51
|
```tsx
|
|
16
52
|
import { LiveAgent } from '@skippr/live-agent-sdk';
|
|
17
53
|
import '@skippr/live-agent-sdk/styles';
|
|
@@ -24,7 +60,95 @@ function App() {
|
|
|
24
60
|
/>
|
|
25
61
|
);
|
|
26
62
|
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Script Tag
|
|
66
|
+
|
|
67
|
+
```html
|
|
68
|
+
<script src="https://unpkg.com/@skippr/live-agent-sdk/dist/skippr-sdk.js"></script>
|
|
69
|
+
<script>
|
|
70
|
+
Skippr.initialize({
|
|
71
|
+
agentId: 'your_agent_id',
|
|
72
|
+
appKey: 'pk_live_your_key',
|
|
73
|
+
});
|
|
74
|
+
</script>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Authentication
|
|
78
|
+
|
|
79
|
+
The SDK supports two identity modes, configured per App Key in the Skippr dashboard.
|
|
80
|
+
|
|
81
|
+
### Direct Auth (default)
|
|
82
|
+
|
|
83
|
+
Users log in via email OTP inside the widget. No backend integration needed. The SDK handles the full OTP flow: email input, code verification, and token persistence automatically.
|
|
84
|
+
|
|
85
|
+
**React:**
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
<LiveAgent agentId="your_agent_id" appKey="pk_live_your_key" />
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
**Script tag:**
|
|
92
|
+
|
|
93
|
+
```js
|
|
94
|
+
Skippr.initialize({
|
|
95
|
+
agentId: 'your_agent_id',
|
|
96
|
+
appKey: 'pk_live_your_key',
|
|
97
|
+
});
|
|
98
|
+
```
|
|
27
99
|
|
|
100
|
+
### Secret Mode
|
|
101
|
+
|
|
102
|
+
Your backend signs a JWT with the App Key's identity secret and passes it as `userToken`. The SDK exchanges it for a bearer token server-side and skips the login form entirely.
|
|
103
|
+
|
|
104
|
+
**Step 1: Generate a signed JWT on your backend**
|
|
105
|
+
|
|
106
|
+
The JWT must be signed with **HS256** using the identity secret you received when creating the App Key.
|
|
107
|
+
|
|
108
|
+
| Claim | Type | Required | Description |
|
|
109
|
+
|-------|------|----------|-------------|
|
|
110
|
+
| `sub` | `string` | Yes | Unique user identifier in your system |
|
|
111
|
+
| `name` | `string` | No | User's display name |
|
|
112
|
+
| `email` | `string` | No | User's email address |
|
|
113
|
+
| `exp` | `number` | Recommended | Expiration timestamp (Unix seconds) |
|
|
114
|
+
|
|
115
|
+
**Node.js example:**
|
|
116
|
+
|
|
117
|
+
```js
|
|
118
|
+
import jwt from 'jsonwebtoken';
|
|
119
|
+
|
|
120
|
+
const userToken = jwt.sign(
|
|
121
|
+
{
|
|
122
|
+
sub: user.id,
|
|
123
|
+
name: user.name,
|
|
124
|
+
email: user.email,
|
|
125
|
+
},
|
|
126
|
+
process.env.SKIPPR_IDENTITY_SECRET,
|
|
127
|
+
{ algorithm: 'HS256', expiresIn: '1h' },
|
|
128
|
+
);
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
**Step 2: Pass the token to the SDK**
|
|
132
|
+
|
|
133
|
+
**React:**
|
|
134
|
+
|
|
135
|
+
```tsx
|
|
136
|
+
<LiveAgent
|
|
137
|
+
agentId="your_agent_id"
|
|
138
|
+
appKey="pk_live_your_key"
|
|
139
|
+
userToken={userToken}
|
|
140
|
+
/>
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**Script tag:**
|
|
144
|
+
|
|
145
|
+
```js
|
|
146
|
+
Skippr.initialize({
|
|
147
|
+
agentId: 'your_agent_id',
|
|
148
|
+
appKey: 'pk_live_your_key',
|
|
149
|
+
userToken: 'eyJhbGciOiJIUzI1NiIs...',
|
|
150
|
+
});
|
|
151
|
+
```
|
|
28
152
|
|
|
29
153
|
## Custom Components
|
|
30
154
|
|
|
@@ -33,6 +157,7 @@ Any component rendered inside `<LiveAgent>` can use the `useLiveAgent` hook to a
|
|
|
33
157
|
```tsx
|
|
34
158
|
import { LiveAgent, useLiveAgent } from '@skippr/live-agent-sdk';
|
|
35
159
|
|
|
160
|
+
function ConnectionStatus() {
|
|
36
161
|
function ConnectionStatus() {
|
|
37
162
|
const { isConnected } = useLiveAgent();
|
|
38
163
|
|
|
@@ -59,13 +184,14 @@ Self-contained widget component. Renders a floating button that opens a sidebar
|
|
|
59
184
|
|
|
60
185
|
| Prop | Type | Default | Description |
|
|
61
186
|
|------|------|---------|-------------|
|
|
62
|
-
| `agentId` | `string` | *required* | Agent ID
|
|
63
|
-
| `appKey` | `string` |
|
|
64
|
-
| `authToken` | `string` | — | Bearer token for authenticated users |
|
|
187
|
+
| `agentId` | `string` | *required* | Agent ID from the Skippr dashboard |
|
|
188
|
+
| `appKey` | `string` | *required* | Publishable App Key from the Skippr dashboard |
|
|
65
189
|
| `userToken` | `string` | — | Signed JWT for secret mode identity verification |
|
|
190
|
+
| `position` | `'left' \| 'right'` | `'right'` | Side of the screen for the widget |
|
|
191
|
+
| `variant` | `'floating' \| 'sidebar'` | `'floating'` | Widget display mode |
|
|
192
|
+
| `minimizable` | `boolean` | `true` | Whether the widget can be minimized |
|
|
66
193
|
| `defaultOpen` | `boolean` | `false` | Whether the panel starts open |
|
|
67
|
-
|
|
68
|
-
---
|
|
194
|
+
| `welcomeMessage` | `string` | — | Message shown on the minimized bubble |
|
|
69
195
|
|
|
70
196
|
### `useLiveAgent()`
|
|
71
197
|
|
|
@@ -76,8 +202,12 @@ Hook for accessing session state and panel controls. Must be called within `<Liv
|
|
|
76
202
|
| Field | Type | Description |
|
|
77
203
|
|-------|------|-------------|
|
|
78
204
|
| `isConnected` | `boolean` | Whether the agent is connected |
|
|
79
|
-
| `isPanelOpen` | `boolean` | Whether the panel is currently open |
|
|
80
205
|
| `isStarting` | `boolean` | Whether a session is being created |
|
|
206
|
+
| `isPanelOpen` | `boolean` | Whether the panel is currently open |
|
|
207
|
+
| `isMinimized` | `boolean` | Whether the widget is minimized |
|
|
208
|
+
| `isAuthenticated` | `boolean` | Whether the user is authenticated |
|
|
209
|
+
| `variant` | `'floating' \| 'sidebar'` | Current widget display mode |
|
|
210
|
+
| `position` | `'left' \| 'right'` | Current widget position |
|
|
81
211
|
| `error` | `string` | Error message, if any |
|
|
82
212
|
|
|
83
213
|
#### Methods
|
|
@@ -89,22 +219,20 @@ Hook for accessing session state and panel controls. Must be called within `<Liv
|
|
|
89
219
|
| `openPanel` | `() => void` | Open the panel |
|
|
90
220
|
| `closePanel` | `() => void` | Close the panel |
|
|
91
221
|
| `togglePanel` | `() => void` | Toggle the panel open/closed |
|
|
222
|
+
| `expandPanel` | `() => void` | Expand from minimized state |
|
|
223
|
+
| `minimizePanel` | `() => void` | Minimize the widget |
|
|
224
|
+
| `setPosition` | `(position: 'left' \| 'right') => void` | Change widget position |
|
|
225
|
+
|
|
226
|
+
### Global API (Script Tag)
|
|
92
227
|
|
|
93
|
-
|
|
228
|
+
Available on `window.Skippr` when using the script tag bundle.
|
|
94
229
|
|
|
95
230
|
| Method | Description |
|
|
96
231
|
|--------|-------------|
|
|
97
|
-
| `Skippr.initialize(config)` | Mount the widget |
|
|
98
|
-
| `Skippr.logout()` | Clear auth token
|
|
99
|
-
| `Skippr.destroy()` | Remove widget and clear auth tokens |
|
|
100
|
-
|
|
101
|
-
## Authentication Modes
|
|
102
|
-
|
|
103
|
-
The SDK supports two identity modes configured per App Key:
|
|
104
|
-
|
|
105
|
-
**Direct Auth** (default) — Users log in via email OTP inside the widget. No backend integration needed.
|
|
232
|
+
| `Skippr.initialize(config)` | Mount the widget. Accepts `agentId`, `appKey`, `userToken`, `position`, `variant`, `minimizable`. |
|
|
233
|
+
| `Skippr.logout()` | Clear stored auth token and show the login form (direct auth mode) |
|
|
234
|
+
| `Skippr.destroy()` | Remove the widget from the page and clear auth tokens |
|
|
106
235
|
|
|
107
|
-
**Secret** — Your backend signs a JWT with the App Key's identity secret and passes it as `userToken`. The SDK skips the login form and verifies the user server-side.
|
|
108
236
|
|
|
109
237
|
## Support
|
|
110
238
|
|