feat: add in-browser dial pad with Twilio Voice SDK

- New DialPad component on Patient Connection page: clickable keypad,
  call/hangup/mute buttons, duration timer, keyboard input support
- Backend: POST /api/twilio/voice-token issues Access Token for browser
  Device; POST /api/twilio/webhook/voice-browser is the TwiML webhook
  Twilio calls to bridge the browser to the patient's phone
- TwiML App SID field added to Twilio Settings (stored in templates JSON)
- README: one-time Twilio Console setup instructions for the dial pad

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -390,6 +390,25 @@ Each office runs its own `cloudflared` tunnel on its own PC. Ports never conflic
 
 ---
 
+## Twilio In-Browser Calling Setup (Dial Pad)
+
+The dial pad on the Patient Connection page lets staff make real phone calls directly through the browser (mic + speaker) using Twilio Voice SDK. One-time setup is required in the Twilio Console.
+
+### One-time Twilio Console setup (required before first call)
+
+1. Go to **Twilio Console → Explore Products → Voice → TwiML Apps**
+2. Click **Create new TwiML App**
+3. Set the **Voice Request URL** to:
+   ```
+   https://communitydentistsoflowell.mydentalofficemanagement.com/api/twilio/webhook/voice-browser
+   ```
+4. Save — copy the **TwiML App SID** (starts with `AP`)
+5. In the dental app, go to **Settings → Twilio Settings → TwiML App SID** → paste the SID and save
+
+Once saved, the dial pad on the Patient Connection page is fully functional. The staff member's browser mic/speaker is used for the call; the patient receives a normal phone call from the office Twilio number.
+
+---
+
 ## License Key Generator
 
 The license key generator is a private tool that lives only on your dev PC. Use it to generate a new license key for any office every 3 months.

apps/Backend/src/routes/twilio-webhooks.ts

@@ -1203,4 +1203,26 @@ router.post("/webhook/voice-recording", async (req: Request, res: Response): Pro
   }
 });
 
+// POST /api/twilio/webhook/voice-browser
+// Called by Twilio when a browser Device (Voice SDK) places an outbound call.
+// Looks up the office's Twilio phone number by AccountSid and dials the patient.
+router.post("/webhook/voice-browser", async (req: Request, res: Response): Promise<any> => {
+  try {
+    const { To, AccountSid } = req.body as { To?: string; AccountSid?: string };
+    if (!To || !AccountSid) {
+      res.set("Content-Type", "text/xml");
+      return res.send("<Response><Say>Missing call parameters.</Say></Response>");
+    }
+    const settings = await db.twilioSettings.findFirst({ where: { accountSid: AccountSid } });
+    const callerId = settings?.phoneNumber || "";
+    res.set("Content-Type", "text/xml");
+    return res.send(
+      `<Response><Dial callerId="${escapeXml(callerId)}"><Number>${escapeXml(To)}</Number></Dial></Response>`
+    );
+  } catch {
+    res.set("Content-Type", "text/xml");
+    return res.send("<Response><Say>An error occurred. Please try again.</Say></Response>");
+  }
+});
+
 export default router;

apps/Backend/src/routes/twilio.ts

@@ -19,12 +19,14 @@ router.get("/settings", async (req: Request, res: Response): Promise<any> => {
     const settings = await storage.getTwilioSettings(userId);
     if (!settings) return res.status(200).json(null);
 
+    const templates = (settings.templates as Record<string, string>) || {};
     return res.status(200).json({
       id: settings.id,
       accountSid: settings.accountSid,
       authToken: settings.authToken,
       phoneNumber: settings.phoneNumber,
       greetingMessage: settings.greetingMessage,
+      twimlAppSid: templates["_twiml_app_sid"] || null,
     });
   } catch (err) {
     return res.status(500).json({ error: "Failed to fetch Twilio settings", details: String(err) });
@@ -37,7 +39,7 @@ router.put("/settings", async (req: Request, res: Response): Promise<any> => {
     const userId = req.user?.id;
     if (!userId) return res.status(401).json({ message: "Unauthorized" });
 
-    const { accountSid, authToken, phoneNumber, greetingMessage } = req.body;
+    const { accountSid, authToken, phoneNumber, greetingMessage, twimlAppSid } = req.body;
     if (!accountSid?.trim() || !authToken?.trim() || !phoneNumber?.trim()) {
       return res.status(400).json({ message: "accountSid, authToken, and phoneNumber are required" });
     }
@@ -47,14 +49,17 @@ router.put("/settings", async (req: Request, res: Response): Promise<any> => {
       authToken: authToken.trim(),
       phoneNumber: phoneNumber.trim(),
       greetingMessage: greetingMessage?.trim() || null,
+      twimlAppSid: twimlAppSid?.trim() || null,
     });
 
+    const templates = (settings.templates as Record<string, string>) || {};
     return res.status(200).json({
       id: settings.id,
       accountSid: settings.accountSid,
       authToken: settings.authToken,
       phoneNumber: settings.phoneNumber,
       greetingMessage: settings.greetingMessage,
+      twimlAppSid: templates["_twiml_app_sid"] || null,
     });
   } catch (err) {
     return res.status(500).json({ error: "Failed to save Twilio settings", details: String(err) });
@@ -469,6 +474,42 @@ router.get("/recent-communications", async (req: Request, res: Response): Promis
   }
 });
 
+// POST /api/twilio/voice-token
+// Returns a short-lived Twilio Access Token so the browser Voice SDK can place calls.
+router.post("/voice-token", async (req: Request, res: Response): Promise<any> => {
+  try {
+    const userId = req.user?.id;
+    if (!userId) return res.status(401).json({ message: "Unauthorized" });
+
+    const settings = await storage.getTwilioSettings(userId);
+    if (!settings) {
+      return res.status(400).json({ message: "Twilio is not configured. Please add your Twilio credentials in Settings." });
+    }
+
+    const templates = (settings.templates as Record<string, string>) || {};
+    const twimlAppSid = templates["_twiml_app_sid"]?.trim();
+    if (!twimlAppSid) {
+      return res.status(400).json({ message: "TwiML App SID is not configured. Please add it in Twilio Settings." });
+    }
+
+    const AccessToken = twilio.jwt.AccessToken;
+    const VoiceGrant = AccessToken.VoiceGrant;
+
+    const token = new AccessToken(
+      settings.accountSid,
+      settings.accountSid,
+      settings.authToken,
+      { identity: `user-${userId}`, ttl: 3600 }
+    );
+    const voiceGrant = new VoiceGrant({ outgoingApplicationSid: twimlAppSid, incomingAllow: false });
+    token.addGrant(voiceGrant);
+
+    return res.status(200).json({ token: token.toJwt(), phoneNumber: settings.phoneNumber });
+  } catch (err: any) {
+    return res.status(500).json({ error: err.message || "Failed to generate voice token" });
+  }
+});
+
 // POST /api/twilio/make-call
 router.post("/make-call", async (req: Request, res: Response): Promise<any> => {
   try {

apps/Backend/src/storage/twilio-storage.ts

@@ -5,6 +5,7 @@ export type TwilioSettingsData = {
   authToken: string;
   phoneNumber: string;
   greetingMessage?: string | null;
+  twimlAppSid?: string | null;
 };
 
 export type CommunicationCreateData = {
@@ -24,10 +25,18 @@ export const twilioStorage = {
   },
 
   async upsertTwilioSettings(userId: number, data: TwilioSettingsData) {
+    const { twimlAppSid, ...rest } = data;
+    const existing = await db.twilioSettings.findUnique({ where: { userId } });
+    const existingTemplates = (existing?.templates as Record<string, string>) || {};
+    const templates: Record<string, string> = { ...existingTemplates };
+    if (twimlAppSid !== undefined) {
+      if (twimlAppSid) templates["_twiml_app_sid"] = twimlAppSid;
+      else delete templates["_twiml_app_sid"];
+    }
     return db.twilioSettings.upsert({
       where: { userId },
-      update: data,
+      update: { ...rest, templates },
-      create: { userId, ...data },
+      create: { userId, ...rest, templates },
     });
   },
 

apps/Frontend/package.json

@@ -48,6 +48,7 @@
     "@tailwindcss/vite": "^4.1.6",
     "@tanstack/react-query": "^5.60.5",
     "@tanstack/react-table": "^8.21.3",
+    "@twilio/voice-sdk": "^2.18.3",
     "autoprefixer": "^10.4.20",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

apps/Frontend/src/components/patient-connection/dial-pad.tsx

@@ -0,0 +1,246 @@
+import { useState, useEffect, useRef, useCallback } from "react";
+import { Device, Call } from "@twilio/voice-sdk";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { Phone, PhoneOff, Mic, MicOff, Delete } from "lucide-react";
+import { useToast } from "@/hooks/use-toast";
+import { apiRequest } from "@/lib/queryClient";
+
+type CallStatus = "idle" | "requesting-token" | "connecting" | "connected" | "error";
+
+const KEYS = [
+  ["1", "2", "3"],
+  ["4", "5", "6"],
+  ["7", "8", "9"],
+  ["*", "0", "#"],
+];
+
+function formatDuration(seconds: number): string {
+  const m = Math.floor(seconds / 60).toString().padStart(2, "0");
+  const s = (seconds % 60).toString().padStart(2, "0");
+  return `${m}:${s}`;
+}
+
+export function DialPad() {
+  const [dialedNumber, setDialedNumber] = useState("");
+  const [status, setStatus] = useState<CallStatus>("idle");
+  const [isMuted, setIsMuted] = useState(false);
+  const [duration, setDuration] = useState(0);
+  const { toast } = useToast();
+
+  const deviceRef = useRef<Device | null>(null);
+  const callRef = useRef<Call | null>(null);
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const stopTimer = useCallback(() => {
+    if (timerRef.current) {
+      clearInterval(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  const destroyDevice = useCallback(() => {
+    callRef.current?.disconnect();
+    callRef.current = null;
+    deviceRef.current?.destroy();
+    deviceRef.current = null;
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      stopTimer();
+      destroyDevice();
+    };
+  }, [stopTimer, destroyDevice]);
+
+  // Keyboard input support
+  useEffect(() => {
+    const handleKey = (e: KeyboardEvent) => {
+      if (status !== "idle") return;
+      const valid = "0123456789*#";
+      if (valid.includes(e.key)) {
+        setDialedNumber((n) => (n.length < 16 ? n + e.key : n));
+      } else if (e.key === "Backspace") {
+        setDialedNumber((n) => n.slice(0, -1));
+      }
+    };
+    window.addEventListener("keydown", handleKey);
+    return () => window.removeEventListener("keydown", handleKey);
+  }, [status]);
+
+  const pressKey = (key: string) => {
+    if (status !== "idle") return;
+    setDialedNumber((n) => (n.length < 16 ? n + key : n));
+  };
+
+  const handleBackspace = () => {
+    if (status !== "idle") return;
+    setDialedNumber((n) => n.slice(0, -1));
+  };
+
+  const handleCall = async () => {
+    if (!dialedNumber.trim()) {
+      toast({ title: "Enter a number", description: "Please dial a phone number first.", variant: "destructive" });
+      return;
+    }
+
+    setStatus("requesting-token");
+    setDuration(0);
+    setIsMuted(false);
+
+    try {
+      const res = await apiRequest("POST", "/api/twilio/voice-token");
+      if (!res.ok) {
+        const err = await res.json().catch(() => null);
+        throw new Error(err?.message || "Failed to get voice token");
+      }
+      const { token } = await res.json();
+
+      const device = new Device(token, { logLevel: "error" });
+      deviceRef.current = device;
+
+      await device.register();
+      setStatus("connecting");
+
+      // Normalize to E.164 if it looks like a 10-digit US number
+      let toNumber = dialedNumber.replace(/\D/g, "");
+      if (toNumber.length === 10) toNumber = "+1" + toNumber;
+      else if (!toNumber.startsWith("+")) toNumber = "+" + toNumber;
+
+      const call = await device.connect({ params: { To: toNumber } });
+      callRef.current = call;
+
+      call.on("accept", () => {
+        setStatus("connected");
+        timerRef.current = setInterval(() => setDuration((d) => d + 1), 1000);
+      });
+
+      call.on("disconnect", () => {
+        stopTimer();
+        destroyDevice();
+        setStatus("idle");
+        setDuration(0);
+        setIsMuted(false);
+      });
+
+      call.on("error", (err: any) => {
+        stopTimer();
+        destroyDevice();
+        setStatus("error");
+        toast({ title: "Call Error", description: err?.message || "Call failed.", variant: "destructive" });
+        setTimeout(() => setStatus("idle"), 3000);
+      });
+    } catch (err: any) {
+      destroyDevice();
+      setStatus("error");
+      toast({ title: "Call Failed", description: err?.message || "Unable to place call.", variant: "destructive" });
+      setTimeout(() => setStatus("idle"), 3000);
+    }
+  };
+
+  const handleHangup = () => {
+    callRef.current?.disconnect();
+  };
+
+  const handleMute = () => {
+    if (!callRef.current) return;
+    const next = !isMuted;
+    callRef.current.mute(next);
+    setIsMuted(next);
+  };
+
+  const statusLabel: Record<CallStatus, string> = {
+    idle: "Ready",
+    "requesting-token": "Initializing...",
+    connecting: "Connecting...",
+    connected: `In Call  ${formatDuration(duration)}`,
+    error: "Error",
+  };
+
+  const statusColor: Record<CallStatus, string> = {
+    idle: "text-muted-foreground",
+    "requesting-token": "text-amber-500",
+    connecting: "text-amber-500",
+    connected: "text-green-600",
+    error: "text-red-500",
+  };
+
+  const isInCall = status === "connected" || status === "connecting";
+  const isBusy = status === "requesting-token" || status === "connecting";
+
+  return (
+    <Card>
+      <CardHeader className="pb-3">
+        <CardTitle className="text-base flex items-center gap-2">
+          <Phone className="h-4 w-4" />
+          Dial Pad
+        </CardTitle>
+      </CardHeader>
+      <CardContent>
+        <div className="flex flex-col items-center gap-3 max-w-xs mx-auto">
+          {/* Number display */}
+          <div className="w-full flex items-center gap-2 px-3 py-2 border rounded-lg bg-gray-50 min-h-[42px]">
+            <span className="flex-1 font-mono text-lg tracking-widest text-center">
+              {dialedNumber || <span className="text-muted-foreground text-sm">Enter number</span>}
+            </span>
+            {dialedNumber && status === "idle" && (
+              <button onClick={handleBackspace} className="text-muted-foreground hover:text-foreground">
+                <Delete className="h-4 w-4" />
+              </button>
+            )}
+          </div>
+
+          {/* Keypad */}
+          <div className="grid grid-cols-3 gap-2 w-full">
+            {KEYS.flat().map((key) => (
+              <button
+                key={key}
+                onClick={() => pressKey(key)}
+                disabled={isInCall || isBusy}
+                className="h-12 rounded-lg border bg-white text-lg font-medium hover:bg-gray-50 active:bg-gray-100 disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
+              >
+                {key}
+              </button>
+            ))}
+          </div>
+
+          {/* Call / Hangup */}
+          <div className="flex gap-3 w-full">
+            {!isInCall ? (
+              <Button
+                className="flex-1 bg-green-600 hover:bg-green-700 text-white"
+                onClick={handleCall}
+                disabled={isBusy || !dialedNumber.trim()}
+              >
+                <Phone className="h-4 w-4 mr-2" />
+                Call
+              </Button>
+            ) : (
+              <>
+                <Button
+                  variant="outline"
+                  onClick={handleMute}
+                  className={isMuted ? "border-red-300 text-red-600" : ""}
+                >
+                  {isMuted ? <MicOff className="h-4 w-4" /> : <Mic className="h-4 w-4" />}
+                </Button>
+                <Button
+                  className="flex-1 bg-red-600 hover:bg-red-700 text-white"
+                  onClick={handleHangup}
+                >
+                  <PhoneOff className="h-4 w-4 mr-2" />
+                  Hang Up
+                </Button>
+              </>
+            )}
+          </div>
+
+          {/* Status */}
+          <p className={`text-sm font-medium ${statusColor[status]}`}>
+            {statusLabel[status]}
+          </p>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

apps/Frontend/src/components/settings/twilio-settings-card.tsx

@@ -11,6 +11,7 @@ type TwilioSettings = {
   authToken: string;
   phoneNumber: string;
   greetingMessage?: string | null;
+  twimlAppSid?: string | null;
 };
 
 export function TwilioSettingsCard() {
@@ -19,6 +20,7 @@ export function TwilioSettingsCard() {
   const [authToken, setAuthToken] = useState("");
   const [phoneNumber, setPhoneNumber] = useState("");
   const [greetingMessage, setGreetingMessage] = useState("");
+  const [twimlAppSid, setTwimlAppSid] = useState("");
   const [showAuthToken, setShowAuthToken] = useState(false);
 
   const { data: settings, isLoading } = useQuery<TwilioSettings | null>({
@@ -36,6 +38,7 @@ export function TwilioSettingsCard() {
       setAuthToken(settings.authToken ?? "");
       setPhoneNumber(settings.phoneNumber ?? "");
       setGreetingMessage(settings.greetingMessage ?? "");
+      setTwimlAppSid(settings.twimlAppSid ?? "");
     }
   }, [settings]);
 
@@ -60,7 +63,7 @@ export function TwilioSettingsCard() {
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
     if (!accountSid.trim() || !authToken.trim() || !phoneNumber.trim()) return;
-    saveMutation.mutate({ accountSid: accountSid.trim(), authToken: authToken.trim(), phoneNumber: phoneNumber.trim(), greetingMessage: greetingMessage.trim() || null });
+    saveMutation.mutate({ accountSid: accountSid.trim(), authToken: authToken.trim(), phoneNumber: phoneNumber.trim(), greetingMessage: greetingMessage.trim() || null, twimlAppSid: twimlAppSid.trim() || null });
   };
 
   const isConfigured = !!(settings?.accountSid && settings?.authToken && settings?.phoneNumber);
@@ -144,6 +147,22 @@ export function TwilioSettingsCard() {
               <p className="text-xs text-gray-500 mt-1">This message plays when a patient calls your Twilio number. Leave blank to use the default.</p>
             </div>
 
+            <div>
+              <label className="block text-sm font-medium">TwiML App SID <span className="text-gray-400 font-normal">(for in-browser calling)</span></label>
+              <input
+                type="text"
+                value={twimlAppSid}
+                onChange={(e) => setTwimlAppSid(e.target.value)}
+                className="mt-1 p-2 border rounded w-full font-mono text-sm"
+                placeholder="APxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+              />
+              <p className="text-xs text-gray-500 mt-1">
+                In Twilio Console → TwiML Apps → create one → set Voice URL to{" "}
+                <code className="bg-gray-100 px-1 rounded text-xs">https://communitydentistsoflowell.mydentalofficemanagement.com/api/twilio/webhook/voice-browser</code>
+                {" "}then paste the App SID here. Required for the dial pad.
+              </p>
+            </div>
+
             <div className="flex items-center gap-3 pt-1">
               <button
                 type="submit"

apps/Frontend/src/pages/patient-connection-page.tsx

@@ -27,6 +27,7 @@ import {
 } from "lucide-react";
 import { SmsTemplateDialog } from "@/components/patient-connection/sms-template-diaog";
 import { MessageThread } from "@/components/patient-connection/message-thread";
+import { DialPad } from "@/components/patient-connection/dial-pad";
 import { useToast } from "@/hooks/use-toast";
 import { apiRequest } from "@/lib/queryClient";
 import type { Patient } from "@repo/db/types";
@@ -374,6 +375,11 @@ export default function PatientConnectionPage() {
         </CardContent>
       </Card>
 
+      {/* Dial Pad */}
+      <div className="mt-6 max-w-xs">
+        <DialPad />
+      </div>
+
       {/* SMS Template Dialog */}
       <SmsTemplateDialog
         open={isSmsDialogOpen}

package-lock.json

@@ -120,6 +120,7 @@
         "@tailwindcss/vite": "^4.1.6",
         "@tanstack/react-query": "^5.60.5",
         "@tanstack/react-table": "^8.21.3",
+        "@twilio/voice-sdk": "^2.18.3",
         "autoprefixer": "^10.4.20",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
@@ -4700,6 +4701,28 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@twilio/voice-errors": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/@twilio/voice-errors/-/voice-errors-1.7.0.tgz",
+      "integrity": "sha512-9TvniWpzU0iy6SYFAcDP+HG+/mNz2yAHSs7+m0DZk86lE+LoTB6J/ZONTPuxXrXWi4tso/DulSHuA0w7nIQtGg==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@twilio/voice-sdk": {
+      "version": "2.18.3",
+      "resolved": "https://registry.npmjs.org/@twilio/voice-sdk/-/voice-sdk-2.18.3.tgz",
+      "integrity": "sha512-sBa9Tw+aXVIqDVnFQXIoY+yZM8GI8v/fwt34EMElSUfvlb8kquDOwLv6wXrBOwSYrnlyJoUqjlAOWdFPizEBnw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@twilio/voice-errors": "1.7.0",
+        "@types/events": "3.0.3",
+        "events": "3.3.0",
+        "loglevel": "1.9.2",
+        "tslib": "2.8.1"
+      },
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/@types/archiver": {
       "version": "6.0.4",
       "resolved": "https://registry.npmjs.org/@types/archiver/-/archiver-6.0.4.tgz",
@@ -4862,6 +4885,12 @@
       "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
       "license": "MIT"
     },
+    "node_modules/@types/events": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@types/events/-/events-3.0.3.tgz",
+      "integrity": "sha512-trOc4AAUThEz9hapPtSd7wf5tiQKvTtu5b371UxXdTuqzIh0ArcRspRP0i0Viu+LXstIQ1z96t1nsPxT9ol01g==",
+      "license": "MIT"
+    },
     "node_modules/@types/express": {
       "version": "5.0.6",
       "resolved": "https://registry.npmjs.org/@types/express/-/express-5.0.6.tgz",
@@ -9634,6 +9663,19 @@
       "integrity": "sha512-Sb487aTOCr9drQVL8pIxOzVhafOjZN9UU54hiN8PU3uAiSV7lx1yYNpbNmex2PK6dSJoNTSJUUswT651yww3Mg==",
       "license": "MIT"
     },
+    "node_modules/loglevel": {
+      "version": "1.9.2",
+      "resolved": "https://registry.npmjs.org/loglevel/-/loglevel-1.9.2.tgz",
+      "integrity": "sha512-HgMmCqIJSAKqo68l0rS2AanEWfkxaZ5wNiEFb5ggm08lDs9Xl2KxBlX3PTcaD2chBM1gXAYf491/M2Rv8Jwayg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6.0"
+      },
+      "funding": {
+        "type": "tidelift",
+        "url": "https://tidelift.com/funding/github/npm/loglevel"
+      }
+    },
     "node_modules/long": {
       "version": "5.3.2",
       "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",