Retell AI Advanced Troubleshooting

Overview

Implementation patterns for Retell AI advanced troubleshooting — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for advanced troubleshooting

Error Handling

Examples

Isolate a voice-call failure without changing production routing

Reproduce the reported failure with a test number and a non-production agent version. Capture the call identifier, selected agent version, webhook response code, and timestamp; redact caller audio and personal data from the ticket. Compare that evidence with one successful test call before changing prompts, transfers, or routing. Promote the smallest verified correction through the preview path, then retain the before/after identifiers for rollback.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Architecture Variants

Overview

Implementation patterns for Retell AI architecture variants — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for architecture variants

Error Handling

Examples

Choose a queue-backed architecture for bursty inbound calls

For a campaign that creates short spikes, keep the public number attached to a stable routing layer and place CRM enrichment behind an asynchronous queue. Start with a preview agent that records only synthetic test calls, set a clear timeout for the enrichment request, and configure a human-transfer fallback. Measure latency and transfer rate during the canary before selecting the variant for production traffic.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Ci Integration

Overview

Implementation patterns for Retell AI ci integration — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for ci integration

Error Handling

Examples

Validate an agent configuration in a pull request

In CI, lint the agent configuration and run a scripted call against a dedicated test agent using a masked test credential. Assert the expected tool invocation, handoff outcome, and redacted transcript markers, but never upload real call audio or customer data. Publish the test result as a PR artifact and require a separate promotion step before the tested configuration reaches a live number.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Common Errors

Overview

Quick reference for the top Retell AI errors and their solutions.

Prerequisites

• retell-sdk installed
• API key configured

Instructions

Error 1: 401 Unauthorized

RetellError: 401 — Invalid API key

Fix: Verify API key in Retell Dashboard. Ensure RETELL_API_KEY starts with key_.

Error 2: Call Fails Immediately

RetellError: 400 — Invalid phone number format

Fix: Use E.164 format: +14155551234. Both from_number and to_number must be valid.

Error 3: Agent Not Responding

Call connected but agent says nothing

Fix: Check LLM configuration:

const llm = await retell.llm.retrieve(agent.response_engine.llm_id);
console.log(`Model: ${llm.model}`);
console.log(`Prompt length: ${llm.general_prompt.length} chars`);
// Ensure general_prompt is not empty and gives clear instructions

Error 4: Function Call Timeout

Function call to https://your-api.com/endpoint timed out

Fix: Your function endpoint must respond within 5 seconds. Offload heavy work:

app.post('/functions/lookup', async (req, res) => {
  // Respond immediately with acknowledgment
  const result = await quickLookup(req.body.args);
  res.json({ result: `Found: ${result.name}` });
  // Do NOT run async work before responding
});

Error 5: Webhook Not Receiving Events

No webhook events received after call

Fix: Set webhook_url on the agent, not just in Dashboard settings:

await retell.agent.update(agentId, {
  webhook_url: 'https://your-app.com/webhooks/retell',
});

Error 6: Voice Quality Issues

Agent voice sounds robotic/choppy

Fix: Check network latency to Retell servers. Use a voice optimized for your use case. Try different voice IDs.

Output

• Error identified and root cause found
• Fix applied and verified
• Call successfully completed

Error Handling

Examples

Triage a failed outbo…

Retell AI Core Workflow A

Overview

Build and configure voice agents with custom prompts, function calling, and call flow logic.

Prerequisites

• Completed retellai-hello-world

Instructions

Step 1: Agent with Function Calling

const llm = await retell.llm.create({
  model: 'gpt-4o',
  general_prompt: `You are a booking assistant for Dr. Smith's office.
    - Help callers book, reschedule, or cancel appointments
    - Collect: name, phone, preferred date/time
    - Confirm all details before booking`,
  functions: [
    {
      name: 'book_appointment',
      description: 'Book a new appointment',
      parameters: {
        type: 'object',
        properties: {
          patient_name: { type: 'string' },
          phone: { type: 'string' },
          date: { type: 'string', description: 'YYYY-MM-DD format' },
          time: { type: 'string', description: 'HH:MM format' },
        },
        required: ['patient_name', 'phone', 'date', 'time'],
      },
      url: 'https://your-api.com/appointments',
      speak_during_execution: true,
      speak_after_execution: true,
    },
  ],
});

Step 2: Configure Voice and Behavior

const agent = await retell.agent.create({
  response_engine: { type: 'retell-llm', llm_id: llm.llm_id },
  voice_id: '11labs-Rachel',
  agent_name: 'Dr. Smith Booking Agent',
  language: 'en-US',
  opt_out_sensitive_data_storage: false,
  end_call_after_silence_ms: 10000,  // End call after 10s silence
  max_call_duration_ms: 300000,       // 5-minute max
  enable_backchannel: true,           // "mhm", "yeah" responses
  boosted_keywords: ['appointment', 'schedule', 'Dr. Smith'],
});

Step 3: Update Agent Configuration

await retell.agent.update(agent.agent_id, {
  voice_id: '11labs-Dorothy',  // Change voice
  end_call_after_silence_ms: 15000,
});

Output

• Agent with custom LLM prompt and function calling
• Voice and behavior configuration
• Real-time function execution during calls

Error Handling

Examples

Create and validate a new appointment-intake agent

Retell AI Core Workflow B

Overview

Manage phone calls: outbound campaigns, call transfers, recordings, and concurrent call handling.

Prerequisites

• Completed retellai-core-workflow-a

Instructions

Step 1: Outbound Call Campaign

const phoneNumbers = ['+14155551001', '+14155551002', '+14155551003'];

for (const number of phoneNumbers) {
  try {
    const call = await retell.call.createPhoneCall({
      from_number: process.env.RETELL_PHONE_NUMBER!,
      to_number: number,
      override_agent_id: agentId,
      metadata: { campaign: 'appointment-reminder', date: '2026-04-01' },
    });
    console.log(`Called ${number}: ${call.call_id}`);
  } catch (err) {
    console.error(`Failed to call ${number}: ${err.message}`);
  }
  // Rate limit: space calls apart
  await new Promise(r => setTimeout(r, 2000));
}

Step 2: List and Filter Calls

const calls = await retell.call.list({
  sort_order: 'descending',
  limit: 20,
});
for (const call of calls) {
  console.log(`${call.call_id}: ${call.call_status} — ${call.end_timestamp - call.start_timestamp}ms`);
}

Step 3: Get Call Recording and Transcript

const callDetail = await retell.call.retrieve(callId);
if (callDetail.recording_url) {
  console.log(`Recording: ${callDetail.recording_url}`);
}
if (callDetail.transcript) {
  console.log(`Transcript:\n${callDetail.transcript}`);
}

Output

• Outbound call campaign with rate limiting
• Call listing with status and duration
• Recordings and transcripts retrieved

Error Handling

Examples

Run a bounded outbound appointment reminder campaign

Upload only consented test contacts to a development campaign and set a small concurrency limit before enabling any production queue. For each test call, verify the E.164 number formatting, expected agent version, completion status, and redacted transcript retrieval. If a call result is ambiguous, query the call identifier before retrying so an operator does not create duplicate calls or overwrite the original outcome.

Resources

• Create Phone Call
• Retell AI Documentation

Next Steps

Handle call event…

Retell AI Cost Tuning

Overview

Implementation patterns for Retell AI cost tuning — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for cost tuning

Error Handling

Examples

Reduce cost without degrading a required human handoff

Measure average call duration, transfer rate, and failed-call retries for a representative non-production sample before changing prompt length or model settings. Trial the lower-cost configuration on a small canary, retaining the existing agent version as rollback. Keep the human-handoff trigger unchanged unless the service owner approves a new threshold; a shorter call is not a saving if it silently increases unresolved customer requests.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Data Handling

Overview

Implementation patterns for Retell AI data handling — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for data handling

Error Handling

Examples

Minimize transcript data in a support escalation

For a failed call, retain the call identifier, timestamps, selected agent version, and error classification in the incident record. Do not paste full recordings or transcripts into a ticket; redact names, phone numbers, and payment details before attaching a narrow excerpt. Set the retention owner and expiry for the exported evidence, then delete the copy after the investigation and any agreed remediation are complete.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Debug Bundle

Overview

Implementation patterns for Retell AI debug bundle — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for debug bundle

Error Handling

Examples

Assemble a safe support bundle for an intermittent failure

Collect the affected call ID, agent version, webhook status, API response headers, and deployment revision from a test or consented call. Exclude API keys, raw audio, and full transcripts from the archive; include a redacted timeline instead. Reproduce against a preview agent before changing the live configuration, and preserve the bundle checksum so the support handoff can be matched to the exact evidence reviewed.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Deploy Integration

Overview

Implementation patterns for Retell AI deploy integration — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for deploy integration

Error Handling

Examples

Promote a tested agent configuration through a preview route

Create a versioned agent configuration and attach it to an internal preview number first. Exercise a synthetic call that verifies the expected webhook, tool permissions, and fallback transfer, then record the configuration version and test result. Promote only that reviewed version to the production routing rule, while retaining the previous version and its routing target for a fast, auditable rollback if call quality or completion rate regresses.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Enterprise Rbac

Overview

Implementation patterns for Retell AI enterprise rbac — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for enterprise rbac

Error Handling

Examples

Grant a release operator access without granting call-data access

Create a role limited to publishing an approved agent version and inspecting deployment status. Do not include transcript, recording, billing, or user management permissions in that role. Test the role against a preview agent: it should promote the designated version but fail to retrieve protected call content. Record the role, environment, and approver before assigning it to a new operator, and remove the assignment when the release window closes.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Hello World

Overview

Create your first Retell AI voice agent and make a test phone call.

Prerequisites

• Completed retellai-install-auth
• A phone number registered in Retell AI Dashboard (or use web call for testing)

Instructions

Step 1: Create an LLM Configuration

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

// Create LLM configuration (what the agent says)
const llm = await retell.llm.create({
  model: 'gpt-4o',
  general_prompt: `You are a friendly receptionist for Acme Corp.
    - Greet callers warmly
    - Ask how you can help
    - Take messages if needed
    - Be concise and professional`,
});
console.log(`LLM created: ${llm.llm_id}`);

Step 2: Create a Voice Agent

const agent = await retell.agent.create({
  response_engine: {
    type: 'retell-llm',
    llm_id: llm.llm_id,
  },
  voice_id: '11labs-Adrian',  // Choose from available voices
  agent_name: 'Acme Receptionist',
});
console.log(`Agent created: ${agent.agent_id}`);

Step 3: Make a Test Phone Call

// Outbound call (requires a registered phone number)
const call = await retell.call.createPhoneCall({
  from_number: '+14155551234',  // Your Retell number
  to_number: '+14155555678',    // Destination
  override_agent_id: agent.agent_id,
});
console.log(`Call initiated: ${call.call_id}`);

Step 4: Or Test with Web Call

// Web call (no phone number needed — great for testing)
const webCall = await retell.call.createWebCall({
  agent_id: agent.agent_id,
});
console.log(`Web call URL: ${webCall.call_id}`);
// Use retell-client-js-sdk to connect from browser

Step 5: Check Call Status

const callDetail = await retell.call.retrieve(call.call_id);
console.log(`Status: ${callDetail.call_status}`);
console.log(`Duration: ${callDetail.end_timestamp - callDetail.start_timestamp}ms`);
if (callDetail.transcript) {
  console.log(`Transcript: ${callDetail.transcript}`);
}

Output

• LLM configuration with custom prompt
• Voice agent with selected voice
• Test call initiated (phone or web)
• Call status and transcript retrieved

Error Handling

Retell AI Incident Runbook

Overview

Implementation patterns for Retell AI incident runbook — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for incident runbook

Error Handling

Examples

Contain a spike in failed transfers

When transfer failures cross the alert threshold, freeze new agent promotions and route new calls to the last known-good agent or human queue. Capture call identifiers, agent versions, transfer destinations, and response codes without copying recordings into the incident channel. Compare a synthetic preview call with the affected production version, make one reversible routing change, and document the rollback condition before restoring normal traffic.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Install Auth

Overview

Install the Retell AI SDK and configure API key authentication for building voice agents.

Prerequisites

• Retell AI account at retellai.com
• API key from the Retell AI dashboard
• Node.js 18+ or Python 3.9+

Instructions

Step 1: Install SDK

set -euo pipefail
# Node.js
npm install retell-sdk

# Python
pip install retell-sdk

Step 2: Configure Environment

# .env
RETELL_API_KEY=key_xxxxxxxxxxxxxxxxxxxxxxxx

Step 3: Initialize Client (Node.js)

import Retell from 'retell-sdk';

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

// Verify connection — list agents
const agents = await retell.agent.list();
console.log(`Connected! ${agents.length} agent(s) configured.`);

Step 4: Initialize Client (Python)

from retell import Retell
import os

retell = Retell(api_key=os.environ["RETELL_API_KEY"])
agents = retell.agent.list()
print(f"Connected! {len(agents)} agent(s) configured.")

Output

• retell-sdk installed
• API key configured
• Connection verified with agent listing

Error Handling

Examples

Configure a least-privilege development credential

Store a non-production API key in the local secret manager or CI secret store, not in source control or a command history. Verify it by listing development agents and record only the account, environment, and verification time. If the test returns an authorization error, revoke the invalid credential rather than trying alternate keys in logs; use a separate production credential only in a protected deployment environment.

Resources

• Retell AI SDKs
• retell-sdk npm

Next Steps

Create your first agent: retellai-hello-world

Retell AI Known Pitfalls

Overview

Implementation patterns for Retell AI known pitfalls — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for known pitfalls

Error Handling

Examples

Avoid a duplicate-call retry after a network timeout

An outbound request times out after submission. Before retrying, look up the request correlation or call identifier to determine whether Retell already created the call. If state is unknown, hold the retry and escalate with the redacted request metadata; sending a second request can contact the same person twice. Add bounded retries only where the operation is explicitly idempotent and monitor the duplicate-call rate after the change.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Load Scale

Overview

Implementation patterns for Retell AI load scale — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for load scale

Error Handling

Examples

Load-test an inbound queue without contacting real callers

Use a preview number and synthetic caller identities to ramp concurrency in small steps. Record queue time, model latency, transfer rate, error rate, and the configured concurrency limit at each step. Stop the test when the agreed latency or error budget is crossed instead of compensating with unbounded retries. Use the result to set an initial production ceiling and retain the last known-good limit as the rollback value.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Local Dev Loop

Overview

Implementation patterns for Retell AI local dev loop — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for local dev loop

Error Handling

Examples

Iterate on a prompt with a deterministic local test set

Keep a small suite of synthetic caller intents, including a successful request, an unclear request, and a required human handoff. Run that suite against a development agent after each prompt or tool-schema change and compare only redacted outcomes such as route, tool arguments, and completion state. Do not point local development at a production phone number; publish a versioned preview only after the suite continues to meet its expected behavior.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Migration Deep Dive

Overview

Implementation patterns for Retell AI migration deep dive — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for migration deep dive

Error Handling

Examples

Migrate one agent while preserving a rollback path

Export the current agent configuration and record its version, routing rule, and supported handoff behavior before making schema or prompt changes. Import the candidate into a preview environment, replay synthetic scenarios, and compare the redacted outcomes with the old version. Move a small canary route only after those checks pass; leave the previous configuration intact until the canary completion and escalation rates remain within the agreed bounds.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Multi Env Setup

Overview

Implementation patterns for Retell AI multi env setup — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for multi env setup

Error Handling

Examples

Keep development and production credentials separated

Create distinct Retell projects or explicitly named agent groups for development, staging, and production. Each environment receives its own secret reference and phone routing configuration, so a local test cannot accidentally create a live call. Verify the separation by listing agents with the development credential and confirming that production identifiers are absent; promote configuration through a controlled CI environment instead of copying keys between files.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Observability

Overview

Implementation patterns for Retell AI observability — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for observability

Error Handling

Examples

Alert on a regression while protecting call content

Emit structured metrics for call completion, transfer outcome, latency, and provider errors using agent version and environment as bounded labels. When an alert fires, link the affected call identifiers to a restricted investigation record instead of attaching transcripts to the dashboard. Compare a synthetic call against the last known-good version, then make one reversible routing or configuration change and watch the same metrics through the defined recovery window.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Performance Tuning

Overview

Implementation patterns for Retell AI performance tuning — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for performance tuning

Error Handling

Examples

Improve response latency with a measured canary

Capture baseline end-to-end latency, model latency, transfer outcome, and completion rate for a synthetic test suite before changing an agent setting. Apply one prompt, model, or integration change to a preview version and repeat the same suite. Promote to a small canary only if latency improves without a drop in completion or an increase in handoffs; otherwise restore the prior version and retain the comparison as the performance decision record.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Policy Guardrails

Overview

Implementation patterns for Retell AI policy guardrails — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for policy guardrails

Error Handling

Examples

Restrict a booking agent to an approved action boundary

Give an appointment agent only the lookup and create-booking tools needed for its flow, with explicit argument validation and a human handoff for refunds, medical questions, or account changes. Test synthetic prompts that attempt each forbidden action and verify that the agent refuses or transfers rather than improvising. Version the policy with the agent and review deviations from the guardrail before widening any permission.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Prod Checklist

Overview

Implementation patterns for Retell AI prod checklist — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for prod checklist

Error Handling

Examples

Approve a limited production launch

Before routing a live number, verify the exact agent version, environment secret references, consent and disclosure text, fallback transfer destination, and on-call owner. Run a final synthetic call through the production-like preview route and record the result without retaining audio. Start with a small traffic percentage and a defined rollback trigger, then expand only when completion, escalation, and error metrics remain within the release bounds.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Rate Limits

Overview

Implementation patterns for Retell AI rate limits — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for rate limits

Error Handling

Examples

Handle a burst without retrying calls indefinitely

When the API returns a rate-limit response, place only the idempotent request metadata in a bounded queue and honor the provider retry guidance before the next attempt. Track queue age, retry count, and error class; do not retry an ambiguous call-creation request until its call identifier is checked. Alert an operator when the queue age exceeds the service target, and shed nonessential work rather than allowing retries to amplify the burst.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Reference Architecture

Overview

Implementation patterns for Retell AI reference architecture — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for reference architecture

Error Handling

Examples

Separate the call path from slow business-system enrichment

Route the voice agent through a stable API boundary that validates inputs and returns a bounded response, while sending slow CRM or analytics enrichment to an asynchronous worker. The agent receives a clear timeout and human-transfer fallback if the business system is unavailable. Exercise this topology with a synthetic outage before launch, then document which component owns retries, audit events, and the rollback to the prior routing configuration.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Reliability Patterns

Overview

Implementation patterns for Retell AI reliability patterns — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for reliability patterns

Error Handling

Examples

Design a safe fallback for a dependent CRM outage

Give the voice flow a short, explicit timeout for CRM lookup and a fallback response that either schedules a follow-up or transfers to a human queue. Test the fallback by making the preview CRM endpoint return a controlled error, then confirm no call is retried or double-booked. Track the fallback rate separately from general call failures and remove the temporary routing change only after the dependency and a synthetic recovery call both succeed.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI SDK Patterns

Overview

Production-ready patterns for Retell AI: client singletons, typed agent configurations, call management, and error handling.

Prerequisites

• Completed retellai-install-auth
• retell-sdk installed

Instructions

Step 1: Singleton Client

import Retell from 'retell-sdk';

let _retell: Retell | null = null;

export function getRetellClient(): Retell {
  if (!_retell) {
    _retell = new Retell({ apiKey: process.env.RETELL_API_KEY! });
  }
  return _retell;
}

Step 2: Typed Agent Configuration

interface AgentConfig {
  name: string;
  voiceId: string;
  prompt: string;
  functions?: FunctionConfig[];
  maxCallDurationMs?: number;
  endCallAfterSilenceMs?: number;
}

async function createAgent(config: AgentConfig) {
  const retell = getRetellClient();

  const llm = await retell.llm.create({
    model: 'gpt-4o',
    general_prompt: config.prompt,
    functions: config.functions,
  });

  const agent = await retell.agent.create({
    response_engine: { type: 'retell-llm', llm_id: llm.llm_id },
    voice_id: config.voiceId,
    agent_name: config.name,
    max_call_duration_ms: config.maxCallDurationMs || 300000,
    end_call_after_silence_ms: config.endCallAfterSilenceMs || 10000,
  });

  return { agentId: agent.agent_id, llmId: llm.llm_id };
}

Step 3: Call Manager with Retry

async function makeCallWithRetry(
  fromNumber: string, toNumber: string, agentId: string, maxRetries = 2
) {
  const retell = getRetellClient();
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const call = await retell.call.createPhoneCall({
        from_number: fromNumber,
        to_number: toNumber,
        override_agent_id: agentId,
      });
      return call;
    } catch (err: any) {
      if (attempt === maxRetries || err.status < 500) throw err;
      await new Promise(r => setTimeout(r, 2000 * (attempt + 1)));
    }
  }
}

Step 4: Batch Call Campaign

async function runCallCampaign(
  numbers: string[], agentId: string, concurrency = 3, delayMs = 2000
) {
  const results: Array<{ number: string; callId?: string; error?: string }> = [];
  const queue = [...numbers];
  const active = new Set<Promise<void>>();

  while (queue.length > 0 || active.size > 0) {
    while (active.size < concurrency && queue.length > 0) {
      const number = queue.shift()!;
      const p = (async () => {
        try {
          const call = await makeCallWithRetry(process.env.RETELL_PHONE_NUMBER!, number, agentId);
          results.push({ number, callId: call.call_id });
        } catch (err: any) {
          results.push({ number, error: err.mes…

Retell AI Security Basics

Overview

Implementation patterns for Retell AI security basics — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for security basics

Error Handling

Examples

Rotate an exposed development credential safely

Disable the exposed development key in the provider console, create a scoped replacement, and update only the development secret reference. Verify the new key with a harmless agent-list request while ensuring command output does not print its value. Review access logs and affected preview configurations, then document the incident with the credential identifier and rotation time rather than copying key material into the ticket or source repository.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Upgrade Migration

Overview

Implementation patterns for Retell AI upgrade migration — voice agent and telephony platform.

Prerequisites

• Completed retellai-install-auth setup

Instructions

Step 1: SDK Pattern

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

const agents = await retell.agent.list();
console.log(`Agents: ${agents.length}`);

Output

• Retell AI integration for upgrade migration

Error Handling

Examples

Upgrade an SDK through a compatibility canary

Pin the candidate SDK version in a branch and run the development agent suite against synthetic create-call, retrieval, error, and webhook scenarios. Record the old and new package versions and any changed request shapes, then deploy a preview configuration before altering production dependencies. Keep the prior lockfile and agent version available until the canary has met its error and latency limits, so rollback does not require reconstructing the old runtime.

Resources

• Retell AI Documentation
• retell-sdk npm

Next Steps

See related Retell AI skills for more workflows.

Retell AI Webhooks Events

Overview

Handle Retell AI webhook events for call lifecycle, transcripts, and function execution.

Prerequisites

• HTTPS webhook endpoint
• Agent configured with webhook URL

Instructions

Step 1: Configure Webhook URL

// Set webhook URL in agent configuration
await retell.agent.update(agentId, {
  webhook_url: 'https://your-app.com/webhooks/retell',
});

Step 2: Webhook Endpoint

import express from 'express';

const app = express();
app.post('/webhooks/retell', express.json(), async (req, res) => {
  const { event, call } = req.body;

  switch (event) {
    case 'call_started':
      console.log(`Call started: ${call.call_id} from ${call.from_number}`);
      break;

    case 'call_ended':
      console.log(`Call ended: ${call.call_id}`);
      console.log(`  Duration: ${call.duration_ms}ms`);
      console.log(`  Status: ${call.call_status}`);
      if (call.transcript) {
        await saveTranscript(call.call_id, call.transcript);
      }
      break;

    case 'call_analyzed':
      console.log(`Analysis ready: ${call.call_id}`);
      console.log(`  Summary: ${call.call_analysis?.call_summary}`);
      break;

    default:
      console.log(`Unhandled event: ${event}`);
  }

  res.status(200).json({ received: true });
});

Step 3: Handle Function Calls During Conversation

// When agent triggers a function, Retell calls your URL
app.post('/functions/book-appointment', express.json(), async (req, res) => {
  const { patient_name, phone, date, time } = req.body.args;

  // Process the booking
  const booking = await bookAppointment(patient_name, phone, date, time);

  // Return response for agent to speak
  res.json({
    result: `Appointment booked for ${patient_name} on ${date} at ${time}. Confirmation number: ${booking.id}`,
  });
});

Output

• Webhook handling for call lifecycle events
• Transcript storage on call completion
• Function execution during live calls

Error Handling

Examples

Process a duplicate webhook delivery safely

Verify the webhook signature, derive a stable event identifier, and record the event before invoking any downstream side effect. When the same identifier is received again, acknowledge it without re-sending a notification, …