Twilio SMS and Verify skill for Codex

Done well means: messages go through a Messaging Service on a registered sender, every inbound and status webhook is signature-validated, delivery status is stored per message SID, opt-outs are honoured, OTPs use Verify rather than home-made codes, and no SMS or call reaches a real number without the user confirming recipients and text.

Before writing code

1. Read AGENTS.md; find an existing Twilio client, webhook routes and any phone-number model.
2. Credentials in env vars: TWILIO_ACCOUNT_SID, plus an API key pair (TWILIO_API_KEY, TWILIO_API_SECRET) for REST calls. Webhook signature validation needs TWILIO_AUTH_TOKEN (API key secrets cannot validate signatures). Never log any of them.
3. Check sender registration with the user. US traffic on 10-digit long codes requires an approved A2P 10DLC campaign; toll-free numbers require toll-free verification. Unregistered traffic is blocked (error 30034) or filtered.
4. Sending to real numbers, bulk campaigns and outbound calls cost money and reach people: confirm recipients, text and volume before running anything that sends.

Calls to Twilio need network access; in a Codex sandbox, ask for approval, or test against mocked clients and the Twilio test credentials described below.

Choose the product

Need	Use
Transactional or notification SMS	Programmable Messaging via a Messaging Service
One-time passcodes, phone verification	Twilio Verify (handles code generation, expiry, rate limits, channels)
Inbound SMS replies or keyword bots	Messaging webhook returning TwiML or 200 empty
Phone menus and call routing	Programmable Voice with TwiML <Gather>
WhatsApp through Twilio	Same Messaging API with whatsapp: addresses; template rules from $whatsapp-business-api apply

Send an SMS

import twilio from "twilio";
const client = twilio(process.env.TWILIO_API_KEY, process.env.TWILIO_API_SECRET, {
  accountSid: process.env.TWILIO_ACCOUNT_SID,
});

const msg = await client.messages.create({
  to: user.phoneE164,                                   // E.164: +15551234567
  messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
  body: renderTemplate("shipped", order),
  statusCallback: `${process.env.PUBLIC_URL}/twilio/status`,
});
await db.smsLog.insert({ sid: msg.sid, to: user.id, status: msg.status });

• Normalise numbers to E.164 at input time (libphonenumber), not at send time.
• A Messaging Service picks the sender, handles sticky sender and opt-outs, and is where 10DLC campaigns attach. Prefer it over a hard-coded from.
• Store sid; status callbacks update it through queued, sent, delivered, undelivered or failed, with an ErrorCode on failure.

Segments and cost

Carriers bill per segment. GSM-7 allows 160 characters in one segment and 153 per segment when split; one non-GSM character (curly quote, em dash, most emoji) switches the whole message to UCS-2, which allows 70 and 67. Check templates before shipping:

python3 scripts/sms_segments.py "Your code is 123456. It expires in 10 minutes."
python3 scripts/sms_segments.py --file templates/sms/shipped.txt --max-segments 2   # exit 1 if over
python3 scripts/sms_segments.py --self-test

The script names the characters that forced UCS-2 so you can replace them (straight quotes, hyphen instead of em dash). Twilio’s Smart Encoding on the Messaging Service can also substitute common look-alikes.

Webhooks and signature validation

// Express: twilio.webhook() validates X-Twilio-Signature using TWILIO_AUTH_TOKEN
app.post("/twilio/sms", express.urlencoded({ extended: false }), twilio.webhook({ protocol: "https" }), (req, res) => {
  const { From, Body, MessageSid } = req.body;
  const reply = new twilio.twiml.MessagingResponse();
  if (/^help$/i.test(Body.trim())) reply.message("Reply STOP to unsubscribe. Support: example.com/help");
  res.type("text/xml").send(reply.toString());
});

app.post("/twilio/status", express.urlencoded({ extended: false }), twilio.webhook({ protocol: "https" }), async (req, res) => {
  await db.smsLog.update(req.body.MessageSid, { status: req.body.MessageStatus, error: req.body.ErrorCode ?? null });
  res.sendStatus(204);
});

Manual validation (Python):

from twilio.request_validator import RequestValidator
ok = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"]).validate(
    public_url_exactly_as_configured, request.form.to_dict(), request.headers.get("X-Twilio-Signature", ""))

The signature covers the full public URL Twilio called (scheme, host, port, path, query) plus POST parameters. Behind a proxy or tunnel the server sees http://internal:3000/..., so validation fails unless you rebuild the public URL (protocol: 'https', host options, or X-Forwarded-* handling). Status callbacks can arrive out of order; never move a message backwards from delivered to sent.

Verify (OTP)

const verify = client.verify.v2.services(process.env.TWILIO_VERIFY_SERVICE_SID!);
await verify.verifications.create({ to: phoneE164, channel: "sms" });         // send code
const check = await verify.verificationChecks.create({ to: phoneE164, code });  // check code
if (check.status !== "approved") throw new Error("Invalid or expired code");

• Rate-limit by user, IP and phone number on your side too; add a CAPTCHA before sending codes from public forms.
• Enable Verify Fraud Guard and restrict Geo Permissions to the countries you serve. SMS pumping (bots requesting codes to premium numbers) is the most common surprise bill.

Voice IVR

app.post("/twilio/voice", express.urlencoded({ extended: false }), twilio.webhook({ protocol: "https" }), (req, res) => {
  const vr = new twilio.twiml.VoiceResponse();
  const g = vr.gather({ numDigits: 1, action: "/twilio/voice/menu", timeout: 5 });
  g.say("Press 1 for order status. Press 2 to speak to someone.");
  vr.redirect("/twilio/voice");                       // no input: repeat menu
  res.type("text/xml").send(vr.toString());
});

Error codes worth mapping

Code	Meaning	Action
21211	Invalid To number	Fix input validation
21408	Geo permission not enabled for that country	Enable only if the user approves the region
21610	Recipient replied STOP	Do not retry; mark opted out
30003 / 30005	Unreachable or unknown destination	Mark number, retry later at most once
30006	Landline or unreachable carrier	Offer voice or email
30007	Carrier filtering (content or volume)	Review content, registration and links
30034	Unregistered US 10DLC sender	Finish A2P 10DLC registration

Testing

• Test credentials (test Account SID and auth token from the console) accept magic numbers such as From: +15005550006 and never send real messages or bill; they cannot be used with Messaging Services or Verify.
• For inbound webhooks, expose localhost with a tunnel ($webhook-testing-tools) and point a dev number at it; never repoint the production number.
• Unit-test webhook handlers by signing requests with twilio.getExpectedTwilioSignature.

Gotchas

• Opt-out keywords (STOP, UNSUBSCRIBE, and others) are handled by Twilio for long codes and toll-free; also record them in your database so other channels respect them.
• Link shorteners from public services trigger filtering; use your own domain or Twilio’s link shortening on a branded domain.
• Quiet hours and local regulations (TCPA in the US, consent rules elsewhere) apply to marketing messages; the user’s counsel should review campaign consent flows.
• Concurrency: Twilio queues messages per sender; bursts above the sender’s throughput are delayed, not dropped, but can expire after the Messaging Service validity period.

Report template

**Sender:** Messaging Service MG..., A2P 10DLC campaign approved (brand + campaign IDs in notes)
**Send path:** messages.create with statusCallback; sms_log(sid, status, error_code)
**Webhooks:** /twilio/sms, /twilio/status, /twilio/voice; signatures validated (proxy-aware URL)
**OTP:** Verify service VA..., Fraud Guard on, Geo Permissions: US, CA
**Templates:** all <= 2 GSM-7 segments (scripts/sms_segments.py in CI)
**Needs user:** live sends, campaign registration details, consent copy review