​
Overview

Retell provides official SDKs for Node.js and Python to simplify integration with our platform. While you can use our REST API directly, our SDKs offer:
  • 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.7 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.
API Keys tab in Retell dashboard showing where to find and copy your API key
2

Install the SDK

Choose your preferred language and install the SDK:
npm i retell-sdk
3

Initialize the Client

Create a new client instance using your API key:
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:
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);
}

​
SDK vs REST API Comparison

To illustrate the benefits of using our SDK, here’s a comparison of creating an agent using both methods:

​
Using REST API (More Verbose)

const options = {
  method: 'POST',
  headers: {
    Authorization: '<authorization>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    response_engine: {
      type: 'retell-llm',
      llm_id: 'llm_234sdertfsdsfsdf'
    },
    agent_name: 'Jarvis',
    voice_id: '11labs-Adrian',
    // ... many more configuration options
  })
};

fetch('https://api.retellai.com/create-agent', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

​
Using SDK (More Concise)

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

async function main() {
  const params: Retell.AgentCreateParams = {
    response_engine: { 
      llm_id: 'llm_234sdertfsdsfsdf',
      type: 'retell-llm'
    },
    voice_id: '11labs-Adrian',
  };
  const agentResponse = await client.agent.create(params);
}

​
Best Practices

​
1. Error Handling

Always wrap SDK calls in try-catch blocks to handle potential errors gracefully: 
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

Store your API key securely using environment variables: 
const retellClient = new Retell({
  apiKey: process.env.RETELL_API_KEY,
});

​
3. Type Safety

Leverage TypeScript types for better developer experience: 
import { Retell, AgentCreateParams } from 'retell-sdk';

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

​
Additional Resources

Find more SDK examples in our test suites to learn more about how to use the SDK: