Complete Twilio WhatsApp Setup Guide

BIBLE-Compliant Messaging for FleetOS

This guide gets real WhatsApp messages flowing through Twilio, integrated with company-owned architecture.

🎯 What You're Building

Fleet creates request → Supplier company gets WhatsApp notification
                    ↓
           Supplier replies "ACK" → Status updates to acknowledged
                    ↓
           Fleet company gets notification → "Supplier acknowledged"

Key Features:

✅ Company-owned notifications (org-first routing)
✅ WhatsApp replies update database (2-way messaging)
✅ Magic links in messages (1-click access)
✅ No individual user dependency (BIBLE-compliant)

📋 Prerequisites

Twilio Account (Free trial: https://www.twilio.com/try-twilio)
Supabase Project (Already set up)
WhatsApp-enabled phone (For testing)

Part 1: Twilio Setup (15 minutes)

Step 1.1: Create Twilio Account

Go to: https://www.twilio.com/try-twilio
Sign up with email
Verify your phone number
Note your trial credit ($15.00 free)

Step 1.2: Enable WhatsApp Sandbox

Twilio Console → Messaging → Try it out → Try WhatsApp

You'll see a WhatsApp sandbox number: +1 415 523 8886
Copy the sandbox code (e.g., join yellow-tiger)
On your phone:
- Open WhatsApp
- Send message to: +1 415 523 8886
- Message: join yellow-tiger (use YOUR code)
You should get confirmation: "Sandbox: ✅ You are all set!"

Step 1.3: Get Credentials

Twilio Console → Account Info

Account SID: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Auth Token: [Click "View" to reveal]

Copy these! You'll need them in the next section.

Part 2: Supabase Configuration (10 minutes)

Step 2.1: Install Supabase CLI

# Install globally
npm install -g supabase

# Verify
supabase --version

# Login to Supabase
supabase login

# Link to your project
cd C:\Projects\robo-hub
supabase link --project-ref bsbjwjpgiangjqqqxota

Step 2.3: Set Twilio Secrets

# Set Account SID
supabase secrets set TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Set Auth Token
supabase secrets set TWILIO_AUTH_TOKEN=your_auth_token_here

# Set WhatsApp number (sandbox)
supabase secrets set TWILIO_WHATSAPP_FROM=whatsapp:+14155238886

Verify secrets:

supabase secrets list

Should show:

TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN
TWILIO_WHATSAPP_FROM

Part 3: Deploy Edge Functions (5 minutes)

Step 3.1: Deploy Send Function

cd C:\Projects\robo-hub
supabase functions deploy send-whatsapp

Expected output:

✓ Deployed send-whatsapp function
✓ Function URL: https://bsbjwjpgiangjqqqxota.supabase.co/functions/v1/send-whatsapp

Step 3.2: Deploy Webhook Function

supabase functions deploy whatsapp-webhook

Expected output:

✓ Deployed whatsapp-webhook function
✓ Function URL: https://bsbjwjpgiangjqqqxota.supabase.co/functions/v1/whatsapp-webhook

Step 3.3: Test Send Function

# Get your Supabase anon key from .env
# VITE_SUPABASE_ANON_KEY=eyJhbGci...

curl -X POST https://bsbjwjpgiangjqqqxota.supabase.co/functions/v1/send-whatsapp \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+27835775735",
    "message": "🚨 Test from FleetOS - Twilio is working!"
  }'

Check your phone! You should get a WhatsApp message.

Part 4: Configure Twilio Webhook (5 minutes)

Step 4.1: Set Incoming Message Webhook

Twilio Console → Messaging → Settings → WhatsApp Sandbox Settings

"When a message comes in" field:

https://bsbjwjpgiangjqqqxota.supabase.co/functions/v1/whatsapp-webhook

Method: POST
Content Type: application/x-www-form-urlencoded
Click Save

Step 4.2: Test Incoming Webhook

From your phone (WhatsApp):

Send to +1 415 523 8886:

HELP

You should get back:

FleetOS Commands:
• ACK - Acknowledge latest request
• ACCEPT - Accept and start work
• DECLINE [reason] - Decline request
• HELP - Show this message

Visit fleetos.com for full dashboard.

✅ Webhook is working!

Part 5: Hook Up to Service Requests (10 minutes)

Step 5.1: Add Notification to Request Creation

File: services/shared/QueryService.ts

Find createServiceRequest() method and add after insert:

static async createServiceRequest(requestData: any) {
  // ... existing insert code ...

  if (error) throw error;

  // ✅ NEW: Trigger WhatsApp notification
  if (data && requestData.supplier_company_id) {
    // Import dynamically to avoid circular dependency
    const { RFQNotificationService } = await import('../RFQNotificationService');

    // Notify supplier org (BIBLE-compliant routing)
    await RFQNotificationService.notifyNewRequest({
      request_id: data.request_id,
      fleet_company_id: requestData.fleet_company_id,
      supplier_company_id: requestData.supplier_company_id,
      description: requestData.description,
      vehicle_identifier: requestData.vehicle_identifier,
      location: requestData.location,
      urgency: requestData.urgency || 'TODAY',
      status: data.status,
      submitted_by_contact_id: requestData.submitted_by_contact_id,
    });
  }

  return data;
}

Step 5.2: Test End-to-End Flow

Create test supplier with phone number:

-- In Supabase SQL Editor
INSERT INTO companies (company_id, domain, company_name, company_type)
VALUES (gen_random_uuid(), 'abctireshop.com', 'ABC Tire Shop', 'supplier');

INSERT INTO contacts (contact_id, company_id, contact_value, contact_type, display_name)
VALUES (
  gen_random_uuid(),
  (SELECT company_id FROM companies WHERE domain = 'abctireshop.com'),
  '+27835775735',  -- YOUR phone number!
  'phone',
  'Test Technician'
);

Create test request via dashboard or API
Check your phone! You should get WhatsApp notification
Reply "ACK" → Check database, status should update to 'acknowledged'

Part 6: Production Setup (Future)

Get Real WhatsApp Business Number

Twilio Console → Messaging → Senders → WhatsApp senders → Request to enable my Twilio numbers for WhatsApp

Fill business info form
Submit for approval (1-3 days)
Get dedicated WhatsApp number (e.g., +1 555 123 4567)

Update secret:

supabase secrets set TWILIO_WHATSAPP_FROM=whatsapp:+15551234567

Cost: ~$1/month + $0.005 per message

🧪 Testing Checklist

✅ Outgoing Messages

Twilio credentials configured in Supabase
Edge function deployed (send-whatsapp)
Test message sent successfully
Message received on phone

✅ Incoming Messages

Webhook URL configured in Twilio
Webhook function deployed (whatsapp-webhook)
"HELP" command works
"ACK" command updates database
"ACCEPT" command updates status
"DECLINE" command works

✅ End-to-End Flow

Service request created
Supplier company receives WhatsApp
Supplier replies "ACK"
Database status updates to 'acknowledged'
Fleet company notified of acknowledgment

🐛 Troubleshooting

"Twilio not configured on server"

Solution:

# Check secrets are set
supabase secrets list

# Re-deploy function
supabase functions deploy send-whatsapp

"No routing target available"

Solution:

Company needs at least one contact with phone or email
Check contacts table has record for company
Check contact_value matches phone number exactly

"Unknown phone number" from webhook

Solution:

-- Check contact exists
SELECT * FROM contacts WHERE contact_value = '+27835775735';

-- Create if missing
INSERT INTO contacts (company_id, contact_value, contact_type, display_name)
VALUES (...);

Webhook not receiving messages

Solution:

Check Twilio webhook URL is correct

Test webhook directly:

curl -X POST https://YOUR_PROJECT.supabase.co/functions/v1/whatsapp-webhook \
  -d "From=whatsapp:+27835775735&Body=HELP&MessageSid=TEST123"

Check Supabase function logs:
- Go to Supabase Dashboard → Edge Functions → whatsapp-webhook → Logs

📊 Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    FleetOS WhatsApp Flow                     │
└─────────────────────────────────────────────────────────────┘

1. OUTGOING (New Request)
   ┌──────────────┐
   │ QueryService │ Creates service_request
   └──────┬───────┘
          │
          v
   ┌────────────────────┐
   │ RFQNotificationSvc │ Triggers notification
   └──────┬─────────────┘
          │
          v
   ┌────────────────────┐
   │ NotificationService│ Org-level routing (BIBLE)
   └──────┬─────────────┘   - Contact hint? → send to contact
          │                  - Else → last active user
          v                  - Else → org default channel
   ┌──────────────────┐
   │ WhatsAppService  │ Calls Edge Function
   └──────┬───────────┘
          │
          v
   ┌──────────────────┐
   │ Edge Function    │ Calls Twilio API
   │ send-whatsapp    │
   └──────┬───────────┘
          │
          v
   ┌──────────────────┐
   │ Twilio           │ Delivers to WhatsApp
   └──────┬───────────┘
          │
          v
   📱 Supplier Phone


2. INCOMING (Reply)
   📱 Supplier Phone
          │
          v
   ┌──────────────────┐
   │ Twilio           │ Receives WhatsApp message
   └──────┬───────────┘
          │
          v
   ┌──────────────────┐
   │ Edge Function    │ Parses command (ACK/ACCEPT/DECLINE)
   │ whatsapp-webhook │ Updates service_request status
   └──────┬───────────┘ Logs event
          │
          v
   ┌──────────────────┐
   │ Database         │ service_requests, event_log updated
   └──────────────────┘
          │
          v
   ┌──────────────────┐
   │ (Future) Notify  │ Fleet gets status update
   │ Fleet Org        │
   └──────────────────┘

🎓 Key Concepts

Company-Owned Work (BIBLE Architecture)

Work belongs to COMPANIES, not individual users
Notifications route to ORG first (last-active fallback)
Any org member can act on any work
Emergency access always works

Magic Links

Org-scoped (not user-scoped)
Include companyId and rfqId in token
Valid for 7 days (org links) or 1 hour (RFQ links)
No login required

Two-Way Messaging

Outgoing: Python/Node → Supabase → Twilio → WhatsApp
Incoming: WhatsApp → Twilio → Supabase → Database
Commands parsed: ACK, ACCEPT, DECLINE, HELP

Services:

services/WhatsAppService.ts - Frontend WhatsApp wrapper
services/NotificationService.ts - Org-level routing logic
services/RFQNotificationService.ts - RFQ-specific notifications
services/shared/QueryService.ts - Database operations

Edge Functions:

supabase/functions/send-whatsapp/index.ts - Outgoing messages
supabase/functions/whatsapp-webhook/index.ts - Incoming webhook

Documentation:

docs/FLEETOS_ROUTING_ACCESS_BIBLE.md - Routing principles
docs/FLEETOS_FUNDAMENTAL_DECISION.md - Company-owned architecture
docs/setup/WHATSAPP_BACKEND_QUICKSTART.md - Original quick start

✅ Success Criteria

You've successfully set up WhatsApp when:

✅ Twilio credentials configured in Supabase
✅ Edge functions deployed and working
✅ Can send test WhatsApp message
✅ Webhook receives and processes replies
✅ Service request creation triggers notification
✅ Reply "ACK" updates database status
✅ Everything is BIBLE-compliant (org-first routing)

Questions? Check:

Twilio logs: https://console.twilio.com/us1/monitor/logs/whatsapp
Supabase logs: https://supabase.com/dashboard/project/bsbjwjpgiangjqqqxota/functions
Edge function logs: Supabase Dashboard → Edge Functions → Logs

Created: 2026-01-09 Status: Ready to implement Architecture: BIBLE-compliant (company-owned + org-first routing)

PreviousTest Matrix: Feedback Widget & Magic Link Fix NextTrue_Test_Matrix_Doc

Last updated 8 days ago

Was this helpful?

hashtag🎯 What You're Building

hashtag📋 Prerequisites

hashtagPart 1: Twilio Setup (15 minutes)

hashtagStep 1.1: Create Twilio Account

hashtagStep 1.2: Enable WhatsApp Sandbox

hashtagStep 1.3: Get Credentials

hashtagPart 2: Supabase Configuration (10 minutes)

hashtagStep 2.1: Install Supabase CLI

hashtagStep 2.2: Login & Link Project

hashtagStep 2.3: Set Twilio Secrets

hashtagPart 3: Deploy Edge Functions (5 minutes)

hashtagStep 3.1: Deploy Send Function

hashtagStep 3.2: Deploy Webhook Function

hashtagStep 3.3: Test Send Function

hashtagPart 4: Configure Twilio Webhook (5 minutes)

hashtagStep 4.1: Set Incoming Message Webhook

hashtagStep 4.2: Test Incoming Webhook

hashtagPart 5: Hook Up to Service Requests (10 minutes)

hashtagStep 5.1: Add Notification to Request Creation

hashtagStep 5.2: Test End-to-End Flow

hashtagPart 6: Production Setup (Future)

hashtagGet Real WhatsApp Business Number

hashtag🧪 Testing Checklist

hashtag✅ Outgoing Messages

hashtag✅ Incoming Messages

hashtag✅ End-to-End Flow

hashtag🐛 Troubleshooting

hashtag"Twilio not configured on server"

hashtag"No routing target available"

hashtag"Unknown phone number" from webhook

hashtagWebhook not receiving messages

hashtag📊 Architecture Overview

hashtag🎓 Key Concepts

hashtagCompany-Owned Work (BIBLE Architecture)

hashtagMagic Links

hashtagTwo-Way Messaging

hashtag📚 Related Files

hashtag✅ Success Criteria

🎯 What You're Building

📋 Prerequisites

Part 1: Twilio Setup (15 minutes)

Step 1.1: Create Twilio Account

Step 1.2: Enable WhatsApp Sandbox

Step 1.3: Get Credentials

Part 2: Supabase Configuration (10 minutes)

Step 2.1: Install Supabase CLI

Step 2.2: Login & Link Project

Step 2.3: Set Twilio Secrets

Part 3: Deploy Edge Functions (5 minutes)

Step 3.1: Deploy Send Function

Step 3.2: Deploy Webhook Function

Step 3.3: Test Send Function

Part 4: Configure Twilio Webhook (5 minutes)

Step 4.1: Set Incoming Message Webhook

Step 4.2: Test Incoming Webhook

Part 5: Hook Up to Service Requests (10 minutes)

Step 5.1: Add Notification to Request Creation

Step 5.2: Test End-to-End Flow

Part 6: Production Setup (Future)

Get Real WhatsApp Business Number

🧪 Testing Checklist

✅ Outgoing Messages

✅ Incoming Messages

✅ End-to-End Flow

🐛 Troubleshooting

"Twilio not configured on server"

"No routing target available"

"Unknown phone number" from webhook

Webhook not receiving messages

📊 Architecture Overview

🎓 Key Concepts

Company-Owned Work (BIBLE Architecture)

Magic Links

Two-Way Messaging

📚 Related Files

✅ Success Criteria