OTP Applications

Create and manage One-Time Password (OTP) applications for user verification.

Visit /otp-applications to set up OTP delivery for authentication, account verification, or sensitive actions.

Creating an OTP Application

1. Click New OTP Application

2. Fill in:

   • Name — e.g., "Web App Login Verification"
   • Connection — the WhatsApp Business Account (WABA) to send OTPs from
   • Template — Choose an existing OTP template, or create a new one
   • Code Length — number of digits (4–8; default 6)
   • Expiry — seconds until code expires (typical: 300 = 5 minutes)
   • Max Attempts — how many wrong guesses before the code locks (default 3)

3. Click Create

The system generates an API key (shown once) — copy it immediately; you won't see it again.

API Key Management

Each OTP application has a unique API key used for authentication when calling the OTP API.

To view or rotate a key:

1. Go to /otp-applications
2. Click the application
3. Click API Keys
4. Click Generate New Key to create a replacement (old key becomes invalid immediately)

Security: Store API keys in your environment variables (.env). Never commit them to version control.

IP Allow-list

Restrict API calls to specific IP addresses for extra security.

To set up:

1. Click the application
2. Go to Security
3. Add trusted IPs (e.g., 192.168.1.100, 203.0.113.50)
4. Save

Only requests from these IPs will succeed; others get a 403 Forbidden error.

Leave blank to allow all IPs (less secure for production).

OTP Template

Each application sends from a WhatsApp OTP template (category: OTP). The template usually contains:

Your verification code is {{1}}. Do not share this code.

• When your app sends an OTP, {{1}} is replaced with the generated code
• Create templates at /templates with category set to OTP
• OTP templates typically get Meta auto-approval

Usage & Limits

Your plan limits the total OTP requests per month:

Monitor usage in the OTP application's Activity tab. If you hit the limit, requests fail with a 402 error; upgrade your plan to continue.

Testing an OTP

1. Go to /otp-applications
2. Click the application
3. Click Test
4. Enter a phone number (your own for testing)
5. Click Send
6. You'll receive the OTP on WhatsApp — note the code
7. Verify it in the UI to confirm the app is working

API Usage

For full API documentation and example curl requests, see the Integration Guide: OTP API.

Quick summary:

# Send OTP
curl -X POST https://wallin.example/api/v1/otp/send \
  -H "X-Wallin-OTP-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+201001234567"}'

# Verify OTP
curl -X POST https://wallin.example/api/v1/otp/verify \
  -H "X-Wallin-OTP-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"reference_id": "...", "code": "123456"}'

Monitoring & Logs

Click an application to see:

• Last Used — timestamp of the most recent API call
• Total Sent — count of OTPs issued
• Activity Log — recent send/verify attempts with status
• Success Rate — % of codes that were verified successfully

Troubleshooting

"API key invalid or missing"

• Ensure you're passing X-Wallin-OTP-Key: your_key in the request header
• Check the key hasn't been rotated or the application disabled
• Verify the key is active (go to the app and check API Keys)

"IP not allowed"

• If you set an IP allow-list, ensure your request's source IP is on it
• Check your IP with curl https://httpbin.org/ip

"Rate limit exceeded"

• Max 5 OTP sends per phone number per hour
• Max 20 sends per IP per hour
• Wait 1 hour or use a different IP

"Plan limit exceeded"

• You've hit your monthly OTP quota
• Upgrade your plan at /organizations/settings → Billing

"Template is paused or rejected"

• Go to /templates and check the template status
• If paused, click Resume
• If rejected, create a new OTP template and reassign it to the application