SDKs

Official Node.js and Python SDKs to integrate UponAI phone agents into your applications.

UponAI provides official SDKs for Node.js and Python. While you can use the REST API directly, the 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

Node.js / TypeScript

Package: retell-sdk on NPM

Requirements: Node.js 18.10.0 or higher

Features: Full TypeScript support, async/await, promise-based API

Python

Package: retell-sdk on PyPI

Requirements: Python 3.7 or higher

Features: Type hints, async support, comprehensive error handling

Setup

1. Get your API key

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

2. Install the SDK

   Node.js

   npm i retell-sdk
   

   Python

   pip install retell-sdk
   
3. Initialize the client

   Node.js

   import Retell from 'retell-sdk';
   
   const client = new Retell({
     apiKey: process.env.RETELL_API_KEY,
   });
   

   Python

   from retell import Retell
   
   client = Retell(api_key=os.environ["RETELL_API_KEY"])
   
4. Make your first API call

   Node.js

   try {
     const response = await client.call.createPhoneCall({
       from_number: '[phone]',
       to_number: '[phone]',
     });
     console.log('Call initiated:', response);
   } catch (error) {
     console.error('Error making call:', error);
   }
   

   Python

   response = client.call.create_phone_call(
       from_number="[phone]",
       to_number="[phone]",
   )
   print("Call initiated:", response)
   

SDK vs REST API

REST API (verbose)

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

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

Best Practices

Error handling — always wrap SDK calls in try/catch:

try {
  const response = await client.call.createPhoneCall(params);
} catch (error) {
  if (error.code === 'insufficient_funds') {
    // handle specific error
  }
}

Environment variables — never hardcode API keys:

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

TypeScript types — use provided types for autocomplete:

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

const params: AgentCreateParams = {
  // TypeScript will autocomplete available fields
};