0
# Conversational AI
1

2
Build AI-powered conversational agents with voice capabilities, knowledge bases, tool integration, phone numbers, and batch calling.
3

4
## Knowledge Base
5

6
### conversationalAi.addToKnowledgeBase()
7

8
```typescript { .api }
9
addToKnowledgeBase(
10
  request: {
11
    agentId?: string;
12
    name?: string;
13
    url?: string;  // Use url or file, not both
14
    file?: File | Blob;  // Use url or file, not both
15
  },
16
  options?: RequestOptions
17
): Promise<AddKnowledgeBaseResponseModel>
18
```
19

20
### conversationalAi.getDocumentRagIndexes()
21

22
```typescript { .api }
23
getDocumentRagIndexes(
24
  documentationId: string,
25
  options?: RequestOptions
26
): Promise<RagDocumentIndexesResponseModel>
27
```
28

29
### conversationalAi.deleteDocumentRagIndex()
30

31
```typescript { .api }
32
deleteDocumentRagIndex(
33
  documentationId: string,
34
  ragIndexId: string,
35
  options?: RequestOptions
36
): Promise<RagDocumentIndexResponseModel>
37
```
38

39
### conversationalAi.ragIndexOverview()
40

41
```typescript { .api }
42
ragIndexOverview(
43
  options?: RequestOptions
44
): Promise<RagIndexOverviewResponseModel>
45
```
46

47
## Agent Management
48

49
### conversationalAi.agents.create()
50

51
```typescript { .api }
52
agents.create(
53
  request: {
54
    conversationConfig: ConversationConfig;
55
    name?: string;
56
    metadata?: object;
57
    platformSettings?: object;
58
    workflow?: object;
59
  },
60
  options?: RequestOptions
61
): Promise<CreateAgentResponseModel>
62

63
interface ConversationConfig {
64
  agent?: AgentConfig;
65
  tts?: TtsConfig;
66
  asr?: AsrConfig;
67
  vad?: VadConfig;
68
  // Additional configs...
69
}
70

71
interface AgentConfig {
72
  prompt?: {
73
    prompt?: string;
74
    llm?: string;  // e.g., "gpt-4"
75
    temperature?: number;
76
    maxTokens?: number;
77
  };
78
  firstMessage?: string;
79
  language?: string;
80
  // Many more configuration options...
81
}
82
```
83

84
### conversationalAi.agents.get()
85

86
```typescript { .api }
87
agents.get(
88
  agentId: string,
89
  options?: RequestOptions
90
): Promise<GetAgentResponseModel>
91
```
92

93
### conversationalAi.agents.update()
94

95
```typescript { .api }
96
agents.update(
97
  agentId: string,
98
  request: UpdateAgentRequest,
99
  options?: RequestOptions
100
): Promise<GetAgentResponseModel>
101
```
102

103
### conversationalAi.agents.delete()
104

105
```typescript { .api }
106
agents.delete(
107
  agentId: string,
108
  options?: RequestOptions
109
): Promise<void>
110
```
111

112
### conversationalAi.agents.list()
113

114
```typescript { .api }
115
agents.list(
116
  request?: {
117
    pageSize?: number;
118
    search?: string;
119
    archived?: boolean;
120
    sortDirection?: "asc" | "desc";
121
    sortBy?: string;
122
    cursor?: string;
123
  },
124
  options?: RequestOptions
125
): Promise<GetAgentsPageResponseModel>
126
```
127

128
### conversationalAi.agents.duplicate()
129

130
```typescript { .api }
131
agents.duplicate(
132
  agentId: string,
133
  request?: { name?: string },
134
  options?: RequestOptions
135
): Promise<CreateAgentResponseModel>
136
```
137

138
## Agent Testing
139

140
### conversationalAi.agents.simulateConversation()
141

142
```typescript { .api }
143
agents.simulateConversation(
144
  agentId: string,
145
  request: {
146
    simulationSpecification: {
147
      simulatedUserConfig: {
148
        firstMessage: string;
149
        language: string;
150
        disableFirstMessageInterruptions?: boolean;
151
      };
152
    };
153
  },
154
  options?: RequestOptions
155
): Promise<AgentSimulatedChatTestResponseModel>
156
```
157

158
### conversationalAi.agents.simulateConversationStream()
159

160
```typescript { .api }
161
agents.simulateConversationStream(
162
  agentId: string,
163
  request: SimulationRequest,
164
  options?: RequestOptions
165
): Promise<ReadableStream<SimulationChunk>>
166
```
167

168
## Conversations
169

170
### conversationalAi.conversations.list()
171

172
```typescript { .api }
173
conversations.list(
174
  request?: {
175
    agentId?: string;
176
    pageSize?: number;
177
    cursor?: string;
178
  },
179
  options?: RequestOptions
180
): Promise<GetConversationsPageResponseModel>
181
```
182

183
### conversationalAi.conversations.get()
184

185
```typescript { .api }
186
conversations.get(
187
  conversationId: string,
188
  options?: RequestOptions
189
): Promise<GetConversationResponseModel>
190
```
191

192
### conversationalAi.conversations.delete()
193

194
```typescript { .api }
195
conversations.delete(
196
  conversationId: string,
197
  options?: RequestOptions
198
): Promise<void>
199
```
200

201
### conversationalAi.conversations.getAudio()
202

203
```typescript { .api }
204
conversations.getAudio(
205
  conversationId: string,
206
  options?: RequestOptions
207
): Promise<ReadableStream<Uint8Array>>
208
```
209

210
## Phone Numbers
211

212
### conversationalAi.phoneNumbers.list()
213

214
```typescript { .api }
215
phoneNumbers.list(
216
  request?: { includeNumbers?: boolean },
217
  options?: RequestOptions
218
): Promise<GetPhoneNumbersPageResponseModel>
219
```
220

221
### conversationalAi.phoneNumbers.create()
222

223
```typescript { .api }
224
phoneNumbers.create(
225
  request: {
226
    agentId: string;
227
    phoneNumber?: string;
228
    areaCode?: string;
229
  },
230
  options?: RequestOptions
231
): Promise<PhoneNumberResponseModel>
232
```
233

234
### conversationalAi.phoneNumbers.update()
235

236
```typescript { .api }
237
phoneNumbers.update(
238
  phoneNumberId: string,
239
  request: { agentId: string },
240
  options?: RequestOptions
241
): Promise<PhoneNumberResponseModel>
242
```
243

244
### conversationalAi.phoneNumbers.delete()
245

246
```typescript { .api }
247
phoneNumbers.delete(
248
  phoneNumberId: string,
249
  options?: RequestOptions
250
): Promise<void>
251
```
252

253
## Batch Calls
254

255
### conversationalAi.batchCalls.create()
256

257
```typescript { .api }
258
batchCalls.create(
259
  request: {
260
    agentId: string;
261
    phoneNumbers: string[];
262
    startTime?: number;  // Unix timestamp
263
    // Additional options...
264
  },
265
  options?: RequestOptions
266
): Promise<CreateBatchCallResponseModel>
267
```
268

269
### conversationalAi.batchCalls.list()
270

271
```typescript { .api }
272
batchCalls.list(
273
  request?: { agentId?: string },
274
  options?: RequestOptions
275
): Promise<GetBatchCallsPageResponseModel>
276
```
277

278
### conversationalAi.batchCalls.get()
279

280
```typescript { .api }
281
batchCalls.get(
282
  batchId: string,
283
  options?: RequestOptions
284
): Promise<GetBatchCallResponseModel>
285
```
286

287
## Usage Examples
288

289
### Create Agent
290

291
```typescript
292
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
293

294
const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY });
295

296
const agent = await client.conversationalAi.agents.create({
297
  conversationConfig: {
298
    agent: {
299
      prompt: {
300
        prompt: "You are a helpful customer service agent for an e-commerce company.",
301
        llm: "gpt-4",
302
        temperature: 0.7,
303
        maxTokens: 500
304
      },
305
      firstMessage: "Hello! How can I help you today?",
306
      language: "en"
307
    },
308
    tts: {
309
      voiceId: "21m00Tcm4TlvDq8ikWAM",
310
      model: "eleven_turbo_v2_5"
311
    }
312
  },
313
  name: "Customer Service Agent"
314
});
315

316
console.log(`Agent created: ${agent.agentId}`);
317
```
318

319
### Add Knowledge Base
320

321
```typescript
322
import fs from "fs";
323

324
// From URL
325
await client.conversationalAi.addToKnowledgeBase({
326
  agentId: "agent_id",
327
  name: "Product Documentation",
328
  url: "https://example.com/docs"
329
});
330

331
// From file
332
const docFile = fs.readFileSync("product_manual.pdf");
333
await client.conversationalAi.addToKnowledgeBase({
334
  agentId: "agent_id",
335
  name: "Product Manual",
336
  file: docFile
337
});
338

339
// Update agent to use knowledge base
340
await client.conversationalAi.agents.update("agent_id", {
341
  conversationConfig: {
342
    agent: {
343
      // Include knowledge base ID in agent config
344
    }
345
  }
346
});
347
```
348

349
### Simulate Conversation
350

351
```typescript
352
const simulation = await client.conversationalAi.agents.simulateConversation(
353
  "agent_id",
354
  {
355
    simulationSpecification: {
356
      simulatedUserConfig: {
357
        firstMessage: "I need help with my order",
358
        language: "en",
359
        disableFirstMessageInterruptions: false
360
      }
361
    }
362
  }
363
);
364

365
console.log("Simulation results:", simulation);
366
```
367

368
### List and Manage Conversations
369

370
```typescript
371
// List conversations
372
const conversations = await client.conversationalAi.conversations.list({
373
  agentId: "agent_id",
374
  pageSize: 20
375
});
376

377
// Get specific conversation
378
const conv = await client.conversationalAi.conversations.get(
379
  conversations.conversations[0].conversationId
380
);
381

382
// Download conversation audio
383
const audio = await client.conversationalAi.conversations.getAudio(conv.conversationId);
384
const output = fs.createWriteStream("conversation.mp3");
385
for await (const chunk of audio) {
386
  output.write(chunk);
387
}
388
output.end();
389

390
// Delete conversation
391
await client.conversationalAi.conversations.delete(conv.conversationId);
392
```
393

394
### Provision Phone Number
395

396
```typescript
397
// Create phone number for agent
398
const phone = await client.conversationalAi.phoneNumbers.create({
399
  agentId: "agent_id",
400
  areaCode: "415"  // San Francisco area code
401
});
402

403
console.log(`Phone number: ${phone.phoneNumber}`);
404

405
// Update phone number to different agent
406
await client.conversationalAi.phoneNumbers.update(phone.phoneNumberId, {
407
  agentId: "different_agent_id"
408
});
409

410
// List all phone numbers
411
const numbers = await client.conversationalAi.phoneNumbers.list({
412
  includeNumbers: true
413
});
414

415
// Delete phone number
416
await client.conversationalAi.phoneNumbers.delete(phone.phoneNumberId);
417
```
418

419
### Batch Calling
420

421
```typescript
422
// Create batch call campaign
423
const batch = await client.conversationalAi.batchCalls.create({
424
  agentId: "agent_id",
425
  phoneNumbers: [
426
    "+14155551234",
427
    "+14155555678",
428
    "+14155559012"
429
  ],
430
  startTime: Math.floor(Date.now() / 1000) + 3600  // Start in 1 hour
431
});
432

433
console.log(`Batch call created: ${batch.batchId}`);
434

435
// List batch calls
436
const batches = await client.conversationalAi.batchCalls.list({
437
  agentId: "agent_id"
438
});
439

440
// Get batch status
441
const batchStatus = await client.conversationalAi.batchCalls.get(batch.batchId);
442
console.log(`Status: ${batchStatus.status}`);
443
```
444

445
### Agent Lifecycle
446

447
```typescript
448
// Create agent
449
const agent = await client.conversationalAi.agents.create({
450
  conversationConfig: { /* ... */ },
451
  name: "Support Agent"
452
});
453

454
// Update agent
455
await client.conversationalAi.agents.update(agent.agentId, {
456
  name: "Updated Support Agent",
457
  conversationConfig: {
458
    agent: {
459
      temperature: 0.8
460
    }
461
  }
462
});
463

464
// Duplicate agent
465
const duplicate = await client.conversationalAi.agents.duplicate(agent.agentId, {
466
  name: "Support Agent (Copy)"
467
});
468

469
// List agents
470
const agents = await client.conversationalAi.agents.list({
471
  pageSize: 10,
472
  search: "support",
473
  sortBy: "name"
474
});
475

476
// Delete agent
477
await client.conversationalAi.agents.delete(agent.agentId);
478
```
479

480
## Important Notes
481

482
- **Agent Config**: Complex configuration with many options
483
  - LLM settings (model, temperature, max tokens)
484
  - TTS settings (voice, model)
485
  - ASR settings (automatic speech recognition)
486
  - VAD settings (voice activity detection)
487
  - Knowledge base integration
488
  - Tool/API integrations
489
- **Knowledge Base**: Upload documents or URLs for RAG
490
  - After adding documents, update agent config
491
  - Supports PDFs, text files, web pages
492
- **Conversations**: Track and manage agent interactions
493
  - List by agent
494
  - Download audio recordings
495
  - Delete for privacy compliance
496
- **Phone Numbers**: Voice-enabled agents
497
  - Provision numbers with area codes
498
  - Assign to agents
499
  - Update assignments
500
- **Batch Calls**: Campaign calling to multiple numbers
501
  - Schedule start time
502
  - Track status and results
503
- **Simulation**: Test agents before deployment
504
  - Streaming and non-streaming modes
505
  - Simulated user interactions
506
- **Additional Sub-Resources**: Tools, tests, secrets, settings, Twilio, SIP trunk, MCP servers, dashboard, LLM usage
507