Skip to content
Twilio Verify OTP Delivery

Twilio Verify OTP Delivery Skill

Add phone or email verification with Twilio Verify — send and check one-time passcodes over SMS, voice, email or WhatsApp, with built-in expiry, rate limiting and Fraud Guard rather than hand-rolled OTP plumbing.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from twilio/ai.

$ npx skills add twilio/ai --skill twilio-verify-send-otp

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

  1. Open the skill on GitHub and download the folder that holds its SKILL.md.
  2. Put it at ~/.claude/skills/twilio-verify-send-otp/, where Claude Code picks it up in every project.

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/twilio-verify-send-otp/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Verify vs Programmable Messaging decision table with cost and compliance trade-offs
  • Create a Verify Service, send tokens and check submitted codes across SMS, voice, email and WhatsApp
  • Automatic WhatsApp-to-SMS fallback and RCS upgrade behaviour explained
  • Fraud Guard, rate limiting and a debugging checklist for undelivered codes

One-time passcodes look trivial and are not: you need code generation, expiry, per-phone and per-service rate limits, fraud protection, delivery confirmation and a fallback when a channel fails. This skill covers the full lifecycle on Twilio Verify and — importantly — tells the agent when Verify is the wrong tool.

It opens with a side-by-side comparison of Twilio Verify against the raw Programmable Messaging API. Verify gives you code generation with a configurable ten-minute default expiry, built-in rate limiting, Fraud Guard with geo-permissions and rate-anomaly detection, exemption from A2P 10DLC registration, and one API across SMS, voice, email and WhatsApp — you change only the channel parameter. Programmable Messaging means building all of that yourself, and is justified only when you need full control of message content, custom delivery logic, or SMS Pumping Protection.

Two details the skill is careful about: RCS is not a channel value — Verify silently upgrades an sms verification to RCS where the device supports it and falls back to SMS — and TOTP for authenticator apps lives in the Verify Factors API, a separate family from channel-based OTP. It also covers automatic WhatsApp-to-SMS fallback, service configuration, and a debugging section for when codes do not arrive.

Part of Twilio's official Skills set, MIT-licensed in the twilio/ai repository. Twilio Skills are a Public Beta product and not covered by Twilio's support terms or SLA.

SKILL.md

The instructions your agent loads, as published by Twilio.

SKILL.md
name
twilio-verify-send-otp
description
Send and verify one-time passcodes (OTPs) via Twilio Verify over SMS (auto-upgraded to RCS where supported), voice, email, or WhatsApp. Covers creating a Verify Service, sending tokens, checking submitted codes, automatic WhatsApp-to-SMS fallback, and service configuration. TOTP is supported via the Factors API (a separate family from channel-based OTP). Use this skill to add phone or email verification or two-factor authentication to any application.
Overview

Use Twilio Verify to manage the full OTP lifecycle: code generation, delivery, expiry, rate limiting, and Fraud Guard protection. Use the Programmable Messaging API to build your own OTP message infrastructure and access features such as SMS Pumping Protection.

Twilio VerifyProgrammable Messaging API
Code generation + expiryBuilt-in (10min default, configurable). Also supports custom codes.Build yourself
Rate limitingBuilt-in (per-phone, per-service)Build yourself
Fraud protectionFraud Guard (geo-permissions, rate anomaly)SMS Pumping Protection
A2P registrationExempt — no 10DLC neededRequired — must register campaign
Multi-channelOne API, change channel param (SMS/Voice/Email/WhatsApp)Separate integration per channel
CostPer confirmed verification + channel feePer-message pricing + build cost
Delivery confirmationYes — via List Attempts or Events APIYes (via StatusCallback)

When Programmable Messaging is justified: You need full control over message content, custom delivery logic, or SMS Pumping Protection features. For standard OTP/2FA flows, use Verify.

Verify supports SMS, voice, email, and WhatsApp — only the channel parameter changes per delivery method. RCS is not a channel value: Verify automatically upgrades an sms verification to RCS where the device supports it and falls back to SMS. TOTP (authenticator apps) is supported via the Verify Factors API, a separate implementation from channel-based OTP.

---

Prerequisites
  • Twilio account (free trial works for testing)

— New to Twilio? See twilio-account-setup
— Verify requires no separate product activation — just create a Service below

  • Environment variables:
  • TWILIO_ACCOUNT_SID
  • TWILIO_AUTH_TOKEN
  • VERIFY_SERVICE_SID (created in Quickstart step 1)

— See twilio-iam-auth-setup for credential setup and best practices

  • SDK: pip install twilio / npm install twilio
  • For WhatsApp channel only: a registered production WhatsApp sender — see twilio-whatsapp-manage-senders

---

Quickstart

Step 1 — Create a Verify Service (one-time)

Python

import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

service = client.verify.v2.services.create(
    friendly_name="My App Verification"
)
print(service.sid)  # VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx — save as VERIFY_SERVICE_SID

Node.js

const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

const service = await client.verify.v2.services.create({
    friendlyName: "My App Verification",
});
console.log(service.sid);  // VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Store the Service SID — reuse it for all verifications, do not recreate it each time.

Step 2 — Send a verification token

Python

verification = client.verify.v2 \
    .services(os.environ["VERIFY_SERVICE_SID"]) \
    .verifications \
    .create(to="+15558675310", channel="sms")

print(verification.status)  # pending

Node.js

const verification = await client.verify.v2
    .services(process.env.VERIFY_SERVICE_SID)
    .verifications.create({ to: "+15558675310", channel: "sms" });

console.log(verification.status);  // pending

Step 3 — Check the submitted code

Python

check = client.verify.v2 \
    .services(os.environ["VERIFY_SERVICE_SID"]) \
    .verification_checks \
    .create(to="+15558675310", code="123456")

if check.status == "approved":
    print("Verified!")
else:
    print("Invalid or expired code")

Node.js

const check = await client.verify.v2
    .services(process.env.VERIFY_SERVICE_SID)
    .verificationChecks.create({ to: "+15558675310", code: "123456" });

if (check.status === "approved") {
    console.log("Verified!");
} else {
    console.log("Invalid or expired code");
}

---

Key Patterns
Supported Channels
Channelchannel valueNotes
SMSsmsDefault, widest coverage. Auto-upgrades to RCS where supported (see below)
Voice callcallReads code aloud
EmailemailUse email address in to
WhatsAppwhatsappRequires own WhatsApp sender (see below)
TOTP (authenticator apps): Supported via the Verify Factors API — a separate implementation from channel-based OTP. See Verify TOTP docs.
WhatsApp OTP

Change channel to "whatsapp" — the send/check flow is identical to SMS.

Requires: A registered production WhatsApp sender. As of March 2024, Twilio no longer provides a shared sender for Verify. See twilio-whatsapp-manage-senders.

Python

verification = client.verify.v2 \
    .services(os.environ["VERIFY_SERVICE_SID"]) \
    .verifications \
    .create(to="+15558675310", channel="whatsapp")

Node.js

const verification = await client.verify.v2
    .services(process.env.VERIFY_SERVICE_SID)
    .verifications.create({ to: "+15558675310", channel: "whatsapp" });
WhatsApp with Automatic SMS Fallback

Python

verification = client.verify.v2 \
    .services(os.environ["VERIFY_SERVICE_SID"]) \
    .verifications \
    .create(
        to="+15558675310",
        channel="whatsapp",
        channel_configuration={
            "whatsapp": {"enabled": True},
            "sms": {"enabled": True}   # falls back to SMS if WhatsApp undelivered
        }
    )

Node.js

const verification = await client.verify.v2
    .services(process.env.VERIFY_SERVICE_SID)
    .verifications.create({
        to: "+15558675310",
        channel: "whatsapp",
        channelConfiguration: {
            whatsapp: { enabled: true },
            sms: { enabled: true },
        },
    });

With fallback enabled, your UI can say "a verification code was sent" without specifying the channel.

Service Configuration

Python

service = client.verify.v2.services.create(
    friendly_name="My App",
    code_length=6              # 4–10 digits (default: 6)
)

Node.js

const service = await client.verify.v2.services.create({
    friendlyName: "My App",
    codeLength: 6
});
Verification Status Values
StatusMeaning
approvedCode is correct
pendingCode is wrong or not yet submitted
expiredCode has expired (default TTL: 10 minutes)
canceledVerification was canceled

---

Debugging

Primary debugging tool: Console > Verify > Logs (per-Service). Shows every verification attempt, delivery status, channel used, and error codes. Check here first before writing custom monitoring code.

Common Errors
CodeMeaningFix
60200Invalid parameterCheck to format and channel value
60202Max check attempts reachedIssue a new verification
60203Max send attempts reachedWait before retrying
60212Service not foundVerify VERIFY_SERVICE_SID is correct
60410Geo-permission not enabledEnable country in Console

Built-in protections (no custom code needed):

  • Rate limiting: 5 verifications per phone per service per 10 minutes
  • Max check attempts: 5 per verification (6th attempt → error 60202)
  • Phone number validation: Verify checks line type before sending (if lookup_enabled=True)
  • Fraud Guard: geo-permissions, rate anomaly detection, SMS pumping protection

International OTP traffic warning: International numbers are high-risk for SMS pumping — fraudsters trigger OTPs to premium-rate destinations to generate revenue. Verify's Fraud Guard handles this automatically when enabled. If you're building custom OTP with Programmable Messaging instead, enable SMS Pumping Protection on your Messaging Service (see twilio-messaging-services). Always restrict geo-permissions to only countries where you have real users.

---

CANNOT
  • No built-in channel fallback — Must implement retry logic manually (e.g., SMS → voice → email). Use channel_configuration for WhatsApp→SMS only.
  • No webhook on verification completion — Must poll verification_checks. Rate-limited: 60/min, 180/hr, 250/day.
  • Cannot retrieve the actual code sent — Code is never returned in any API response. By design.
  • Sending on a new channel with the same `to` reuses the pending verification — the same Verification SID and code are kept, just delivered over the new channel (e.g. switching sms → call for the same phone number). A different to (e.g. an email address) starts a separate verification. To force a fresh code on the same to, cancel the pending one first.
  • Cannot extend TTL on an existing verification — Default 10 minutes, and not a per-verification or Service create/update param. Contact Twilio Support to change the default on your Service (adjustable 2 min–24 hr).
  • Verification SID deleted after approval — Fetching an approved verification returns 404. Canceled verifications remain fetchable.
  • `auto` channel not universally available — Returns error 60200 on accounts without Fraud Guard enabled.
  • Email channel requires Mailer configuration — channel: 'email' without a configured Mailer returns error 60217.
  • No real-time delivery push notification — Delivery status is available via List Attempts or Events API (pull-based), not via a push webhook.
  • FriendlyName rejects embedded digit strings — avoid embedding 5 or more digits in a Service name; it can trigger error 60200. Use words.
  • Wrong code does not throw an exception — Check returns status: "pending", not an error. You must check status === "approved" explicitly.
  • Cannot re-check an approved verification — Each verification is single-use. Once approved, subsequent checks return 404.
  • Cannot send to arbitrary numbers on trial accounts — Trial accounts have limited verification destinations
  • Cannot customize WhatsApp OTP template — Uses a fixed Meta authentication template
  • Cannot use WhatsApp channel for PSD2 compliance mode — PSD2 payee/amount parameters not supported on WhatsApp

---

Next Steps
  • Register a WhatsApp sender: twilio-whatsapp-manage-senders
  • Validate phone numbers before sending: twilio-lookup-phone-intelligence
  • Credential setup: twilio-iam-auth-setup
Install
Featured

Auth0's official agent skill: a router that detects your framework and intent, then loads the right Auth0 guidance for login, MFA, Organizations, tenant audits, debugging or provider migration.

Skill: Turnstile Spin

by Cloudflare

Turns “set up Turnstile” into a working end-to-end bot check — widget, frontend snippets, canonical server-side siteverify, and a real validation pass before it reports success.

Browse all skills →