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

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