Retell SDKs for TypeScript and Python

​

Overview

• Type safety: Full TypeScript support with autocomplete
• Simplified authentication: Built-in API key handling
• Error handling: Structured error responses with detailed messages
• Reduced boilerplate: Cleaner, more maintainable code

​

Available SDKs & Requirements

​

Node.js TypeScript SDK

• Package: retell-sdk on NPM
• Requirements: Node.js version 18.10.0 or higher
• Features: Full TypeScript support, async/await, promise-based API

​

Python SDK

• Package: retell-sdk on PyPI
• Requirements: Python 3.9 or higher
• Features: Type hints, async support, comprehensive error handling

1

Get Your API Key

Navigate to the “API Keys” tab in your dashboard to obtain your API key.

2

Install the SDK

Choose your preferred language and install the SDK:

Node Client

Python Client

npm i retell-sdk

3

Initialize the Client

Create a new client instance using your API key:

Node Client

Python Client

import Retell from 'retell-sdk';

const retellClient = new Retell({
  apiKey: "YOUR_API_KEY",
});

4

Make API Calls

Here’s an example of making a phone call using the SDK:

Node Client

Python Client

try {
  const response = await retellClient.call.createPhoneCall({
    from_number: '+14157774444',
    to_number: '+12137774445',
  });
  console.log('Call initiated:', response);
} catch (error) {
  console.error('Error making call:', error);
}

​

Versioning

​

Create an agent with the TypeScript SDK

​

Best Practices

​

1. Error Handling

try {
  const response = await retellClient.call.createPhoneCall(params);
  // Handle success
} catch (error) {
  if (error.code === 'insufficient_funds') {
    // Handle specific error
  }
  // Log error details
}

​

2. Environment Variables

const retellClient = new Retell({
  apiKey: process.env.RETELL_API_KEY,
});

​

3. Type Safety

import { Retell, AgentCreateParams } from 'retell-sdk';

const params: AgentCreateParams = {
  // TypeScript will provide autocomplete here
};

​

Rate Limits

​

429 Response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limiter: general
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 7

{ "status": "error", "message": "Too many API requests, you are being throttled, please try again later." }

​

Handling 429s

• Use RateLimit-Reset (seconds) for backoff; retry with jittered exponential backoff.
• Don’t parallelize list-* calls — the per-route budget is small.
• For high call volume, design around CPS rather than HTTP throughput.