Skip to content

TWILIO_SETUP_GUIDE.md

Latest commit

 

History

History
283 lines (208 loc) · 8.76 KB

TWILIO_SETUP_GUIDE.md

File metadata and controls

283 lines (208 loc) · 8.76 KB

Twilio WhatsApp Integration Setup Guide for Hawkins

This guide covers both Sandbox (Testing) and Production (Live) setups for Twilio WhatsApp integration in your Hawkins fraud detection system.

🚀 Quick Start Options

Option 1: Development Mode (No Twilio Required)

Best for: Testing the approval flow without Twilio setup

  1. In Supabase Dashboard → Project Settings → Edge Functions → Secrets
  2. Add secret: 
    Key: ENABLE_WHATSAPP_DEV_MODE
Value: true
  3. Redeploy the send-whatsapp-approval edge function
  4. ✅ WhatsApp approvals will be simulated (no real messages sent)

Option 2: Sandbox Mode (Testing with Real WhatsApp)

Best for: Testing real WhatsApp messages before production

Step 1: Get Twilio Sandbox Credentials

  1. Create Twilio Account at console.twilio.com
  2. Copy your credentials from the Console homepage:
    • Account SID: AC... (starts with AC)
    • Auth Token: Click "Show" to reveal
  3. Navigate to WhatsApp Sandbox:
    • Go to Messaging → Try it out → Send a WhatsApp message
    • Or direct link: WhatsApp Sandbox

Step 2: Join Twilio WhatsApp Sandbox

⚠️ CRITICAL: You must join the sandbox before it works!

  1. Send WhatsApp message from your phone to: +1 415 523 8886
  2. Message content: join [your-sandbox-code]
    • Your sandbox code is shown in Twilio Console
    • Example: join capital-evening
  3. Wait for confirmation: You'll receive a message saying you've joined
  4. ✅ Now WhatsApp messages can be sent to your number

Step 3: Configure Supabase Edge Function

  1. Go to Supabase Dashboard → Your Project → Project Settings → Edge Functions → Secrets

  2. Add these three secrets:

    Key: TWILIO_ACCOUNT_SID
Value: YOUR_TWILIO_ACCOUNT_SID_HERE

Key: TWILIO_AUTH_TOKEN
Value: YOUR_TWILIO_AUTH_TOKEN_HERE

Key: TWILIO_WHATSAPP_NUMBER
Value: +14155238886

    ⚠️ CRITICAL FORMAT RULES:

    • ✅ Correct: +14155238886 (with + prefix, NO "whatsapp:" prefix)
    • ❌ Wrong: whatsapp:+14155238886 (this will cause errors)
    • ❌ Wrong: 14155238886 (missing + prefix)

  3. Redeploy the send-whatsapp-approval edge function:

    supabase functions deploy send-whatsapp-approval

Step 4: Test the Integration

  1. In your Hawkins app → Customer Dashboard
  2. Click "Quick Transaction" and submit a test transaction
  3. You should receive a WhatsApp message on the phone that joined the sandbox
  4. Reply: YES ITSME to approve or NO to decline
  5. ✅ The transaction should update based on your response

Option 3: Production Setup (Live WhatsApp Business)

Best for: Production deployments with your own WhatsApp Business number

Prerequisites

  • Verified business (Facebook Business Manager)
  • Business documents ready
  • WhatsApp Business API approval (1-3 business days)

Step 1: Request WhatsApp Business API Access

  1. In Twilio Console: Messaging → Senders → WhatsApp senders
  2. Click: "Request Access" for WhatsApp Business API
  3. Provide business information:
    • Business name and website
    • Business category
    • Business address
  4. Upload business documents:
    • Business registration documents
    • Tax ID or business license
  5. Submit for review (typically 1-3 business days)

Step 2: Configure Your WhatsApp Business Number

  1. After approval, you'll receive a WhatsApp Business number (e.g., +1234567890)
  2. This number must be:
    • Not currently used with WhatsApp
    • Owned by your business
    • Able to receive SMS verification codes

Step 3: Update Supabase Edge Function Secrets

  1. Go to Supabase Dashboard → Project Settings → Edge Functions → Secrets

  2. Update these secrets:

    Key: TWILIO_ACCOUNT_SID
Value: YOUR_TWILIO_ACCOUNT_SID_HERE

Key: TWILIO_AUTH_TOKEN
Value: YOUR_TWILIO_AUTH_TOKEN_HERE

Key: TWILIO_WHATSAPP_NUMBER
Value: +1234567890 (your approved WhatsApp Business number)

    ⚠️ FORMAT RULES:

    • ✅ Use your approved business number with + prefix
    • ✅ Do NOT include "whatsapp:" prefix
    • ✅ Example: +12025551234

  3. Remove dev mode (if previously set):

    • Delete ENABLE_WHATSAPP_DEV_MODE secret

  4. Redeploy the edge function:

    supabase functions deploy send-whatsapp-approval

🔍 Troubleshooting Common Errors

Error: "The 'From' number is not a valid phone number"

Cause: Incorrect TWILIO_WHATSAPP_NUMBER format

Fix:

  1. Check Supabase Edge Function secrets
  2. Ensure format is: +14155238886 (NO "whatsapp:" prefix)
  3. Must include + at the start
  4. Redeploy edge function after fixing

Error: "Authenticate" or Code 20003

Cause: Invalid Twilio credentials

Fix:

  1. Verify Account SID starts with AC
  2. Re-copy Auth Token from Twilio Console (click "Show")
  3. Check for typos or extra spaces
  4. Update in Supabase secrets and redeploy

Error: Code 21606 - WhatsApp sender not verified

Cause: Haven't joined Twilio sandbox OR sandbox expired

Fix for Sandbox:

  1. Send WhatsApp message: join [code] to +1 415 523 8886
  2. Wait for confirmation message
  3. Sandbox expires after 72 hours of inactivity - rejoin if needed

Fix for Production:

  1. Complete WhatsApp Business API approval in Twilio Console
  2. Use your approved WhatsApp Business number
  3. Update TWILIO_WHATSAPP_NUMBER with approved number

No WhatsApp Message Received

Check:

  1. ✅ Joined Twilio sandbox (for testing)
  2. ✅ Phone number format correct: +[country_code][number]
  3. ✅ Edge function secrets correctly configured
  4. ✅ Edge function redeployed after secret changes
  5. ✅ Check Supabase Edge Function logs for errors

📋 Configuration Checklist

For Sandbox Testing:

  • Twilio account created
  • Joined WhatsApp sandbox by messaging +1 415 523 8886
  • TWILIO_ACCOUNT_SID configured in Supabase
  • TWILIO_AUTH_TOKEN configured in Supabase
  • TWILIO_WHATSAPP_NUMBER set to +14155238886
  • Edge function redeployed
  • Test transaction sent and WhatsApp message received

For Production:

  • WhatsApp Business API approved by Twilio
  • WhatsApp Business number assigned
  • TWILIO_ACCOUNT_SID configured in Supabase
  • TWILIO_AUTH_TOKEN configured in Supabase
  • TWILIO_WHATSAPP_NUMBER set to approved business number
  • ENABLE_WHATSAPP_DEV_MODE deleted (if previously set)
  • Edge function redeployed
  • Test transaction sent to production number

🎯 Expected Behavior

Sandbox Mode:

  • ✅ Messages only work with numbers that joined sandbox
  • ✅ Message shows "sent from unverified business"
  • ✅ Sandbox expires after 72 hours of inactivity
  • ✅ Limited to 1 message per 24 hours per number

Production Mode:

  • ✅ Send to any WhatsApp number worldwide
  • ✅ Verified business badge displayed
  • ✅ No message limits
  • ✅ Custom business name shown as sender

🆘 Getting Help

  1. Twilio Documentation: WhatsApp API Docs
  2. Supabase Docs: Edge Functions
  3. Check Supabase Logs: Project → Edge Functions → Logs
  4. Twilio Console: Check SMS logs for delivery status

🔐 Security Best Practices

  1. Never commit Twilio credentials to git
  2. Use Supabase secrets for credential storage
  3. Rotate Auth Token regularly (every 90 days)
  4. Enable Two-Factor Authentication on Twilio account
  5. Monitor usage in Twilio Console to detect unauthorized access

💰 Pricing Information

Sandbox (Free):

  • No charge for sandbox testing
  • Limited functionality
  • Only pre-approved numbers

Production:

  • WhatsApp Business API: $0.005 - $0.02 per message (varies by country)
  • Conversation-based pricing (24-hour windows)
  • Free tier: First 1,000 conversations per month

Check current pricing: Twilio WhatsApp Pricing

✅ Success Indicators

Your setup is working correctly when:

  • ✅ Customer receives WhatsApp message within 5 seconds of transaction
  • ✅ Reply "YES ITSME" updates transaction status to approved
  • ✅ Reply "NO" updates transaction status to declined
  • ✅ 60-second timer stops when reply received
  • ✅ No errors in Supabase Edge Function logs

🔄 Migration from Sandbox to Production

  1. Complete WhatsApp Business API approval
  2. Get your production WhatsApp Business number
  3. Update TWILIO_WHATSAPP_NUMBER in Supabase secrets
  4. Remove ENABLE_WHATSAPP_DEV_MODE (if set)
  5. Redeploy edge function
  6. Test with production number
  7. ✅ Your users no longer need to "join" anything!