Status: {status}
{isSpeaking && 'Agent is speaking...'}
Transcript
{transcript.map((line, i) => (
{line}
))}
);
}
```
### JavaScript SDK (`@elevenlabs/client`)
For vanilla JavaScript projects (no React).
**Installation**:
```bash
npm install @elevenlabs/client
```
**Example**:
```javascript
import { Conversation } from '@elevenlabs/client';
const conversation = new Conversation({
agentId: 'your-agent-id',
apiKey: process.env.ELEVENLABS_API_KEY,
onConnect: () => console.log('Connected'),
onDisconnect: () => console.log('Disconnected'),
onEvent: (event) => {
switch (event.type) {
case 'transcript':
document.getElementById('user-text').textContent = event.data.text;
break;
case 'agent_response':
document.getElementById('agent-text').textContent = event.data.text;
break;
}
}
});
// Start conversation
document.getElementById('start-btn').addEventListener('click', async () => {
await conversation.start();
});
// Stop conversation
document.getElementById('stop-btn').addEventListener('click', async () => {
await conversation.stop();
});
```
### Connection Types: WebRTC vs WebSocket
ElevenLabs SDKs support two connection types with different characteristics.
**Comparison Table**:
| Feature | WebSocket | WebRTC |
|---------|-----------|--------|
| **Authentication** | `signedUrl` | `conversationToken` |
| **Audio Format** | Configurable | PCM_48000 (hardcoded) |
| **Sample Rate** | Configurable (16k, 24k, 48k) | 48000 (hardcoded) |
| **Latency** | Standard | Lower |
| **Device Switching** | Flexible | Limited (format locked) |
| **Best For** | General use, flexibility | Low-latency requirements |
**WebSocket Configuration** (default):
```typescript
import { useConversation } from '@elevenlabs/react';
const { startConversation } = useConversation({
agentId: 'your-agent-id',
// WebSocket uses signed URL
signedUrl: async () => {
const response = await fetch('/api/elevenlabs/auth');
const { signedUrl } = await response.json();
return signedUrl;
},
// Connection type (optional, defaults to 'websocket')
connectionType: 'websocket',
// Audio config (flexible)
audioConfig: {
sampleRate: 24000, // 16000, 24000, or 48000
format: 'PCM_24000'
}
});
```
**WebRTC Configuration**:
```typescript
const { startConversation } = useConversation({
agentId: 'your-agent-id',
// WebRTC uses conversation token (different auth flow)
conversationToken: async () => {
const response = await fetch('/api/elevenlabs/token');
const { token } = await response.json();
return token;
},
// Connection type
connectionType: 'webrtc',
// Audio format is HARDCODED to PCM_48000 (not configurable)
// audioConfig ignored for WebRTC
});
```
**Backend Token Endpoints**:
```typescript
// WebSocket signed URL (GET /v1/convai/conversation/get-signed-url)
app.get('/api/elevenlabs/auth', async (req, res) => {
const response = await fetch(
`https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${AGENT_ID}`,
{ headers: { 'xi-api-key': ELEVENLABS_API_KEY } }
);
const { signed_url } = await response.json();
res.json({ signedUrl: signed_url });
});
// WebRTC conversation token (GET /v1/convai/conversation/token)
app.get('/api/elevenlabs/token', async (req, res) => {
const response = await fetch(
`https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=${AGENT_ID}`,
{ headers: { 'xi-api-key': ELEVENLABS_API_KEY } }
);
const { conversation_token } = await response.json();
res.json({ token: conversation_token });
});
```
**When to Use Each**:
| Use WebSocket When | Use WebRTC When |
|--------------------|-----------------|
| Need flexible audio formats | Need lowest possible latency |
| Switching between audio devices frequently | Audio format can be locked to 48kHz |
| Standard latency is acceptable | Building real-time applications |
| Need maximum configuration control | Performance is critical |
**Gotchas**:
- WebRTC hardcodes PCM_48000 - no way to change format
- Device switching in WebRTC limited by fixed format
- Different authentication methods (signedUrl vs conversationToken)
- WebRTC may have better performance but less flexibility
### React Native SDK (Expo)
**Installation**:
```bash
npx expo install @elevenlabs/react-native @livekit/react-native @livekit/react-native-webrtc livekit-client
```
**Requirements**:
- Expo SDK 47+
- iOS 14.0+ / macOS 11.0+
- **Custom dev build required** (Expo Go not supported)
**Example**:
```typescript
import { useConversation } from '@elevenlabs/react-native';
import { View, Button, Text } from 'react-native';
import { z } from 'zod';
export default function App() {
const { startConversation, stopConversation, status } = useConversation({
agentId: 'your-agent-id',
signedUrl: 'https://api.elevenlabs.io/v1/convai/auth/...',
clientTools: {
updateProfile: {
description: "Update user profile",
parameters: z.object({
name: z.string()
}),
handler: async ({ name }) => {
console.log('Updating profile:', name);
return { success: true };
}
}
}
});
return (