RonanCodes/twilio-whatsapp

Twilio WhatsApp

Two-way WhatsApp in your app. For a demo, use the WhatsApp Sandbox — no Meta business verification, no number purchase, live in minutes. For production, register a real WhatsApp sender (needs Meta business profile + approval).

Credentials + env

Twilio REST auth is HTTP Basic. Two valid pairs:

• Account SID + Auth Token — simplest. AC... / token from the console dashboard.
• API Key SID + Secret (SK... / secret) — revocable, scoped; pass with { accountSid }. Recommended for production.

The Auth Token is still required for inbound webhook signature validation regardless of which pair you send with (Twilio always signs with the account Auth Token).

TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...                 # needed for inbound signature validation
TWILIO_API_KEY_SID=SK...              # optional, production-correct send auth
TWILIO_API_KEY_SECRET=...
TWILIO_REGION=ie1                     # if the key/account is regional (Ireland)
TWILIO_WHATSAPP_FROM=whatsapp:+14155238886   # the sandbox sender

Node client: twilio(apiKeySid, apiKeySecret, { accountSid, region }) (or twilio(accountSid, authToken)).

Sandbox setup (demo path)

1. Console → Messaging → Try it out → Send a WhatsApp message; accept terms. Note the shared sender (+1 415 523 8886) and your join <code>.
2. From each phone that will message the demo, WhatsApp join <code> to that number. The sandbox can ONLY message numbers that have opted in; the join expires after 3 idle days (re-join before a demo).
3. Set the sandbox "When a message comes in" webhook to https://<app>/api/whatsapp/webhook.

Inbound webhook (Next.js App Router)

Twilio POSTs form-encoded. Key fields: From (whatsapp:+E164), Body, ProfileName, WaId (the number, no prefix), MessageSid, media via NumMedia/MediaUrl0.

export async function POST(req: Request) {
  const raw = await req.text();
  const params = new URLSearchParams(raw);
  const token = process.env.TWILIO_AUTH_TOKEN;
  if (token) {
    // Twilio signature: base64(HMAC-SHA1(fullUrl + sorted(key+value)...)), Auth Token as key.
    const proto = req.headers.get("x-forwarded-proto") ?? "https";
    const url = `${proto}://${req.headers.get("host")}/api/whatsapp/webhook`;
    const data = url + [...params.keys()].sort().map(k => k + params.get(k)).join("");
    const expected = crypto.createHmac("sha1", token).update(Buffer.from(data,"utf-8")).digest("base64");
    if (req.headers.get("x-twilio-signature") !== expected) return new Response("bad sig", { status: 403 });
  }
  const waNumber = (params.get("From")||"").replace("whatsapp:","");
  // → upsert a contact by phone, insert a message (channel "whatsapp"), then:
  return new Response("<Response></Response>", { headers: { "Content-Type": "text/xml" } }); // empty TwiML = no auto-reply
}

Signature gotcha: behind a proxy (Vercel/CF) TLS terminates upstream, so reconstruct the exact public HTTPS URL Twilio called (hardcode the known path) or validation fails. For a throwaway demo you can skip validation (gate on the secret of obscurity), but keep it for anything real.

Sending

await client.messages.create({
  from: process.env.TWILIO_WHATSAPP_FROM!,   // "whatsapp:+14155238886"
  to: `whatsapp:+${waId}`,
  body: text,
});

24-hour session window: after a user messages you, you can send free-form replies for 24h. Outside that window you must use a pre-approved template (sandbox: 3 test templates; production: your Meta-approved ones). User-initiated demos stay in-window, so no templates needed if you reply promptly.

Production path (summary)

Register a Sender under Twilio's WhatsApp Senders flow, tied to a Meta Business profile (business verification, display name). Approval is minutes-to-days. Then create Meta-approved templates for business-initiated messages. A WhatsApp-capable number costs ~$7.70/month (e.g. a NL mobile, 2026), plus ~$0.005/message on top of Meta's per-message fee; user-initiated service conversations are free for the first 24h. The sandbox needs none of this — it's free and uses the shared +1 415 523 8886. Only buy a number when you need a branded production sender.

Client opt-in pattern (onboarding)

To let a client opt into WhatsApp alerts during onboarding, show a consent toggle + a QR that deep-links WhatsApp pre-filled with the join code: https://wa.me/<sandboxNumber>?text=join%20<code>. They scan or tap, hit send, and they're connected to the sandbox — no manual number/code copying. (In production, swap the sandbox join for your registered sender; the consent record is what matters for compliance.)

Checklist

• [ ] Env set; TWILIO_AUTH_TOKEN present for inbound validation; twilioConfigured() guard so the app degrades gracefully.
• [ ] Sandbox activated; demo phones opted in via join <code> (re-join after 3 idle days).
• [ ] Inbound webhook set in the sandbox config; returns empty TwiML.
• [ ] Reply respects the 24h window; templates only when needed.
• [ ] Trial accounts may need a card/top-up before sends succeed.

Further reading

• Sandbox: https://www.twilio.com/docs/whatsapp/sandbox
• Quickstart: https://www.twilio.com/docs/whatsapp/quickstart
• Webhook fields: https://www.twilio.com/docs/messaging/guides/webhook-request
• Signature validation: https://www.twilio.com/docs/usage/webhooks/webhooks-security