While you can use our REST API for most operations, we recommend using our SDKs to speed up development and reduce code complexity. Our SDKs provide typed methods and a more structured approach to integrating with Retell.

​
Available SDKs & Requirements

  • Node.js TypeScript SDK
    • NPM Package
    • Requires Node.js version 18.10.0 or higher
  • Python SDK
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:
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 Example

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
  2. Type Safety: Take advantage of TypeScript types in the Node.js SDK
  3. API Reference: Refer to our API documentation for all available parameters

​
Additional Resources

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