Skip to main content

Twilio Integration

Enable SMS-based WiFi authentication with one-time passwords, phone number verification, and guest notifications using Twilio's messaging platform.

Overview​

Twilio integration provides:

  • SMS Authentication - One-time passwords via SMS
  • Phone Number Verification - Verify guest phone numbers
  • Notifications - Send welcome messages or access codes
  • Two-Factor Authentication - Additional security layer

Prerequisites​

  • IronWifi account with captive portal
  • Twilio account (twilio.com)
  • Twilio phone number (for sending SMS)

Twilio Account Setup​

Create Account​

  1. Sign up at twilio.com
  2. Verify your email and phone number
  3. Complete account setup

Get a Phone Number​

  1. In Twilio Console, go to Phone Numbers
  2. Click Buy a Number
  3. Select a number with SMS capability
  4. Note the phone number

Get API Credentials​

  1. Go to Account > API keys & tokens
  2. Copy:
    • Account SID: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    • Auth Token: Your authentication token

IronWifi Configuration​

Step 1: Add Twilio Provider​

  1. Log in to IronWifi Console
  2. Navigate to Networks > Captive Portals
  3. Select your captive portal
  4. Go to Authentication Providers
  5. Click Add Provider > Twilio (SMS)

Step 2: Configure Credentials​

Enter Twilio details:

  • Account SID: Your Twilio Account SID
  • Auth Token: Your Auth Token
  • From Number: Your Twilio phone number (E.164 format: +1234567890)

Step 3: Configure SMS Settings​

Message Template:

Your WiFi access code is: {{code}}
Valid for 5 minutes.

Available variables:

  • {{code}} - One-time password
  • {{network}} - Network name
  • {{duration}} - Access duration
  • {{expiry}} - Code expiration time

Settings:

  • Code Length: 4-8 digits
  • Code Expiry: Time in minutes (default: 5)
  • Max Attempts: Limit verification attempts

Authentication Flow​

SMS Login Flow​

  1. Guest connects to WiFi
  2. Captive portal displays phone number input
  3. Guest enters phone number
  4. IronWifi sends SMS via Twilio
  5. Guest receives code on their phone
  6. Guest enters code on captive portal
  7. Code verified, access granted

Implementation​

<!-- Phone Number Form -->
<form id="phone-form">
  <input type="tel" name="phone" placeholder="+1 (555) 123-4567" required>
  <button type="submit">Send Code</button>
</form>

<!-- Verification Form (shown after SMS sent) -->
<form id="verify-form" style="display:none;">
  <input type="text" name="code" placeholder="Enter code" maxlength="6">
  <button type="submit">Verify</button>
  <a href="#" onclick="resendCode()">Resend Code</a>
</form>

Advanced Configuration​

Country Restrictions​

Limit SMS to specific countries:

  1. In Twilio provider settings, find Allowed Countries
  2. Enter country codes (e.g., US, CA, GB)
  3. Requests from other countries will be rejected

Rate Limiting​

Prevent abuse:

  • Max SMS per number per hour: 3
  • Max SMS per IP per hour: 10
  • Cooldown between requests: 60 seconds

Number Validation​

Enable phone number validation:

  1. In settings, enable Validate Phone Numbers
  2. IronWifi uses Twilio Lookup API
  3. Invalid numbers are rejected before SMS

Two-Factor Authentication​

Add SMS as second factor:

Setup​

  1. Configure primary authentication (social login, vouchers, etc.)
  2. Enable Two-Factor Authentication
  3. Select Twilio SMS as 2FA method

Flow​

  1. User completes primary authentication
  2. Prompted for phone number
  3. SMS code sent
  4. Code verified
  5. Access granted

Notifications​

Welcome SMS​

Send welcome message after authentication:

Welcome to {{network}}!
You have {{duration}} of WiFi access.
Support: help@example.com

Expiry Warning​

Notify users before access expires:

Your WiFi access expires in 10 minutes.
Visit the portal to extend your session.

Testing​

Twilio Test Credentials​

Use test credentials for development:

  • Messages aren't actually sent
  • No charges incurred
  • Test phone numbers for various scenarios

Magic Numbers​

Twilio provides test numbers:

  • +15005550006 - Valid number
  • +15005550001 - Invalid number
  • +15005550009 - Cannot receive SMS

Verify in Console​

  1. Send test SMS
  2. Check Twilio Console > Monitor > Logs
  3. Verify message delivery status

Troubleshooting​

SMS Not Received​

  1. Verify phone number format (E.164)
  2. Check Twilio logs for errors
  3. Verify "From" number can send to destination
  4. Check for carrier filtering

Invalid Code Errors​

  1. Verify code hasn't expired
  2. Check for typos
  3. Confirm max attempts not exceeded
  4. Try requesting new code

Rate Limit Errors​

  1. Wait for cooldown period
  2. Check rate limit settings
  3. Contact support if legitimate usage

Costs​

Twilio pricing:

  • SMS pricing varies by country
  • Typically $0.0075 - $0.05 per message
  • Phone number: ~$1/month
  • Lookup API: $0.005 per lookup

Estimate monthly costs based on expected guest volume.

Best Practices​

  1. Clear instructions - Explain SMS login process
  2. Reasonable expiry - 5-10 minutes for codes
  3. Resend option - Allow code resend after delay
  4. International support - Consider country restrictions
  5. Monitor usage - Track SMS costs and abuse