### Install Dependencies and Build SDK

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/CONTRIBUTING.md

Run these commands to install project dependencies and build the SDK output files.

```sh
$ yarn
$ yarn build
```

--------------------------------

### Add and Run an Example

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/CONTRIBUTING.md

Add new examples to the `examples/` directory and make them executable. Run examples against your API using `yarn tsn`.

```ts
// add an example to examples/<your-example>.ts

#!/usr/bin/env -S npm run tsn -T
…
```

```sh
$ chmod +x examples/<your-example>.ts
# run the example against your api
$ yarn tsn -T examples/<your-example>.ts
```

--------------------------------

### Install SDK from Git

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/CONTRIBUTING.md

Install the Retell TypeScript SDK directly from its GitHub repository using npm.

```sh
$ npm install git+ssh://git@github.com:RetellAI/retell-typescript-sdk.git
```

--------------------------------

### Install Retell SDK

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/README.md

Install the Retell SDK using npm. This is the first step to integrate the library into your project.

```sh
npm install retell-sdk
```

--------------------------------

### Add Sources to Knowledge Base Example

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/knowledge-base.md

Example demonstrating how to add URLs, text, and documents to a knowledge base using the Retell SDK. Requires importing `toFile` and `fs`.

```typescript
import { toFile } from 'retell-sdk';
import fs from 'fs';

const pdfBuffer = fs.readFileSync('guide.pdf');
const updated = await client.knowledgeBase.addSources('kb_abc123', {
  urls: ['https://example.com/docs'],
  texts: ['Company holiday schedule: ...'],
  documents: [
    await toFile(pdfBuffer, 'guide.pdf', { type: 'application/pdf' }),
  ],
});
```

--------------------------------

### Quick Start: Initialize Client, Create Agent, and Start Call

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/README.md

Initialize the Retell client with an API key, create a new AI agent with a specified LLM and voice, and then initiate a phone call between two numbers using the created agent.

```typescript
import Retell from 'retell-sdk';

// Initialize the client
const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'],
});

// Create an agent
const agent = await client.agent.create({
  response_engine: {
    llm_id: 'llm_abc123',
    type: 'retell-llm',
  },
  voice_id: 'retell-Cimo',
});

// Create a phone call
const call = await client.call.createPhoneCall({
  from_number: '+14157774444',
  to_number: '+12137774445',
  agent_id: agent.agent_id,
});
```

--------------------------------

### Initialize Retell Client with Full Configuration

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/configuration.md

Example demonstrating full client configuration including API key, base URL, timeouts, retry settings, log level, custom logger, and fetch options. Replace 'your-api-key' with your actual key.

```typescript
const client = new Retell({
  apiKey: 'your-api-key',
  baseURL: 'https://api.retellai.com',
  timeout: 30000,
  maxRetries: 3,
  logLevel: 'debug',
  logger: customLogger,
  fetchOptions: {
    // Custom fetch options
  },
});
```

--------------------------------

### MCP Server Configuration JSON

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/packages/mcp-server/README.md

Example configuration for clients that use a JSON file to set up the MCP server. This includes command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "retell_sdk_api": {
      "command": "npx",
      "args": ["-y", "@retell-ai/mcp-server"],
      "env": {
        "RETELL_API_KEY": "YOUR_RETELL_API_KEY"
      }
    }
  }
}
```

--------------------------------

### Initialize Retell Client with API Key

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/configuration.md

Basic setup for initializing the Retell client using an API key from environment variables. Ensure the RETELL_API_KEY environment variable is set.

```typescript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'],
});
```

--------------------------------

### retrieve

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/knowledge-base.md

Get details of a specific knowledge base.

```APIDOC
## GET /knowledge_base/{knowledgeBaseID}

### Description
Get details of a specific knowledge base.

### Method
GET

### Endpoint
/knowledge_base/{knowledgeBaseID}

### Parameters
#### Path Parameters
- **knowledgeBaseID** (string) - Required - The knowledge base ID to retrieve

### Response
#### Success Response (200)
- **knowledge_base_id** (string) - The ID of the knowledge base.
- **knowledge_base_name** (string) - The name of the knowledge base.
- **created_at** (string) - Timestamp of creation.
- **updated_at** (string) - Timestamp of last update.
- **status** (string) - Status of the knowledge base.
- **source_count** (integer) - Number of sources in the knowledge base.
- **retrieval_model** (object) - Retrieval model configuration.
- **vector_index_type** (string) - Type of vector index.
- **options** (object) - Additional options.

#### Response Example
```json
{
  "knowledge_base_id": "kb_abc123",
  "knowledge_base_name": "Product Documentation",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z",
  "status": "ready",
  "source_count": 1,
  "retrieval_model": {
    "type": "retrieval"
  },
  "vector_index_type": "hnsw",
  "options": {}
}
```
```

--------------------------------

### Install MCP Server with Claude Code

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/packages/mcp-server/README.md

Command to add the MCP server for Claude Code. Requires setting environment variables in your home directory's .claude.json file.

```bash
claude mcp add retell_ai_mcp_server_api --env RETELL_API_KEY="YOUR_RETELL_API_KEY" -- npx -y @retell-ai/mcp-server
```

--------------------------------

### Remote MCP Server Configuration JSON

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/packages/mcp-server/README.md

Example configuration for a remotely hosted MCP server. It specifies the URL, authorization headers, and security scheme.

```json
{
  "mcpServers": {
    "retell_sdk_api": {
      "url": "http://localhost:3000",
      "headers": {
        "Authorization": "Bearer <auth value>"
      }
    }
  }
}
```

--------------------------------

### Configure Node.js Proxy with Undici

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/README.md

For Node.js environments, configure proxy behavior by providing a `fetchOptions` object with an `undici.ProxyAgent`. This example uses a local proxy server.

```typescript
import Retell from 'retell-sdk';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new Retell({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});
```

--------------------------------

### Handle API Errors

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/INDEX.md

This example demonstrates how to handle different types of errors that may occur during API interactions, such as invalid input or general API errors. Refer to errors.md for comprehensive error handling guidance.

```typescript
// See errors.md for complete error handling
try {
  await client.agent.create(...);
} catch (err) {
  if (err instanceof Retell.BadRequestError) {
    // Handle invalid input
  } else if (err instanceof Retell.APIError) {
    // Handle API error
    console.log(err.status, err.message);
  }
}
```

--------------------------------

### retrieve

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/chat-agent.md

Get details of a specific chat agent.

```APIDOC
## retrieve

### Description
Get details of a specific chat agent.

### Method
GET

### Endpoint
/v1/chat_agents/{agent_id}

### Parameters
#### Path Parameters
- **agentID** (`string`) - Required - The agent ID to retrieve

#### Query Parameters
- **query** (`ChatAgentRetrieveParams`) - Optional - Query parameters

#### Request Body
None

### Response
#### Success Response (200)
- **agent_id** (string) - The agent ID
- **agent_name** (string) - The name of the agent

#### Response Example
```json
{
  "agent_id": "agent_abc123",
  "agent_name": "Chat Support Bot"
}
```
```

--------------------------------

### retrieve

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/llm.md

Get details of a specific Retell LLM.

```APIDOC
## retrieve

### Description
Get details of a specific Retell LLM.

### Method
GET

### Endpoint
/llm/{llm_id}

### Parameters
#### Path Parameters
- **llmID** (string) - Required - The LLM ID to retrieve

#### Query Parameters
- **query** (object) - Optional - Query parameters for retrieval.

### Response
#### Success Response (200)
- **llm_id** (string) - The ID of the LLM.
- **general_prompt** (string) - The general prompt for the LLM.
- **general_tools** (array) - A list of tools the LLM can use.

### Response Example
```json
{
  "llm_id": "llm_abc123",
  "general_prompt": "You are a helpful customer service assistant.",
  "general_tools": [
    {
      "name": "check_balance",
      "description": "Check the customer balance",
      "type": "function"
    }
  ]
}
```
```

--------------------------------

### Create Agent and Make a Call

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/README.md

This pattern demonstrates the process of creating an LLM, then an agent configured with that LLM, and finally initiating a phone call using the created agent. Ensure you have the necessary LLM and voice configurations before proceeding.

```typescript
// Create an LLM
const llm = await client.llm.create({
  general_prompt: 'You are a helpful assistant.',
  begin_message: 'Hello, how can I help?',
});

// Create an agent
const agent = await client.agent.create({
  response_engine: {
    type: 'retell-llm',
    llm_id: llm.llm_id,
  },
  voice_id: 'retell-Cimo',
  agent_name: 'My Assistant',
});

// Create a phone call
const call = await client.call.createPhoneCall({
  from_number: '+14157774444',
  to_number: '+12137774445',
  agent_id: agent.agent_id,
});

console.log('Call ID:', call.call_id);
```

--------------------------------

### Build a Knowledge Base

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/README.md

This pattern illustrates how to create a knowledge base and add sources to it, either via URLs or direct text content. This allows your agents to access and utilize this information.

```typescript
// Create knowledge base
const kb = await client.knowledgeBase.create({
  knowledge_base_name: 'Support Documentation',
});

// Add sources
await client.knowledgeBase.addSources(kb.knowledge_base_id, {
  urls: [
    'https://docs.example.com',
    'https://help.example.com',
  ],
  texts: [
    'Company hours: 9am-5pm EST',
    'Refund policy: 30 days with receipt',
  ],
});
```

--------------------------------

### withOptions

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/client.md

Creates a new client instance with modified options, reusing the current client's settings. This is useful for creating specialized clients without re-initializing the base client.

```APIDOC
## withOptions

Create a new client instance with modified options, reusing the current client's settings.

### Method Signature

```typescript
withOptions(options: Partial<ClientOptions>): Retell
```

### Parameters

#### Request Body

- **options** (`Partial<ClientOptions>`) - Required - Options to override in the new client instance

### Returns

A new `Retell` instance with merged options

### Example

```typescript
const client = new Retell();
const customClient = client.withOptions({
  timeout: 30000,
  logLevel: 'debug',
});
```
```

--------------------------------

### retrieve

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/conversation-flow.md

Get details of a specific conversation flow using its ID.

```APIDOC
## retrieve ConversationFlow

### Description
Get details of a specific conversation flow.

### Method
GET

### Endpoint
/v1/conversation-flows/{conversationFlowID}

### Parameters
#### Path Parameters
- **conversationFlowID** (string) - Required - The conversation flow ID to retrieve.

#### Query Parameters
- **version** (string) - Optional - Specifies the version of the conversation flow to retrieve.

### Response
#### Success Response (200)
- **conversation_flow_id** (string) - The unique identifier for the conversation flow.
- **conversation_flow_name** (string) - The name of the conversation flow.
- **description** (string) - The description of the conversation flow.
- **nodes** (array) - The nodes defining the conversation flow.
- **agent_id** (string) - The ID of the associated agent.
- **created_at** (string) - The timestamp when the flow was created.
- **updated_at** (string) - The timestamp when the flow was last updated.

#### Response Example
```json
{
  "conversation_flow_id": "flow_abc123",
  "conversation_flow_name": "Customer Support Flow",
  "description": "Flow for handling customer support inquiries.",
  "nodes": [
    {
      "node_id": "start",
      "type": "start",
      "next_node_id": "welcome_message"
    }
  ],
  "agent_id": "agent_xyz789",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### client.voice.list

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/api.md

Lists all available voices. This method corresponds to a GET request to the /list-voices endpoint.

```APIDOC
## GET /list-voices

### Description
Lists all available voices.

### Method
GET

### Endpoint
/list-voices

### Response
#### Success Response (200)
- **VoiceListResponse** (object) - The response object containing a list of voices.
```

--------------------------------

### Create Modified Client with New Options

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/configuration.md

Use the `withOptions()` method to create a new client instance with updated configuration, such as a different logLevel. The original client remains unchanged.

```typescript
const client = new Retell({
  logLevel: 'info',
});

// Create a debug client
const debugClient = client.withOptions({
  logLevel: 'debug',
});

// Original client is unchanged
console.log(client.logLevel); // 'info'
console.log(debugClient.logLevel); // 'debug'
```

--------------------------------

### client.chat.retrieve

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/api.md

Retrieves a specific chat by its ID. Use this to get details about a chat session.

```APIDOC
## GET /get-chat/{chat_id}

### Description
Retrieves a specific chat by its ID.

### Method
GET

### Endpoint
/get-chat/{chat_id}

### Parameters
#### Path Parameters
- **chat_id** (string) - Required - The ID of the chat to retrieve.
```

--------------------------------

### client.concurrency.retrieve

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/api.md

Retrieves the current concurrency limits. This method corresponds to a GET request to the /get-concurrency endpoint.

```APIDOC
## GET /get-concurrency

### Description
Retrieves the current concurrency limits.

### Method
GET

### Endpoint
/get-concurrency

### Response
#### Success Response (200)
- **ConcurrencyRetrieveResponse** (object) - The response object containing concurrency information.
```

--------------------------------

### Initialize Retell Client

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/client.md

Demonstrates how to initialize the Retell client with basic and custom configurations. Ensure your API key is provided either directly or via the RETELL_API_KEY environment variable.

```typescript
import Retell from 'retell-sdk';

// Basic initialization
const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'],
});

// With custom configuration
const client = new Retell({
  apiKey: 'your-api-key',
  baseURL: 'https://api.example.com',
  timeout: 30000,
  maxRetries: 3,
  logLevel: 'debug',
});
```

--------------------------------

### client.call.retrieve

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/api.md

Retrieves a specific call by its ID. Use this to get details about a past or ongoing call.

```APIDOC
## GET /v2/get-call/{call_id}

### Description
Retrieves a specific call by its ID.

### Method
GET

### Endpoint
/v2/get-call/{call_id}

### Parameters
#### Path Parameters
- **call_id** (string) - Required - The ID of the call to retrieve.
```

--------------------------------

### retrieve

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/chat.md

Get details of a specific chat. This method retrieves information about a particular chat session.

```APIDOC
## retrieve

### Description
Get details of a specific chat.

### Method
GET

### Endpoint
/v1/chat/{chatID}

### Parameters
#### Path Parameters
- **chatID** (string) - Required - The chat ID to retrieve.

### Response
#### Success Response (200)
- **chat_id** (string) - The unique identifier for the chat.
- **agent_id** (string) - The ID of the agent associated with the chat.
- **user_name** (string) - The name of the user.
- **created_at** (string) - Timestamp when the chat was created.
- **chat_status** (string) - The current status of the chat (e.g., 'ongoing', 'ended').
- **metadata** (object) - Custom key-value pairs associated with the chat.

### Response Example
```json
{
  "chat_id": "chat_abc123",
  "agent_id": "agent_abc123",
  "user_name": "John Doe",
  "created_at": "2023-10-27T10:00:00Z",
  "chat_status": "ongoing",
  "metadata": {
    "customer_id": "cust_123"
  }
}
```
```

--------------------------------

### Configure Proxy for Deno

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/configuration.md

Create a Deno HttpClient with proxy settings and pass it to the Retell constructor via fetchOptions.

```typescript
import Retell from 'npm:retell-sdk';

const httpClient = Deno.createHttpClient({
  proxy: { url: 'http://localhost:8888' },
});

const client = new Retell({
  fetchOptions: {
    client: httpClient,
  },
});
```

--------------------------------

### client.exportRequest.list

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/api.md

Lists all export requests with optional filtering. This method corresponds to a GET request to the /v2/list-export-requests endpoint.

```APIDOC
## GET /v2/list-export-requests

### Description
Lists all export requests with optional filtering.

### Method
GET

### Endpoint
/v2/list-export-requests

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering export requests.

### Response
#### Success Response (200)
- **ExportRequestListResponse** (object) - The response object containing a list of export requests.
```

--------------------------------

### create

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/knowledge-base.md

Create a new knowledge base.

```APIDOC
## POST /knowledge_base

### Description
Create a new knowledge base.

### Method
POST

### Endpoint
/knowledge_base

### Parameters
#### Request Body
- **knowledge_base_name** (string) - Required - Name of the knowledge base.
- **retrieval_model** (object) - Optional - Retrieval model configuration.
  - **type** (string) - Required - Type of retrieval model.
  - **embedding_model** (string) - Optional - Embedding model to use.
- **vector_index_type** (string) - Optional - Type of vector index.
- **options** (object) - Optional - Additional options.
  - **use_dynamic_chunking** (boolean) - Optional - Whether to use dynamic chunking.
  - **min_chunk_size** (integer) - Optional - Minimum chunk size.
  - **max_chunk_size** (integer) - Optional - Maximum chunk size.
  - **chunk_overlap** (integer) - Optional - Chunk overlap.

### Request Example
```json
{
  "knowledge_base_name": "Product Documentation",
  "retrieval_model": {
    "type": "retrieval"
  },
  "vector_index_type": "hnsw"
}
```

### Response
#### Success Response (200)
- **knowledge_base_id** (string) - The ID of the created knowledge base.
- **knowledge_base_name** (string) - The name of the knowledge base.
- **created_at** (string) - Timestamp of creation.
- **updated_at** (string) - Timestamp of last update.
- **status** (string) - Status of the knowledge base.
- **source_count** (integer) - Number of sources in the knowledge base.
- **retrieval_model** (object) - Retrieval model configuration.
- **vector_index_type** (string) - Type of vector index.
- **options** (object) - Additional options.

#### Response Example
```json
{
  "knowledge_base_id": "kb_abc123",
  "knowledge_base_name": "Product Documentation",
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z",
  "status": "ready",
  "source_count": 0,
  "retrieval_model": {
    "type": "retrieval"
  },
  "vector_index_type": "hnsw",
  "options": {}
}
```
```

--------------------------------

### Initialize Client with Custom Base URL

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/configuration.md

Pass the RETELL_BASE_URL from the environment to the baseURL option in the Retell constructor.

```typescript
const client = new Retell({
  baseURL: process.env.RETELL_BASE_URL,
});
```

--------------------------------

### client.voice.retrieve

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/api.md

Retrieves a specific voice by its ID. This method corresponds to a GET request to the /get-voice/{voice_id} endpoint.

```APIDOC
## GET /get-voice/{voice_id}

### Description
Retrieves a specific voice by its ID.

### Method
GET

### Endpoint
/get-voice/{voice_id}

### Parameters
#### Path Parameters
- **voiceID** (string) - Required - The ID of the voice to retrieve.

### Response
#### Success Response (200)
- **VoiceResponse** (object) - The response object for a voice operation.
```

--------------------------------

### Configure Deno Proxy

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/README.md

For Deno runtime, create a custom `HttpClient` using `Deno.createHttpClient` with proxy settings and pass it to the Retell client via `fetchOptions.client`.

```typescript
import Retell from 'npm:retell-sdk';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new Retell({
  fetchOptions: {
    client: httpClient,
  },
});
```

--------------------------------

### Retrieve a Conversation Flow

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/conversation-flow.md

Get details of a specific conversation flow by its ID. Optionally, query parameters can be provided.

```typescript
const flow = await client.conversationFlow.retrieve('flow_abc123');
console.log(flow.conversation_flow_name);
```

--------------------------------

### Create and Populate Customer Support Knowledge Base

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/knowledge-base.md

Create a new knowledge base and add URLs and text snippets as sources. This is useful for providing customer support with frequently asked questions and policy information.

```typescript
// Create knowledge base
const kb = await client.knowledgeBase.create({
  knowledge_base_name: 'Customer Support FAQ',
  description: 'Frequently asked questions and support docs',
});

// Add various sources
await client.knowledgeBase.addSources(kb.knowledge_base_id, {
  urls: [
    'https://help.example.com/faq',
    'https://help.example.com/contact',
  ],
  texts: [
    'Shipping policy: We offer free shipping on orders over $50',
    'Returns: 30-day return policy with original receipt',
  ],
});

// Create agent that uses knowledge base
const agent = await client.agent.create({
  agent_name: 'Support Agent',
  response_engine: {
    type: 'retell-llm',
    llm_id: 'llm_abc123',
  },
  voice_id: 'retell-Cimo',
  // Agent can reference knowledge base in LLM system prompt
});
```

--------------------------------

### Update a Conversation Flow

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/conversation-flow.md

Update an existing conversation flow by providing its ID and the fields to modify. The name is updated in this example.

```typescript
const updated = await client.conversationFlow.update('flow_abc123', {
  conversation_flow_name: 'Updated Support Flow',
});
```

--------------------------------

### Initialize Retell Client with Options

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/README.md

Instantiate the Retell client with various configuration options including API key, base URL, timeouts, retries, log level, and a custom logger.

```typescript
const client = new Retell({
  apiKey: 'your-key',
  baseURL: 'https://api.retellai.com',
  timeout: 60000,
  maxRetries: 2,
  logLevel: 'warn',
  logger: console,
});
```

--------------------------------

### Retrieve Voice Details

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/voice.md

Get specific details for a given voice ID. This returns the voice's name and provider.

```typescript
const voice = await client.voice.retrieve('retell-Cimo');
console.log(voice.voice_name);
console.log(voice.provider);
```

--------------------------------

### List All Available Voices

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/voice.md

Retrieve a list of all voices accessible to the user. The result is an array of voice objects, which can be filtered, for example, by gender.

```typescript
const voices = await client.voice.list();
console.log(voices); // Array of voice objects

// Filter by gender
const maleVoices = voices.filter(v => v.gender === 'male');
```

--------------------------------

### Create an Agent with Retell SDK

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/README.md

Initialize the Retell client and create a new agent. Ensure your RETELL_API_KEY is set as an environment variable. The agent is configured with a response engine and a voice ID.

```js
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const agentResponse = await client.agent.create({
  response_engine: { llm_id: 'llm_234sdertfsdsfsdf', type: 'retell-llm' },
  voice_id: 'retell-Cimo',
});

console.log(agentResponse.agent_id);
```

--------------------------------

### Get Agent Versions

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/agent.md

Retrieve all versions associated with a given agent ID. The response contains an array of agent version objects.

```typescript
const versions = await client.agent.getVersions('agent_abc123');
versions.forEach(v => {
  console.log(`Version ${v.version}: ${v.agent_name}`);
});
```

--------------------------------

### Link Local SDK Repository with pnpm

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/CONTRIBUTING.md

Clone the repository and use `pnpm link` to link a local copy of the SDK into your project. This is useful for development.

```sh
# With pnpm
$ pnpm link --global
$ cd ../my-package
$ pnpm link --global retell-sdk
```

--------------------------------

### Create Knowledge Base

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/knowledge-base.md

Creates a new knowledge base with a specified name and optional description.

```APIDOC
## POST /v1/knowledge-bases

### Description
Creates a new knowledge base.

### Method
POST

### Endpoint
/v1/knowledge-bases

### Parameters
#### Request Body
- **knowledge_base_name** (string) - Required - Name of the knowledge base
- **description** (string) - Optional - Optional description

### Response
#### Success Response (200)
- **knowledge_base_id** (string) - Unique knowledge base identifier
- **knowledge_base_name** (string) - Display name of the knowledge base
- **description** (string) - Optional description
- **sources** (KnowledgeBaseSource[]) - Sources in the knowledge base

### Response Example
```json
{
  "knowledge_base_id": "kb_abc123",
  "knowledge_base_name": "My Company Docs",
  "description": "Internal company documentation",
  "sources": []
}
```
```

--------------------------------

### Send Message and Get Response - TypeScript

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/chat.md

Sends a message to a chat session and receives the agent's response. Use this for interactive chat completions.

```typescript
const response = await client.chat.createChatCompletion({
  chat_id: 'chat_abc123',
  content: 'What are your business hours?',
});

console.log(response.messages); // Array of response messages
```

--------------------------------

### Create Knowledge Base

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/knowledge-base.md

Creates a new knowledge base with a name and an optional description.

```APIDOC
## POST /v1/knowledge-bases

### Description
Creates a new knowledge base.

### Method
POST

### Endpoint
/v1/knowledge-bases

### Parameters
#### Request Body
- **knowledge_base_name** (string) - Required - The name of the knowledge base.
- **description** (string) - Optional - A description for the knowledge base.
```

--------------------------------

### create

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/agent.md

Creates a new AI agent with the specified configuration, including response engines, voice settings, and agent name. It returns the newly created agent object.

```APIDOC
## create

### Description
Create a new agent with specified configuration.

### Method
POST

### Endpoint
/v1/accounts/{accountId}/agents

### Parameters
#### Request Body
- **response_engine** (object) - Required - Agent's response engine configuration.
- **voice_id** (string) - Required - The ID of the voice to be used by the agent.
- **agent_name** (string) - Required - The name of the agent.
- **language** (string) - Required - The language of the agent (e.g., 'en-US').

### Request Example
```json
{
  "response_engine": {
    "llm_id": "llm_234sdertfsdsfsdf",
    "type": "retell-llm"
  },
  "voice_id": "retell-Cimo",
  "agent_name": "Customer Service Bot",
  "language": "en-US"
}
```

### Response
#### Success Response (200)
- **agent_id** (string) - The unique identifier for the created agent.
- **agent_name** (string) - The name of the agent.
- **voice_id** (string) - The voice ID used by the agent.
- **language** (string) - The language of the agent.
- **response_engine** (object) - The response engine configuration.

#### Response Example
```json
{
  "agent_id": "agent_abc123",
  "agent_name": "Customer Service Bot",
  "voice_id": "retell-Cimo",
  "language": "en-US",
  "response_engine": {
    "llm_id": "llm_234sdertfsdsfsdf",
    "type": "retell-llm"
  }
}
```
```

--------------------------------

### Initialize Retell Client with API Key

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/configuration.md

Initialize the Retell client with your API key for authentication. This is required unless the RETELL_API_KEY environment variable is set.

```typescript
const client = new Retell({
  apiKey: 'retell_abc123def456',
});
```

--------------------------------

### Get All Chat Agent Versions

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/chat-agent.md

Retrieve all versions associated with a given chat agent ID. The response includes details for each version, such as version number and agent name.

```typescript
const versions = await client.chatAgent.getVersions('agent_abc123');
versions.forEach(v => {
  console.log(`Version ${v.version}: ${v.agent_name}`);
});
```

--------------------------------

### Create and Populate Document-Based Knowledge Base

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/knowledge-base.md

Create a knowledge base and add PDF documents as sources. This is ideal for making technical manuals or API documentation searchable.

```typescript
import fs from 'fs';
import { toFile } from 'retell-sdk';

// Create knowledge base for documents
const kb = await client.knowledgeBase.create({
  knowledge_base_name: 'Product Manual',
});

// Add PDF documentation
const manualPdf = fs.readFileSync('product-manual.pdf');
const apiDocPdf = fs.readFileSync('api-docs.pdf');

await client.knowledgeBase.addSources(kb.knowledge_base_id, {
  documents: [
    await toFile(manualPdf, 'product-manual.pdf', {
      type: 'application/pdf',
    }),
    await toFile(apiDocPdf, 'api-docs.pdf', {
      type: 'application/pdf',
    }),
  ],
});
```

--------------------------------

### list

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/knowledge-base.md

List all knowledge bases.

```APIDOC
## GET /knowledge_base

### Description
List all knowledge bases.

### Method
GET

### Endpoint
/knowledge_base

### Response
#### Success Response (200)
- **knowledge_base_id** (string) - The ID of the knowledge base.
- **knowledge_base_name** (string) - The name of the knowledge base.
- **created_at** (string) - Timestamp of creation.
- **updated_at** (string) - Timestamp of last update.
- **status** (string) - Status of the knowledge base.
- **source_count** (integer) - Number of sources in the knowledge base.
- **retrieval_model** (object) - Retrieval model configuration.
- **vector_index_type** (string) - Type of vector index.
- **options** (object) - Additional options.

#### Response Example
```json
[
  {
    "knowledge_base_id": "kb_abc123",
    "knowledge_base_name": "Product Documentation",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z",
    "status": "ready",
    "source_count": 1,
    "retrieval_model": {
      "type": "retrieval"
    },
    "vector_index_type": "hnsw",
    "options": {}
  }
]
```
```

--------------------------------

### Update Call Metadata and Storage Settings

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/call.md

Modify call metadata and data storage settings using the call's 'callID'. This example updates 'data_storage_setting' and adds 'metadata'.

```typescript
const updated = await client.call.update('call_abc123', {
  data_storage_setting: 'everything_except_pii',
  metadata: {
    customer_id: 'cust_123',
    notes: 'Follow-up required',
  },
});
```

--------------------------------

### Test Agent Prompt with Playground

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/playground.md

Creates a test LLM and agent, then uses the playground to test a specific prompt with user input. Returns the agent's response content.

```typescript
const testPrompt = async (prompt: string, userMessage: string) => {
  // Create a test LLM with the prompt
  const llm = await client.llm.create({
    general_prompt: prompt,
  });
  
  // Create test agent
  const agent = await client.agent.create({
    response_engine: {
      type: 'retell-llm',
      llm_id: llm.llm_id,
    },
    voice_id: 'retell-Cimo',
  });
  
  // Test in playground
  const response = await client.playground.completion(agent.agent_id, {
    messages: [
      {
        role: 'user',
        content: userMessage,
      },
    ],
  });
  
  return response.messages[0]?.content;
};

const agentResponse = await testPrompt(
  'You are a helpful customer service bot.',
  'What are your hours?'
);
console.log(agentResponse);
```

--------------------------------

### Create a Knowledge Base

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/knowledge-base.md

Use this method to create a new knowledge base. The name is required for identification.

```typescript
const kb = await client.knowledgeBase.create({
  knowledge_base_name: 'Product Documentation',
});

console.log(kb.knowledge_base_id);
```

--------------------------------

### create

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/chat-agent.md

Create a new chat agent.

```APIDOC
## create

### Description
Create a new chat agent.

### Method
POST

### Endpoint
/v1/chat_agents

### Parameters
#### Request Body
- **body** (`ChatAgentCreateParams`) - Required - Chat agent configuration
- **options** (`RequestOptions`) - Optional - Request options

### Request Example
```json
{
  "response_engine": {
    "llm_id": "llm_abc123",
    "type": "retell-llm"
  },
  "agent_name": "Chat Support Bot"
}
```

### Response
#### Success Response (200)
- **agent_id** (string) - The created chat agent object
- **agent_name** (string) - The name of the agent
- **response_engine** (object) - The response engine configuration

#### Response Example
```json
{
  "agent_id": "agent_xyz789",
  "agent_name": "Chat Support Bot",
  "response_engine": {
    "llm_id": "llm_abc123",
    "type": "retell-llm"
  }
}
```
```

--------------------------------

### Handling PermissionDeniedError for Access Issues

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/errors.md

Catch permission denied errors when a user or API key lacks the necessary permissions to perform an action. This helps in guiding users on access requirements.

```typescript
try {
  await client.agent.delete('agent_id');
} catch (err) {
  if (err instanceof Retell.PermissionDeniedError) {
    console.log('You do not have permission to delete this agent');
  }
}
```

--------------------------------

### createVersion

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/chat-agent.md

Create a new draft version of a chat agent.

```APIDOC
## createVersion

### Description
Create a new draft version of a chat agent.

### Method
POST

### Endpoint
/v1/chat_agents/{agent_id}/versions

### Parameters
#### Path Parameters
- **agentID** (`string`) - Required - The agent ID

#### Request Body
- **body** (`ChatAgentCreateVersionParams`) - Required - Version parameters

### Request Example
```json
{
  "base_version": 4
}
```

### Response
#### Success Response (200)
- **version** (number) - The new draft version number

#### Response Example
```json
{
  "version": 5
}
```
```

--------------------------------

### List, Get, and Update Conversation Flows

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/conversation-flow.md

This snippet demonstrates how to list all existing conversation flows, organize them by name, retrieve a specific flow, and update its name. Ensure the flow you are trying to update exists.

```typescript
// List all flows
const flows = await client.conversationFlow.list();

// Organize by name
const flowsByName = new Map();
for (const flow of flows) {
  flowsByName.set(flow.conversation_flow_name, flow);
}

// Get specific flow
const supportFlow = flowsByName.get('Customer Support');
if (supportFlow) {
  console.log(`Support flow ID: ${supportFlow.conversation_flow_id}`);
}

// Update flow
await client.conversationFlow.update(supportFlow.conversation_flow_id, {
  conversation_flow_name: 'Enhanced Customer Support v2',
});
```

--------------------------------

### Manage Chat Agent Versions

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/chat-agent.md

Demonstrates version management for a chat agent, including retrieving, creating drafts, updating, testing, and publishing.

```typescript
// Get current version
const latest = await client.chatAgent.retrieve('agent_abc123');

// Create a new draft based on current version
const draft = await client.chatAgent.createVersion('agent_abc123', {
  base_version: latest.version,
});

// Make updates
const updated = await client.chatAgent.update('agent_abc123', {
  agent_name: 'Updated Chat Agent',
});

// Test in playground
const testResponse = await client.playground.completion('agent_abc123', {
  messages: [{ role: 'user', content: 'Hello' }],
});

// If satisfied, publish
await client.chatAgent.publish('agent_abc123', {
  version: updated.version,
});
```

--------------------------------

### create

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/llm.md

Create a new Retell LLM Response Engine.

```APIDOC
## create

### Description
Create a new Retell LLM Response Engine.

### Method
POST

### Endpoint
/llm

### Parameters
#### Request Body
- **general_prompt** (string) - Required - The general prompt for the LLM.
- **general_tools** (array) - Optional - A list of tools the LLM can use.
  - **name** (string) - Required - The name of the tool.
  - **description** (string) - Required - The description of the tool.
  - **type** (string) - Required - The type of the tool.

### Request Example
```json
{
  "general_prompt": "You are a helpful customer service assistant.",
  "general_tools": [
    {
      "name": "check_balance",
      "description": "Check the customer balance",
      "type": "function"
    }
  ]
}
```

### Response
#### Success Response (200)
- **llm_id** (string) - The ID of the created LLM.
- **general_prompt** (string) - The general prompt for the LLM.
- **general_tools** (array) - A list of tools the LLM can use.

### Response Example
```json
{
  "llm_id": "llm_xyz789",
  "general_prompt": "You are a helpful customer service assistant.",
  "general_tools": [
    {
      "name": "check_balance",
      "description": "Check the customer balance",
      "type": "function"
    }
  ]
}
```
```

--------------------------------

### Send Messages to Agent for Completion

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/playground.md

Use the `completion` method to send a sequence of messages to an agent and get its response. This is useful for testing agent prompts and behavior during development. The `agentID` and `params` (including messages) are required.

```typescript
const response = await client.playground.completion('agent_abc123', {
  messages: [
    {
      content: "Hi, I'd like to check my appointment.",
      role: 'user',
    },
    {
      content: 'Sure! Could you please provide your name?',
      role: 'agent',
    },
    {
      content: 'My name is John Smith.',
      role: 'user',
    },
  ],
});

console.log(response.messages); // New messages from agent
console.log(response.call_ended); // Whether agent ended conversation
```

--------------------------------

### Handling API Promises

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/README.md

All API methods return APIPromise<T>, which offers special methods for handling responses. You can await the direct response, get the raw response with headers, or access the response object without consuming the body.

```typescript
// Await the response
const agent = await client.agent.create(params);

// Get raw response with headers
const { data, response } = await client.agent.create(params).withResponse();
console.log(response.headers);

// Get response object without consuming body
const response = await client.agent.create(params).asResponse();
```

--------------------------------

### KnowledgeBaseCreateParams Interface

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/knowledge-base.md

Defines the parameters required for creating a new knowledge base. Requires a name and optionally accepts a description.

```typescript
interface KnowledgeBaseCreateParams {
  knowledge_base_name: string;
  description?: string;
  [key: string]: unknown;
}
```

--------------------------------

### Use Undocumented Request Parameters

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/README.md

To use undocumented parameters, add `// @ts-expect-error` before the parameter. The library sends extra values as-is. For GET requests, extra params go in the query; for others, they go in the body.

```typescript
client.agent.create({
  // ...
  // @ts-expect-error baz is not yet public
  baz: 'undocumented option',
});
```

--------------------------------

### Run MCP Server Directly with npx

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/packages/mcp-server/README.md

Use this command to run the MCP Server directly. Ensure your RETELL_API_KEY environment variable is set.

```sh
export RETELL_API_KEY="YOUR_RETELL_API_KEY"
npx -y @retell-ai/mcp-server@latest
```

--------------------------------

### Link Local SDK Repository with Yarn

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/CONTRIBUTING.md

Clone the repository and use `yarn link` to link a local copy of the SDK into your project. This is useful for development.

```sh
# Clone
$ git clone https://www.github.com/RetellAI/retell-typescript-sdk
$ cd retell-typescript-sdk

# With yarn
$ yarn link
$ cd ../my-package
$ yarn link retell-sdk
```

--------------------------------

### client.chat.create

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/api.md

Creates a new chat. This method initiates a chat session.

```APIDOC
## POST /create-chat

### Description
Creates a new chat.

### Method
POST

### Endpoint
/create-chat

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating a chat.
```

--------------------------------

### Project Structure Overview

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/DOCUMENTATION_SUMMARY.md

This snippet outlines the directory structure of the Retell TypeScript/JavaScript SDK repository. It helps users navigate and understand the organization of documentation and API reference files.

```markdown
```
/workspace/home/output/
├── README.md                          # Main overview
├── DOCUMENTATION_SUMMARY.md           # This file
├── types.md                          # Type reference
├── configuration.md                  # Configuration guide
├── errors.md                         # Error handling
└── api-reference/                    # Individual resource APIs
    ├── INDEX.md                      # Navigation index
    ├── client.md                     # Retell client class
    ├── agent.md                      # Voice agents
    ├── chat-agent.md                 # Chat agents
    ├── call.md                       # Phone/web calls
    ├── chat.md                       # Chat sessions
    ├── llm.md                        # LLM engines
    ├── voice.md                      # TTS voices
    ├── playground.md                 # Agent testing
    ├── conversation-flow.md          # Flow-based agents
    ├── knowledge-base.md             # Knowledge bases
    └── phone-number.md               # Phone numbers
```
```

--------------------------------

### Configure Bun Proxy

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/README.md

For Bun runtime, you can specify a proxy URL directly within the `fetchOptions` object when creating the Retell client.

```typescript
import Retell from 'retell-sdk';

const client = new Retell({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});
```

--------------------------------

### Create Chat Agent for Web Chat Integration

Source: https://github.com/retellai/retell-typescript-sdk/blob/main/_autodocs/api-reference/chat-agent.md

Create a chat agent and then set up a chat session for web integration. This involves creating a chat and sending messages.

```typescript
const agent = await client.chatAgent.create({
  response_engine: {
    type: 'retell-llm',
    llm_id: 'llm_abc123',
  },
  agent_name: 'Web Chat Bot',
});

// Create a chat session for web
const chat = await client.chat.create({
  agent_id: agent.agent_id,
  user_name: 'Website Visitor',
});

// Send messages
const response = await client.chat.createChatCompletion({
  chat_id: chat.chat_id,
  content: 'I need help with my order',
});
```