Retell AI Deploy Integration

Overview

Deploy Retell AI voice agent applications to production. Covers configuring voice agent webhooks, deploying WebSocket endpoints for real-time audio, and managing API credentials for Retell AI's call management API at api.retellai.com.

Prerequisites

• Retell AI API key stored in RETELL_API_KEY environment variable
• Voice agent configured in Retell AI dashboard
• HTTPS endpoint for webhooks and WebSocket connections
• Platform CLI installed (vercel, fly, or gcloud)

Instructions

Step 1: Configure Secrets

# Fly.io (recommended for WebSocket support)
fly secrets set RETELL_API_KEY=your-key
fly secrets set RETELL_WEBHOOK_SECRET=your-secret

# Cloud Run
echo -n "your-key" | gcloud secrets create retell-api-key --data-file=-

Step 2: Deploy WebSocket Server

// server.ts - WebSocket for real-time audio
import { WebSocketServer } from "ws";
import express from "express";

const app = express();
const server = app.listen(process.env.PORT || 3000);  # 3000: 3 seconds in ms
const wss = new WebSocketServer({ server, path: "/ws/call" });

wss.on("connection", (ws, req) => {
  const callId = new URL(req.url!, `http://${req.headers.host}`).searchParams.get("call_id");
  console.log(`WebSocket connected for call: ${callId}`);

  ws.on("message", (data) => {
    // Process audio stream from Retell AI
    handleAudioChunk(callId!, data);
  });

  ws.on("close", () => {
    console.log(`Call ${callId} WebSocket closed`);
  });
});

Step 3: Fly.io Deployment

# fly.toml
app = "retellai-voice-server"
primary_region = "iad"

[env]
NODE_ENV = "production"

[http_service]
internal_port = 3000  # 3000: 3 seconds in ms
force_https = true
auto_stop_machines = false
auto_start_machines = true
min_machines_running = 1

[checks]
  [checks.health]
    type = "http"
    port = 3000  # 3 seconds in ms
    path = "/health"
    interval = "30s"

fly deploy

Step 4: Webhook Endpoint

// api/webhooks/retellai.ts
app.post("/webhooks/retellai", express.raw({ type: "application/json" }), (req, res) => {
  const event = JSON.parse(req.body.toString());
  res.status(200).json({ received: true });  # HTTP 200 OK

  switch (event.event) {
    case "call_ended":
      processCallTranscript(event.call);
      break;
    case "call_analyzed":
      syncCallAnalysis(event.call);
      break;
  }
});

Step 5: Register Agent Webhook

set -euo pipefail
curl -X PATCH https://api.retellai.com/v2/agent/$AGENT_ID \
  -H "Authorization: Bearer $RETELL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-app.fly.dev/webhooks/retellai",
    "websocket_url": "wss://your-app.fly.dev/ws/call"
  }'

Error Handling

Issue	Cause	Solution
WebSocket disconnect	Server restart	Use min_machines_running: 1
Audio latency	Wrong region	Deploy close to Retell AI servers (US East)
Webhook signature fail	Wrong secret	Verify secret in Retell AI dashboard
Call quality issues	Network jitter	Use dedicated VM, not serverless

Examples

Basic usage: Apply retellai deploy integration to a standard project setup with default configuration options.

Advanced scenario: Customize retellai deploy integration for production environments with multiple constraints and team-specific requirements.

Resources

• Retell AI Documentation
• Retell AI WebSocket API
• Fly.io WebSocket Guide

Next Steps

For multi-environment setup, see retellai-multi-env-setup.

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale