Retell AI Integration

Caller --> Phone Number --> Retell AI (Voice)
                                   |
                                   v
                              LLM Agent
                                   |
                                   v
                          FrontDeskOS MCP Server
                           (Tools + Resources)
                                   |
                                   v
                         Your Business Systems
                    (Calendar, CRM, Phone System)

npm install @frontdeskos/mcp-server @frontdeskos/retell-adapter

# Set your environment variables
export FRONTDESK_API_KEY="sk_live_your_key"
export FRONTDESK_WORKSPACE_ID="ws_your_workspace"
export RETELL_API_KEY="your_retell_api_key"

import { RetellClient } from "retell-sdk";
import { FrontDeskMCPServer } from "@frontdeskos/mcp-server";
import { createRetellAdapter } from "@frontdeskos/retell-adapter";

const retell = new RetellClient({ apiKey: process.env.RETELL_API_KEY! });
const frontdesk = new FrontDeskMCPServer({
  apiKey: process.env.FRONTDESK_API_KEY!,
  workspaceId: process.env.FRONTDESK_WORKSPACE_ID!,
});

// Create the adapter that bridges Retell and FrontDeskOS
const adapter = createRetellAdapter(frontdesk, {
  // Select which tools the voice agent can use
  allowedTools: [
    "frontdesk_check_availability",
    "frontdesk_book_appointment",
    "frontdesk_reschedule_appointment",
    "frontdesk_cancel_appointment",
    "frontdesk_create_callback",
    "frontdesk_create_lead",
    "frontdesk_list_appointments",
  ],
});

// Create the Retell agent
const agent = await retell.agent.create({
  agent_name: "Riverside Dental Receptionist",
  voice_id: "sarah", // Natural female voice
  response_engine: {
    type: "retell-llm",
    llm_id: await createLLMConfig(),
  },
});

async function createLLMConfig() {
  const llm = await retell.llm.create({
    model: "gpt-4o",
    general_prompt: `You are the AI receptionist for Riverside Family Dental.
You are friendly, professional, and efficient. Your primary goals are:
1. Greet callers warmly and identify their needs
2. Schedule, reschedule, or cancel appointments
3. Answer questions about services and hours
4. Capture new patient information as leads
5. Transfer to a human when needed

Always confirm details before booking. Use the caller's name when known.`,
    general_tools: adapter.getToolDefinitions(),
  });
  return llm.llm_id;
}

import express from "express";
import { createRetellAdapter } from "@frontdeskos/retell-adapter";

const app = express();
app.use(express.json());

// Handle Retell function calls
app.post("/retell/webhook", async (req, res) => {
  const { function_name, arguments: args, call_id } = req.body;

  try {
    // The adapter translates Retell function calls to MCP tool calls
    const result = await adapter.handleFunctionCall(function_name, args, {
      callId: call_id,
    });

    res.json({
      response: result.content,
      // Tell Retell what to say based on the tool result
      speak: result.speakableResponse,
    });
  } catch (error: any) {
    res.json({
      response: { error: error.message },
      speak: "I apologize, I encountered an issue. Let me transfer you to someone who can help.",
    });
  }
});

// Handle call status changes
app.post("/retell/call-status", async (req, res) => {
  const { call_id, status, transcript } = req.body;

  if (status === "ended") {
    // After the call ends, create a call record in FrontDeskOS
    await adapter.handleCallEnded(call_id, {
      transcript,
      duration: req.body.duration_seconds,
    });
  }

  res.sendStatus(200);
});

app.listen(3001, () => {
  console.log("Retell webhook server running on port 3001");
});

// Option 1: Buy a number from Retell
const number = await retell.phoneNumber.create({
  agent_id: agent.agent_id,
  area_code: "503",
});

console.log("Your AI receptionist phone number:", number.phone_number);

// Option 2: Forward your existing Twilio number
await retell.phoneNumber.import({
  agent_id: agent.agent_id,
  phone_number: "+15035550100",
  twilio_account_sid: "AC...",
  twilio_auth_token: "...",
});

// Create a test call through the Retell API
const testCall = await retell.call.create({
  agent_id: agent.agent_id,
  from_number: "+15035550100",
  to_number: "+15035550199", // Your test number
});

console.log("Test call started:", testCall.call_id);
// Pick up your test phone and talk to your AI receptionist!

const adapter = createRetellAdapter(frontdesk, {
  transferConfig: {
    // When to offer human transfer
    triggers: [
      "caller requests human",
      "medical emergency mentioned",
      "complaint or escalation",
      "billing dispute",
    ],
    // Where to transfer
    targets: {
      default: "+15035550101", // Front desk
      emergency: "+15035550911", // On-call staff
      billing: "+15035550102",  // Billing department
    },
  },
});

const adapter = createRetellAdapter(frontdesk, {
  callerContext: {
    enabled: true,
    // Load the caller's history when a call starts
    contextFields: [
      "last_visit_date",
      "upcoming_appointments",
      "preferred_staff",
      "special_notes",
    ],
  },
});