Skip to content

Commit 116f9e6

Browse files
AJLangeAJLange
authored
Merge pull request #647 from twilio-labs/add-agents-md-to-verify
Modernize Verify Template
2 parents 9dca058 + 7173246 commit 116f9e6

6 files changed

Lines changed: 201 additions & 3 deletions

File tree

‎verify/.github/copilot-instructions.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
<!-- Auto-synced from AGENTS.md — do not edit directly. -->
2+
3+
# Twilio Verify - One-Time Passcode Verification
4+
5+
Serverless one-time passcode (OTP) verification using Twilio Verify with multi-channel support (SMS, voice call, WhatsApp, email) deployed on Twilio Functions.
6+
7+
## Commands
8+
9+
```bash
10+
# Install dependencies
11+
npm install
12+
13+
# Run locally
14+
npm start
15+
# Opens at http://localhost:3000/index.html
16+
17+
# Test
18+
npm test
19+
20+
# Deploy to Twilio
21+
twilio serverless:deploy
22+
```
23+
24+
## Environment Variables
25+
26+
Copy `.env.example` to `.env`. Never commit `.env`.
27+
28+
```bash
29+
cp .env.example .env
30+
```
31+
32+
| Variable | Where to find | Format |
33+
| -------- | ------------- | ------ |
34+
| `ACCOUNT_SID` | [Console](https://console.twilio.com) homepage | Starts with `AC` |
35+
| `AUTH_TOKEN` | Console homepage → click to reveal | 32-char string. Treat as a password. |
36+
| `VERIFY_SERVICE_SID` | Console → Verify → Services | Starts with `VA` |
37+
38+
## Project Structure
39+
40+
```
41+
functions/
42+
start-verify.js # Sends OTP via SMS, call, WhatsApp, or email
43+
check-verify.js # Validates user-provided OTP code
44+
assets/
45+
index.html # Web UI for testing verification flow
46+
styles.css # Twilio Paste design system styles
47+
locales.js # Multi-language support options
48+
tests/ # Unit tests for both functions
49+
```
50+
51+
## Agent Boundaries
52+
53+
**Always:**
54+
- Confirm `.env` is configured before running any command
55+
- Use the Environment Variables section to guide the user to each credential — don't ask them to find values without direction
56+
- Confirm the app is running before asking the user to test it
57+
- Verify the Verify Service is created at https://console.twilio.com/verify/services
58+
59+
**Never:**
60+
- Run the app with missing or placeholder credentials
61+
- Hardcode credentials or phone numbers in source files
62+
- Skip the `cp .env.example .env` step
63+
- Use invalid phone number formats (must be E.164: +15551234567)
64+
65+
## Verify It's Working
66+
67+
1. Open http://localhost:3000/index.html in your browser
68+
2. Select a verification channel (SMS, WhatsApp, voice call, or email)
69+
3. Enter your phone number (with country code) or email address
70+
4. Click "Get a one-time passcode" to receive the OTP
71+
5. Enter the code in the modal dialog and click "Verify code"
72+
6. You should see "Verification success!" in green
73+
74+
**Expected behavior:**
75+
- SMS/WhatsApp/Call: You receive a code on your phone within 30 seconds
76+
- Email: Check your inbox for a verification code email
77+
- After entering the correct code, the system confirms "Verification success!"
78+
- Incorrect codes show "Incorrect token!" in red
79+
80+
## Twilio Resources
81+
82+
- [Twilio Console](https://console.twilio.com) — credentials, Verify service configuration
83+
- [Verify API Documentation](https://www.twilio.com/docs/verify/api)
84+
- [Verify Quickstart](https://www.twilio.com/docs/verify/quickstarts)
85+
- [Supported Languages](https://www.twilio.com/docs/verify/supported-languages)
86+
- [Email Verification Setup](https://www.twilio.com/docs/verify/email)

‎verify/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules
2+
.env

‎verify/AGENTS.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Twilio Verify - One-Time Passcode Verification
2+
3+
Serverless one-time passcode (OTP) verification using Twilio Verify with multi-channel support (SMS, voice call, WhatsApp, email) deployed on Twilio Functions.
4+
5+
## Commands
6+
7+
```bash
8+
# Install dependencies
9+
npm install
10+
11+
# Run locally
12+
npm start
13+
# Opens at http://localhost:3000/index.html
14+
15+
# Test
16+
npm test
17+
18+
# Deploy to Twilio
19+
twilio serverless:deploy
20+
```
21+
22+
## Environment Variables
23+
24+
Copy `.env.example` to `.env`. Never commit `.env`.
25+
26+
```bash
27+
cp .env.example .env
28+
```
29+
30+
| Variable | Where to find | Format |
31+
| -------- | ------------- | ------ |
32+
| `ACCOUNT_SID` | [Console](https://console.twilio.com) homepage | Starts with `AC` |
33+
| `AUTH_TOKEN` | Console homepage → click to reveal | 32-char string. Treat as a password. |
34+
| `VERIFY_SERVICE_SID` | Console → Verify → Services | Starts with `VA` |
35+
36+
## Project Structure
37+
38+
```
39+
functions/
40+
start-verify.js # Sends OTP via SMS, call, WhatsApp, or email
41+
check-verify.js # Validates user-provided OTP code
42+
assets/
43+
index.html # Web UI for testing verification flow
44+
styles.css # Twilio Paste design system styles
45+
locales.js # Multi-language support options
46+
tests/ # Unit tests for both functions
47+
```
48+
49+
## Agent Boundaries
50+
51+
**Always:**
52+
- Confirm `.env` is configured before running any command
53+
- Use the Environment Variables section to guide the user to each credential — don't ask them to find values without direction
54+
- Confirm the app is running before asking the user to test it
55+
- Verify the Verify Service is created at https://console.twilio.com/verify/services
56+
57+
**Never:**
58+
- Run the app with missing or placeholder credentials
59+
- Hardcode credentials or phone numbers in source files
60+
- Skip the `cp .env.example .env` step
61+
- Use invalid phone number formats (must be E.164: +15551234567)
62+
63+
## Verify It's Working
64+
65+
1. Open http://localhost:3000/index.html in your browser
66+
2. Select a verification channel (SMS, WhatsApp, voice call, or email)
67+
3. Enter your phone number (with country code) or email address
68+
4. Click "Get a one-time passcode" to receive the OTP
69+
5. Enter the code in the modal dialog and click "Verify code"
70+
6. You should see "Verification success!" in green
71+
72+
**Expected behavior:**
73+
- SMS/WhatsApp/Call: You receive a code on your phone within 30 seconds
74+
- Email: Check your inbox for a verification code email
75+
- After entering the correct code, the system confirms "Verification success!"
76+
- Incorrect codes show "Incorrect token!" in red
77+
78+
## Twilio Resources
79+
80+
- [Twilio Console](https://console.twilio.com) — credentials, Verify service configuration
81+
- [Verify API Documentation](https://www.twilio.com/docs/verify/api)
82+
- [Verify Quickstart](https://www.twilio.com/docs/verify/quickstarts)
83+
- [Supported Languages](https://www.twilio.com/docs/verify/supported-languages)
84+
- [Email Verification Setup](https://www.twilio.com/docs/verify/email)

‎verify/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

‎verify/README.md‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
1-
# Twilio Verify
1+
# Twilio Verify - One-Time Passcode Verification
22

3-
These function show you how to send and check verification tokens for [Twilio Verify](https://www.twilio.com/docs/verify/api). More details about how to work with Verify and Twilio functions can be found in [this blog post](https://www.twilio.com/blog/serverless-phone-verification).
3+
## Serverless phone, email, and WhatsApp verification with Twilio Verify
4+
5+
These functions show you how to send and check verification tokens for [Twilio Verify](https://www.twilio.com/docs/verify/api). Build secure, serverless user verification flows with one-time passcodes (OTP) delivered via SMS, voice call, WhatsApp, or email. More details about how to work with Verify and Twilio functions can be found in [this blog post](https://www.twilio.com/blog/serverless-phone-verification).
6+
7+
Perfect for two-factor authentication (2FA), account verification, password resets, transaction confirmations, and any use case requiring identity verification.
48

59
![phone-verification-gif](./phone-verification-v3.gif?raw=true)
610

@@ -31,7 +35,7 @@ In your `.env` file, set the following values:
3135
| Parameter | Description | Required |
3236
| :------------- | :------------------------------------------ | :------- |
3337
| `to` | Either an email or phone number in [E.164 format](https://www.twilio.com/docs/glossary/what-e164) | Yes |
34-
| `channel` | 'sms', 'call', or 'email'. Default is 'sms' | No |
38+
| `channel` | 'sms', 'call', 'whatsapp', or 'email'. Default is 'sms' | No |
3539
| `locale` | Localization language. See [supported languages](https://www.twilio.com/docs/verify/supported-languages). Default is 'en' | No |
3640

3741
`check-verify.js` expects the following parameters:
@@ -83,3 +87,10 @@ With the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart):
8387
```
8488
twilio serverless:deploy
8589
```
90+
91+
## Additional Resources
92+
93+
- [Twilio Verify API Documentation](https://www.twilio.com/docs/verify/api)
94+
- [Verify Quickstart Guide](https://www.twilio.com/docs/verify/quickstarts)
95+
- [Email Verification Setup](https://www.twilio.com/docs/verify/email)
96+
- [Phone Verification with Twilio Verify Blog Tutorial](https://www.twilio.com/en-us/blog/serverless-phone-verification)

‎verify/package.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
{
2+
"name": "twilio-verify-otp",
23
"version": "1.0.2",
4+
"description": "Serverless one-time passcode verification using Twilio Verify with multi-channel support (SMS, voice, WhatsApp, email)",
5+
"keywords": [
6+
"twilio",
7+
"verify",
8+
"otp",
9+
"2fa",
10+
"two-factor-authentication",
11+
"phone-verification",
12+
"email-verification",
13+
"sms",
14+
"whatsapp",
15+
"serverless"
16+
],
317
"private": true,
418
"dependencies": {
519
"twilio": "^5.2.1"

0 commit comments

Comments
 (0)