████████╗██╗    ██╗██╗██╗     ██╗ ██████╗
╚══██╔══╝██║    ██║██║██║     ██║██╔═══██╗
   ██║   ██║ █╗ ██║██║██║     ██║██║   ██║
   ██║   ██║███╗██║██║██║     ██║██║   ██║
   ██║   ╚███╔███╔╝██║███████╗██║╚██████╔╝
   ╚═╝    ╚══╝╚══╝ ╚═╝╚══════╝╚═╝ ╚═════╝

npm install twilio

// lib/twilio.ts
import twilio from "twilio";

export const client = twilio(
  process.env.TWILIO_ACCOUNT_SID!,
  process.env.TWILIO_AUTH_TOKEN!, // server-side only — never ship to the browser
);

import { client } from "@/lib/twilio";

export async function sendSms(to: string, body: string) {
  const message = await client.messages.create({
    to,                               // E.164, e.g. "+15619991234"
    from: process.env.TWILIO_PHONE_NUMBER!, // a Twilio number you own, or use messagingServiceSid
    body,
  });
  return message.sid; // "SM…" — accepted; final state arrives via the status webhook
}

await client.messages.create({
  to: "+15619991234",
  messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID!, // "MG…"
  body: "Your codeAmani appointment is confirmed for Tue 10:00 AM.",
  statusCallback: "https://app.example.com/api/twilio/status", // queued → sent → delivered
});

// lib/verify.ts
import { client } from "@/lib/twilio";

const SERVICE = process.env.TWILIO_VERIFY_SERVICE_SID!; // "VA…"

/** Start: send a code over SMS (or "call", "whatsapp", "email"). */
export async function startVerification(to: string) {
  const v = await client.verify.v2
    .services(SERVICE)
    .verifications.create({ to, channel: "sms" });
  return v.status; // "pending"
}

/** Check: verify the code the user entered. */
export async function checkVerification(to: string, code: string) {
  const check = await client.verify.v2
    .services(SERVICE)
    .verificationChecks.create({ to, code });
  return check.status === "approved"; // else: pending | canceled | max_attempts_reached | failed | expired
}

// app/api/verify/start/route.ts
import { NextResponse } from "next/server";
import { startVerification } from "@/lib/verify";

export async function POST(req: Request) {
  const { phone } = await req.json();
  await startVerification(phone);
  return NextResponse.json({ ok: true });
}

// app/api/verify/check/route.ts
import { NextResponse } from "next/server";
import { checkVerification } from "@/lib/verify";

export async function POST(req: Request) {
  const { phone, code } = await req.json();
  const approved = await checkVerification(phone, code);
  if (!approved) return NextResponse.json({ ok: false }, { status: 401 });
  // approved → mint your session / mark the phone verified
  return NextResponse.json({ ok: true });
}

const call = await client.calls.create({
  to: "+15619991234",
  from: process.env.TWILIO_PHONE_NUMBER!,
  twiml: "<Response><Say voice=\"Polly.Joanna\">This is a codeAmani appointment reminder.</Say></Response>",
});
return call.sid; // "CA…"

import twilio from "twilio";

const vr = new twilio.twiml.VoiceResponse();
const gather = vr.gather({ numDigits: 1, action: "/api/twilio/voice/handle", method: "POST" });
gather.say("Press 1 for appointments, 2 for billing.");
// res.type("text/xml").send(vr.toString());

// lib/twilio-webhook.ts  — framework-agnostic verification
import twilio from "twilio";

export function isValidTwilioRequest(
  signature: string,
  url: string,                       // the EXACT public URL Twilio called (incl. https + path + query)
  params: Record<string, string>,    // parsed application/x-www-form-urlencoded body
): boolean {
  return twilio.validateRequest(process.env.TWILIO_AUTH_TOKEN!, signature, url, params);
}

// app/api/twilio/inbound/route.ts
import { NextResponse } from "next/server";
import { isValidTwilioRequest } from "@/lib/twilio-webhook";

export async function POST(req: Request) {
  const signature = req.headers.get("x-twilio-signature") ?? "";
  const form = await req.formData();
  const params = Object.fromEntries([...form.entries()].map(([k, v]) => [k, String(v)]));

  // The signed URL must match what Twilio called. Behind Vercel/proxies, build it from
  // forwarded headers (https + host) — NOT req.url, which may show the internal origin.
  const host = req.headers.get("x-forwarded-host") ?? req.headers.get("host");
  const url = `https://${host}/api/twilio/inbound`;

  if (!isValidTwilioRequest(signature, url, params)) {
    return new NextResponse("Invalid signature", { status: 403 });
  }

  const from = params.From;
  const body = params.Body;
  // ... process the message (untrusted input) ...

  // Reply with TwiML (empty <Response/> = no auto-reply)
  return new NextResponse("<Response><Message>Thanks, we got it.</Message></Response>", {
    status: 200,
    headers: { "Content-Type": "text/xml" },
  });
}

const twilio = require("twilio");
const express = require("express");
const app = express();

app.use(express.urlencoded({ extended: false })); // MUST run before validation
app.post(
  "/twilio/inbound",
  twilio.webhook(), // reads TWILIO_AUTH_TOKEN, validates X-Twilio-Signature, 403s otherwise
  (req, res) => {
    const reply = new twilio.twiml.MessagingResponse();
    reply.message("Thanks, we got it.");
    res.type("text/xml").send(reply.toString());
  },
);

await client.messages.create({
  to: "whatsapp:+15619991234",
  from: "whatsapp:+14155238886", // your WhatsApp sender (Sandbox number in dev)
  body: "Your codeAmani appointment is confirmed.",
});

# Account auth (server-side only — the Auth Token is a full-account secret)
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # NEVER ship to the client bundle

# Messaging
TWILIO_PHONE_NUMBER=+15619991234                    # a Twilio number you own (E.164)
TWILIO_MESSAGING_SERVICE_SID=MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # optional: number pool / sender

# Verify (OTP) — create the Service in the console, copy its SID
TWILIO_VERIFY_SERVICE_SID=VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

npm install -g twilio-cli
twilio login                                   # stores credentials in the keychain
twilio api:core:messages:create \
  --from "$TWILIO_PHONE_NUMBER" --to "+15619991234" --body "Hello from codeAmani"
twilio phone-numbers:list                      # list owned numbers