SDKs

Official SDKs for Node.js and Python to integrate Retell AI phone agents into your applications

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.

   
2. Install the SDK

   Choose your preferred language and install the SDK:

   Node Client

   npm i retell-sdk
   
3. Initialize the Client

   Create a new client instance using your API key:

   Node 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

   try {
     const response = await retellClient.call.createPhoneCall({
       from_number: '[phone]',
       to_number: '[phone]',
     });
     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:

• Node.js SDK Examples
• Python SDK Examples