callwright 1.0.0

package/setup-agent-from.js

@@ -0,0 +1,96 @@
+// Create a Retell agent from a prompt file and register it in agents.json.
+// Generalizes setup-agent.js so any scenario (or a generic agent) can be made.
+//
+//   node setup-agent-from.js <prompt-file> <agent_name> [call_type1,call_type2,...]
+//
+// Example (generic agent that handles appointment_booking + general_inquiry):
+//   node setup-agent-from.js generic-prompt.md generic appointment_booking,general_inquiry
+//
+// Env: RETELL_API_KEY  (no phone number needed)
+
+const fs = require("fs");
+
+const API_KEY = process.env.RETELL_API_KEY;
+if (!API_KEY) { console.error("Missing RETELL_API_KEY."); process.exit(1); }
+
+const promptFile = process.argv[2];
+const agentName = process.argv[3];
+const callTypes = (process.argv[4] || "").split(",").map(s => s.trim()).filter(Boolean);
+if (!promptFile || !agentName) {
+  console.error("Usage: node setup-agent-from.js <prompt-file> <agent_name> [call_type1,...]");
+  process.exit(1);
+}
+
+const VOICE_ID = process.env.RETELL_VOICE_ID || "11labs-Adrian";
+const AGENT_LANG = process.env.RETELL_AGENT_LANG || "en-US";
+const VOICE_MODEL = process.env.RETELL_VOICE_MODEL || null;
+const VOICEMAIL_TEXT = process.env.RETELL_VOICEMAIL_TEXT || "{{voicemail_message}}";
+const BASE = "https://api.retellai.com";
+
+function loadPrompt(file) {
+  const raw = fs.readFileSync(file, "utf8");
+  const cut = raw.indexOf("# ---");
+  return (cut > -1 ? raw.slice(0, cut) : raw).trim();
+}
+
+// Generic post-call analysis (scenario-agnostic).
+const postCallAnalysis = [
+  { type: "enum", name: "status",
+    description: "Final result of the call.",
+    choices: ["booked", "failed", "voicemail", "callback_needed", "escalated"] },
+  { type: "string", name: "booked_date", description: "Agreed date, or empty." },
+  { type: "string", name: "booked_time", description: "Agreed time, or empty." },
+  { type: "string", name: "confirmation_ref", description: "Any confirmation name/number." },
+  { type: "boolean", name: "accommodations_ok", description: "Were special requests accepted." },
+  { type: "string", name: "unmet_items", description: "Anything not achieved, or why it failed." },
+  { type: "string", name: "unanswered_questions",
+    description: "List any questions the business asked that the agent could NOT answer or had to defer to the principal (e.g. 'what type of haircut', 'preferred stylist'). Empty if none." },
+];
+
+async function api(path, body) {
+  const resp = await fetch(BASE + path, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const text = await resp.text();
+  if (!resp.ok) throw new Error(`${path} -> ${resp.status}\n${text}`);
+  return JSON.parse(text);
+}
+
+(async () => {
+  console.log(`Creating LLM from ${promptFile}...`);
+  const llm = await api("/create-retell-llm", {
+    general_prompt: loadPrompt(promptFile),
+    general_tools: [
+      { type: "end_call", name: "end_call", description: "End the call when done." },
+      { type: "press_digit", name: "press_digit",
+        description: "Press a keypad digit to navigate an automated phone menu (IVR). Use whenever a menu instructs you to press a number to reach a department or person.",
+        delay_ms: 1500 },
+    ],
+  });
+  console.log("  llm_id:", llm.llm_id);
+
+  console.log("Creating agent...");
+  const agentBody = {
+    response_engine: { type: "retell-llm", llm_id: llm.llm_id },
+    voice_id: VOICE_ID,
+    agent_name: agentName,
+    language: AGENT_LANG,
+    max_call_duration_ms: 300000,
+    interruption_sensitivity: 0.9,
+    voicemail_option: { action: { type: "static_text", text: VOICEMAIL_TEXT } },
+    post_call_analysis_data: postCallAnalysis,
+    webhook_events: ["call_started", "call_ended", "call_analyzed"],
+  };
+  if (VOICE_MODEL) agentBody.voice_model = VOICE_MODEL;
+  const agent = await api("/create-agent", agentBody);
+  console.log("  agent_id:", agent.agent_id);
+
+  // Register in agents.json for the given call types.
+  const reg = fs.existsSync("agents.json") ? JSON.parse(fs.readFileSync("agents.json", "utf8")) : {};
+  for (const ct of callTypes) reg[ct] = agent.agent_id;
+  fs.writeFileSync("agents.json", JSON.stringify(reg, null, 2));
+  console.log("\nRegistered in agents.json for:", callTypes.join(", ") || "(none)");
+  console.log(JSON.stringify(reg, null, 2));
+})().catch(e => { console.error("\nFailed:\n" + e.message); process.exit(1); });

package/setup-core.js

@@ -0,0 +1,299 @@
+// callwright — shared setup core (NON-interactive, reusable).
+//
+// Both the CLI wizard (init.js) and the future MCP server build on these.
+// Nothing here reads stdin or prints prompts, so it is safe to call from an
+// MCP tool handler (stdio-owned) as well as from the terminal wizard.
+//
+// Responsibilities:
+//   - verify a Retell API key (and list agents)
+//   - list phone numbers; resolve a from-number
+//   - reuse-or-create the generic agent
+//   - load/save config.json
+//   - report setup status / what's missing (for onboarding prompts)
+//   - set principal identity + facts (data the LLM gathered in chat)
+//   - guard: tell a caller (LLM) when setup is incomplete before place_call
+
+const fs = require("fs");
+const paths = require("./paths");
+
+const BASE = "https://api.retellai.com";
+const CONFIG_PATH = paths.CONFIG_PATH;
+const AGENTS_PATH = paths.AGENTS_PATH;
+const DEFAULT_PROMPT_FILE = "generic-prompt.md";
+
+// The webhook_url to bake into agents so Retell posts call_analyzed back to this
+// server for auto-learn. Returns null if no public URL is configured.
+function webhookUrl() {
+  const base = (process.env.CALLWRIGHT_PUBLIC_URL || "").replace(/\/+$/, "");
+  return base ? `${base}/webhook/retell` : null;
+}
+
+// Generic post-call analysis (single source of truth; init/setup-agent reuse).
+const POST_CALL_ANALYSIS = [
+  { type: "enum", name: "status", description: "Final result of the call.",
+    choices: ["booked", "failed", "voicemail", "callback_needed", "escalated"] },
+  { type: "string", name: "booked_date", description: "Agreed date, or empty." },
+  { type: "string", name: "booked_time", description: "Agreed time, or empty." },
+  { type: "string", name: "confirmation_ref", description: "Any confirmation name/number." },
+  { type: "boolean", name: "accommodations_ok", description: "Were special requests accepted." },
+  { type: "string", name: "unmet_items", description: "Anything not achieved, or why it failed." },
+  { type: "string", name: "unanswered_questions",
+    description: "List any questions the business asked that the agent could NOT answer or had to defer to the principal. Empty if none." },
+];
+
+// ---- low-level ----
+async function apiCall(key, method, path, body) {
+  const opts = { method, headers: { Authorization: `Bearer ${key}` } };
+  if (body) { opts.headers["Content-Type"] = "application/json"; opts.body = JSON.stringify(body); }
+  const resp = await fetch(BASE + path, opts);
+  const text = await resp.text();
+  if (!resp.ok) throw new Error(`${method} ${path} -> ${resp.status}\n${text}`);
+  return text ? JSON.parse(text) : {};
+}
+
+function loadJson(path, fallback) {
+  try { return JSON.parse(fs.readFileSync(path, "utf8")); } catch { return fallback; }
+}
+function loadConfig() {
+  const c = loadJson(CONFIG_PATH, {});
+  c.retell = c.retell || {};
+  c.agents = c.agents || {};
+  c.principal = c.principal || {};
+  return c;
+}
+function saveConfig(config) {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+  return config;
+}
+
+function loadPromptText(file = DEFAULT_PROMPT_FILE) {
+  // Volume-first: a runtime-added language's prompt persists on the volume and
+  // overrides the image; en/ja seeds ship in the image.
+  const raw = fs.readFileSync(paths.resolveAsset(file), "utf8");
+  const cut = raw.indexOf("# ---");
+  return (cut > -1 ? raw.slice(0, cut) : raw).trim();
+}
+
+// ---- Retell infra ----
+// List voice agents via the unified v2 endpoint (POST /v2/list-agents), reading
+// `items` and following pagination. Replaces the deprecated GET /list-agents
+// (removed 2026-07-31). The channel filter preserves the old voice-only behavior.
+async function listAgents(key) {
+  if (!key) throw new Error("No RETELL_API_KEY provided.");
+  const out = [];
+  let pageKey;
+  do {
+    const body = { filter_criteria: { channel: { type: "string", op: "eq", value: "voice" } } };
+    if (pageKey) body.pagination_key = pageKey;
+    const resp = await apiCall(key, "POST", "/v2/list-agents", body);
+    const items = Array.isArray(resp) ? resp : (resp.items || []);
+    out.push(...items);
+    pageKey = (!Array.isArray(resp) && resp.has_more) ? resp.pagination_key : null;
+  } while (pageKey);
+  return out;
+}
+
+// Verify a key by listing agents. Returns the agents array (throws if invalid).
+async function verifyKey(key) {
+  return listAgents(key);
+}
+
+async function listNumbers(key) {
+  // v2 returns unified pagination ({ items, has_more }); unwrap to an array.
+  const resp = await apiCall(key, "GET", "/v2/list-phone-numbers");
+  return Array.isArray(resp) ? resp : (resp.items || []);
+}
+
+// Auto-resolve a from-number: keep the preferred if still present; else if exactly
+// one exists use it; else return { needsChoice, numbers } so the caller can ask.
+async function resolveFromNumber(key, preferred) {
+  const numbers = await listNumbers(key);
+  const have = numbers.map((n) => n.phone_number);
+  if (preferred && have.includes(preferred)) return { from_number: preferred, numbers };
+  if (numbers.length === 1) return { from_number: have[0], numbers };
+  if (numbers.length === 0) return { from_number: null, numbers, needsChoice: true, reason: "no_numbers" };
+  return { from_number: null, numbers, needsChoice: true, reason: "multiple" };
+}
+
+// Reuse an existing generic agent or create one. Returns { agent_id, created }.
+async function ensureGenericAgent(key, { agents, defaultId, promptFile = DEFAULT_PROMPT_FILE, voiceId } = {}) {
+  agents = agents || (await verifyKey(key));
+  const lc = (a) => (a.agent_name || "").toLowerCase();
+  // Canonical English default is an agent named exactly "generic".
+  const exact = agents.find((a) => lc(a) === "generic");
+  // Honor an existing default ONLY if it's still valid AND not being shadowed by
+  // a canonical "generic" (self-heals a default mistakenly set to e.g. generic_ja).
+  if (defaultId && agents.some((a) => a.agent_id === defaultId)) {
+    if (!exact || defaultId === exact.agent_id) {
+      return { agent_id: defaultId, created: false, reused: true };
+    }
+  }
+  // Prefer exact English "generic"; avoid language-suffixed variants (generic_ja).
+  const byName =
+    exact ||
+    agents.find((a) => /generic/i.test(lc(a)) && !/_(ja|jp|es|fr|de|zh|ko|pt|it)$/i.test(lc(a))) ||
+    agents.find((a) => /generic/i.test(lc(a)));
+  if (byName) return { agent_id: byName.agent_id, created: false, reused: true, matchedByName: true };
+
+  const llm = await apiCall(key, "POST", "/create-retell-llm", {
+    general_prompt: loadPromptText(promptFile),
+    // Phone etiquette: wait for the callee to answer ("Hello?") before the agent
+    // introduces itself. begin_after_user_silence_ms is a fallback if they pick
+    // up silently (or an IVR doesn't greet) so we don't wait forever.
+    start_speaker: "user",
+    begin_message: "",
+    begin_after_user_silence_ms: 8000,
+    general_tools: [
+      { type: "end_call", name: "end_call", description: "End the call when done." },
+      { type: "press_digit", name: "press_digit",
+        description: "Press a keypad digit to navigate an automated phone menu (IVR).",
+        delay_ms: 1500 },
+    ],
+  });
+  const agent = await apiCall(key, "POST", "/create-agent", {
+    response_engine: { type: "retell-llm", llm_id: llm.llm_id },
+    voice_id: voiceId || process.env.RETELL_VOICE_ID || "11labs-Brian",
+    agent_name: "generic",
+    language: "en-US",
+    max_call_duration_ms: 600000,
+    interruption_sensitivity: 0.9,
+    voicemail_option: { action: { type: "static_text", text: "{{voicemail_message}}" } },
+    post_call_analysis_data: POST_CALL_ANALYSIS,
+    webhook_events: ["call_started", "call_ended", "call_analyzed"],
+    ...(webhookUrl() ? { webhook_url: webhookUrl() } : {}),
+  });
+  return { agent_id: agent.agent_id, created: true, llm_id: llm.llm_id };
+}
+
+// Detect language-variant generic agents by name convention "generic_<lang>"
+// (e.g. generic_ja -> { ja: agent_id }). Lets the MCP/CLI route lang -> agent.
+function detectLanguageAgents(agents) {
+  const out = {};
+  for (const a of agents || []) {
+    const m = (a.agent_name || "").toLowerCase().match(/^generic[_-]([a-z]{2,3})$/);
+    if (m) out[m[1]] = a.agent_id;
+  }
+  return out;
+}
+
+// Persist resolved infra into config + keep agents.json default in sync.
+function applyInfra(config, { from_number, agent_id, by_lang } = {}) {
+  if (from_number) config.retell.from_number = from_number;
+  if (agent_id) {
+    config.agents.default = agent_id;
+    const reg = loadJson(AGENTS_PATH, {});
+    reg.default = agent_id;
+    fs.writeFileSync(AGENTS_PATH, JSON.stringify(reg, null, 2));
+  }
+  if (by_lang && Object.keys(by_lang).length) {
+    config.agents.by_lang = { ...(config.agents.by_lang || {}), ...by_lang };
+  }
+  return config;
+}
+
+// ---- principal grounding ----
+// Merge identity + facts the LLM gathered (in chat) or the wizard collected.
+function setPrincipal(config, { name, callback_number, facts } = {}) {
+  config.principal = config.principal || {};
+  if (name != null) config.principal.name = name;
+  if (callback_number != null) config.principal.callback_number = callback_number;
+  if (facts && typeof facts === "object") {
+    config.principal.facts = { ...(config.principal.facts || {}), ...facts };
+  }
+  return config;
+}
+
+// Per-call values that are NOT durable identity — never suggest saving these to
+// the standing profile (they belong to a single call).
+const EPHEMERAL_FACT_KEYS = new Set([
+  "confirmation_number", "confirmation_ref", "confirmation", "booking_ref", "booking_number",
+  "reservation_number", "reservation_ref", "otp", "one_time_code", "verification_code", "code", "pin",
+]);
+
+// Lazy-save nudge: durable PII furnished for THIS call that the standing profile
+// doesn't already have, so the host LLM can offer to save it once (via configure)
+// instead of re-asking on every future call. Returns [{ key, type:'new'|'changed' }].
+// Excludes anonymous calls and obviously one-off values (confirmation numbers, OTPs).
+function unsavedDurableFacts(job, config = loadConfig()) {
+  const out = [];
+  const p = (job && job.principal) || {};
+  if (p.anonymous) return out;
+  const standing = (config && config.principal) || {};
+  const standingFacts = standing.facts || {};
+  if (p.name && !standing.name) out.push({ key: "name", type: "new" });
+  if (p.callback_number && !standing.callback_number) out.push({ key: "callback_number", type: "new" });
+  const facts = p.facts || {};
+  for (const [k, v] of Object.entries(facts)) {
+    if (v == null || v === "") continue;
+    if (EPHEMERAL_FACT_KEYS.has(String(k).toLowerCase())) continue;
+    const saved = standingFacts[k];
+    if (saved == null || saved === "") out.push({ key: k, type: "new" });
+    else if (String(saved) !== String(v)) out.push({ key: k, type: "changed" });
+  }
+  return out;
+}
+
+// ---- status / guard (drives onboarding prompts) ----
+// Report what's configured and what's missing, split by infra vs principal.
+function setupStatus(config = loadConfig()) {
+  const infraMissing = [];
+  if (!config.retell?.from_number) infraMissing.push("retell.from_number");
+  if (!(config.agents?.default)) infraMissing.push("agents.default");
+
+  const basicsMissing = [];
+  if (!config.principal?.name) basicsMissing.push("name");
+  if (!config.principal?.callback_number) basicsMissing.push("callback_number");
+
+  const factKeys = Object.keys(config.principal?.facts || {});
+  return {
+    infra_ready: infraMissing.length === 0,
+    basics_ready: basicsMissing.length === 0,
+    ready: infraMissing.length === 0 && basicsMissing.length === 0,
+    infra_missing: infraMissing,
+    basics_missing: basicsMissing,
+    have: {
+      from_number: config.retell?.from_number || null,
+      default_agent: config.agents?.default || null,
+      name: config.principal?.name || null,
+      callback_number: config.principal?.callback_number || null,
+      fact_keys: factKeys,
+    },
+  };
+}
+
+// Guard for place_call: returns null when OK, or a structured needs_setup object
+// instructing the host LLM how to onboard the user (ask basics, call configure).
+function guardPlaceCall(config = loadConfig()) {
+  const s = setupStatus(config);
+  if (s.ready) return null;
+  const missing = [...s.infra_missing, ...s.basics_missing];
+  const instructions = [];
+  if (!s.infra_ready) {
+    instructions.push(
+      "Infrastructure is not set up. Call run_provisioning (or have the user run `node init.js`) " +
+      "to verify the Retell key, select a phone number, and create the generic agent."
+    );
+  }
+  if (!s.basics_ready) {
+    instructions.push(
+      "Basic principal grounding is missing. Ask the user, in chat, for: " +
+      s.basics_missing.join(" and ") +
+      " (name is used when a call becomes a booking; callback_number is shared only if a business asks). " +
+      "Optionally offer to save a primary/service address. Then call configure with those values."
+    );
+  }
+  return {
+    needs_setup: true,
+    missing,
+    status: s,
+    instruction: instructions.join(" "),
+  };
+}
+
+module.exports = {
+  BASE, CONFIG_PATH, AGENTS_PATH, DEFAULT_PROMPT_FILE, POST_CALL_ANALYSIS,
+  apiCall, loadConfig, saveConfig, loadPromptText, webhookUrl,
+  verifyKey, listAgents, listNumbers, resolveFromNumber, ensureGenericAgent, applyInfra,
+  detectLanguageAgents, setPrincipal, setupStatus, guardPlaceCall,
+  unsavedDurableFacts,
+};

package/update-prompt.js

@@ -0,0 +1,98 @@
+// Update an existing Retell agent's LLM prompt from a prompt file.
+//   node update-prompt.js <agent_id> <prompt-file>
+// Env: RETELL_API_KEY
+const fs = require("fs");
+const API_KEY = process.env.RETELL_API_KEY;
+if (!API_KEY) { console.error("Missing RETELL_API_KEY."); process.exit(1); }
+
+const agentId = process.argv[2];
+const promptFile = process.argv[3];
+if (!agentId || !promptFile) {
+  console.error("Usage: node update-prompt.js <agent_id> <prompt-file>");
+  process.exit(1);
+}
+const BASE = "https://api.retellai.com";
+
+function loadPrompt(file) {
+  const raw = fs.readFileSync(file, "utf8");
+  const cut = raw.indexOf("# ---");
+  return (cut > -1 ? raw.slice(0, cut) : raw).trim();
+}
+
+async function get(path) {
+  const resp = await fetch(BASE + path, {
+    headers: { Authorization: `Bearer ${API_KEY}` },
+  });
+  const text = await resp.text();
+  if (!resp.ok) throw new Error(`${path} -> ${resp.status}\n${text}`);
+  return JSON.parse(text);
+}
+
+async function patch(path, body) {
+  const resp = await fetch(BASE + path, {
+    method: "PATCH",
+    headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const text = await resp.text();
+  if (!resp.ok) throw new Error(`${path} -> ${resp.status}\n${text}`);
+  return JSON.parse(text);
+}
+
+(async () => {
+  const agent = await get(`/get-agent/${agentId}`);
+  const llmId = agent.response_engine?.llm_id;
+  if (!llmId) throw new Error("Agent has no retell-llm engine; cannot update prompt.");
+  console.log("agent:", agentId, "-> llm:", llmId);
+
+  // Preserve existing tools; ensure a press_digit tool exists for IVR navigation.
+  const llm = await get(`/get-retell-llm/${llmId}`);
+  const tools = Array.isArray(llm.general_tools) ? llm.general_tools.slice() : [];
+  if (!tools.some(t => t.type === "press_digit")) {
+    tools.push({
+      type: "press_digit",
+      name: "press_digit",
+      description: "Press a keypad digit to navigate an automated phone menu (IVR). Use whenever a menu instructs you to press a number to reach a department or person.",
+      delay_ms: 1500,
+    });
+    console.log("  + added press_digit tool");
+  }
+  if (!tools.some(t => t.type === "end_call")) {
+    tools.push({ type: "end_call", name: "end_call", description: "End the call when done." });
+  }
+
+  await patch(`/update-retell-llm/${llmId}`, {
+    general_prompt: loadPrompt(promptFile),
+    general_tools: tools,
+    // Phone etiquette: wait for the callee to answer before introducing.
+    start_speaker: "user",
+    begin_message: "",
+    begin_after_user_silence_ms: 8000,
+  });
+  console.log("✅ Prompt + tools + etiquette updated from", promptFile);
+  console.log("   tools:", tools.map(t => t.type).join(", "));
+
+  // Ensure the agent leaves a CONTEXTFUL voicemail (who + why + callback),
+  // driven by the per-call {{voicemail_message}} dynamic variable.
+  const vmText = "{{voicemail_message}}";
+  const currentVm = agent.voicemail_option?.action?.text;
+  if (currentVm !== vmText) {
+    await patch(`/update-agent/${agentId}`, {
+      voicemail_option: { action: { type: "static_text", text: vmText } },
+    });
+    console.log("✅ Voicemail set to contextful {{voicemail_message}}");
+  }
+
+  // Point the agent's webhook at this server (auto-learn) if a public URL is set.
+  const base = (process.env.CALLWRIGHT_PUBLIC_URL || "").replace(/\/+$/, "");
+  if (base) {
+    const url = `${base}/webhook/retell`;
+    if (agent.webhook_url !== url) {
+      await patch(`/update-agent/${agentId}`, {
+        webhook_url: url,
+        webhook_events: ["call_started", "call_ended", "call_analyzed"],
+      });
+      console.log("✅ webhook_url set ->", url);
+    }
+  }
+})().catch(e => { console.error("\nFailed:\n" + e.message); process.exit(1); });

package/webhook/README.md

@@ -0,0 +1,104 @@
+# Retell Webhook → Resend Email Notifier
+
+**Serverless**, scale-to-zero webhook handler. Runs ONLY when Retell posts a completed call, then emails you a status summary. No always-on server, no database.
+
+## What it does
+
+When a call completes:
+- Retell fires `call_analyzed` webhook → this function
+- Verifies signature, extracts outcome (status, booking details, reply, transcript)
+- Emails you a formatted summary via Resend
+
+Email looks like:
+```
+✅ [booked] Eclips Salon & Day Spa — Haircut appointment
+
+The agent successfully booked a men's haircut for Phil at 10:30 AM on Saturday, July 18th.
+
+Status          booked
+Business        Eclips Salon & Day Spa
+Booked date     Saturday, July 18th
+Booked time     10:30 AM
+Duration        50s
+Call ID         call_d8cc81394abc94ab43ac3518eed
+
+[Transcript]
+Agent: Hi, I'm an AI assistant calling on behalf of Phil...
+```
+
+## Deploy to Vercel (one-time, 2 minutes)
+
+### 1. Push this folder to a Git repo
+```bash
+cd webhook
+git init
+git add .
+git commit -m "retell webhook handler"
+# push to GitHub/GitLab
+```
+
+### 2. Import to Vercel
+- Go to [vercel.com/new](https://vercel.com/new)
+- Import your repo
+- Root directory: `webhook`
+- Framework preset: Other
+
+### 3. Set environment variables (in Vercel project settings)
+```
+RETELL_API_KEY   = key_xxx...       # from Retell dashboard
+RESEND_API_KEY   = re_xxx...        # from resend.com
+EMAIL_FROM       = calls@yourdomain.com   # must be verified in Resend
+EMAIL_TO         = you@example.com
+```
+
+### 4. Deploy
+Vercel auto-deploys. You'll get a URL like:
+```
+https://virtuphil-webhook.vercel.app/api/retell-webhook
+```
+
+### 5. Register the webhook with Retell
+
+**Option A: Account-level (all agents)**
+- Go to Retell dashboard → Settings → Webhooks
+- Paste your Vercel URL
+- Save
+
+**Option B: Per-agent (selective)**
+Use `update-postcall.js` or the setup scripts with `webhook_url`:
+```javascript
+// in setup-agent-from.js, add before api("/create-agent"):
+const WEBHOOK_URL = process.env.WEBHOOK_URL || null;
+// then in the agent body:
+webhook_url: WEBHOOK_URL,
+```
+
+## Test it
+
+Place a call (any of your existing scripts), wait ~30s for analysis, check your inbox.
+
+## Cost
+
+- **Vercel**: free tier = 100GB-hrs/mo (plenty for webhook spikes)
+- **Resend**: free tier = 3,000 emails/mo
+- **Total**: $0 unless you place thousands of calls/month
+
+## Local testing (optional)
+
+```bash
+npm install
+# mock a Retell payload
+node -e "
+const h = require('./api/retell-webhook.js');
+const call = {
+  call_id: 'test',
+  retell_llm_dynamic_variables: { business_name: 'Test Co', objective: 'test' },
+  call_analysis: { call_successful: true, custom_analysis_data: { status: 'booked' } }
+};
+console.log(h.buildEmail(call));
+"
+```
+
+---
+
+Once deployed, you have **optional proactive email** on every call — but the MCP server still works standalone (pull-on-demand from Retell when you ask in chat). Best of both.