SMS Vendor Delivery Confirmations

Overview

This document describes the SMS-based delivery confirmation system for vendors who prefer not to use email or login to a portal. Vendors can receive an SMS with a simple link that allows them to confirm deliveries with one click - no login required.

Features

• Preferred Contact Method: Vendors can choose Email, SMS, or Both for delivery confirmations
• One-Click Confirmation: SMS contains a signed URL that doesn't require authentication
• Mobile-Friendly: Simple, clean interface optimized for mobile devices
• Secure: Uses Rails signed IDs with 7-day expiration

Implementation

1. Database Migration

File: db/migrate/20251104205203_add_preferred_contact_method_to_vendors.rb

Adds preferred_contact_method field to vendors table:

• Values: 'email', 'sms', or 'both'
• Default: 'email'
• Not null

Run migration:

bin/rails db:migrate

2. Vendor Model Updates

File: app/models/vendor.rb

Added:

• CONTACT_METHODS constant
• Validation for preferred_contact_method
• Helper methods:
  • prefers_email? - Returns true if vendor wants email
  • prefers_sms? - Returns true if vendor wants SMS
  • has_valid_phone_for_sms? - Checks if phone number is valid

3. SMS Service Enhancement

File: app/services/sms_service.rb

Added send_vendor_delivery_confirmations method:

• Sends SMS to vendor with count of deliveries to confirm
• Includes shortened confirmation URL
• Message format:

  Quarry Rentals: Please confirm X delivery(ies) from MM/DD.
  Tap to confirm: https://admin.quarryrents.com/vendors/confirm_deliveries/[signed-id]
  

4. Updated Confirmation Job

File: app/jobs/send_delivery_confirmation_emails_job.rb

Now handles multiple contact methods:

• Sends email if vendor prefers_email?
• Sends SMS if vendor prefers_sms? AND has valid phone
• Can send both if vendor selected "both"
• Logs each notification method used

5. Simple Confirmation Controller

File: app/controllers/vendor_confirmations_controller.rb

Public controller (no authentication required):

• GET /vendors/confirm_deliveries/:signed_id - Shows pending deliveries
• POST /vendors/confirm_deliveries/:signed_id/:confirmation_id - Confirms delivery

Security:

• Uses Rails signed_id with 7-day expiration
• Validates vendor from signed ID
• Only shows recent pending confirmations (last 2 days)

6. Mobile-Friendly View

File: app/views/vendor_confirmations/index.html.erb

Features:

• Responsive design with Tailwind CSS
• Large "Confirm Delivery" buttons
• Shows order details (customer, address, date)
• Success state after all deliveries confirmed
• Help text with contact number

7. Updated Vendor Form

File: app/views/vendors/_form.html.erb

Added "Preferred Contact Method" dropdown with options:

• Email Only
• SMS/Text Only
• Both Email & SMS

Helper text: "How should we send delivery confirmation requests?"

8. Routes

File: config/routes.rb

Added public routes:

get "/vendors/confirm_deliveries/:signed_id", to: "vendor_confirmations#index"
post "/vendors/confirm_deliveries/:signed_id/:confirmation_id", to: "vendor_confirmations#confirm"

Usage

Setting Up a Vendor for SMS Confirmations

1. Go to vendor edit page
2. Ensure phone number is entered (e.g., (415) 555-1234)
3. Set "Preferred Contact Method" to "SMS/Text Only"
4. Save vendor

How It Works

1. Daily Job Runs (via cron at 5 PM):

   bin/rails runner "SendDeliveryConfirmationEmailsJob.perform_now"
   

2. System Creates Confirmations:

   • Finds all orders delivered yesterday
   • Groups by vendor
   • Creates DeliveryConfirmation records

3. SMS Sent (if vendor prefers SMS):

   Quarry Rentals: Please confirm 2 deliveries from 11/03.
   Tap to confirm: https://admin.quarryrents.com/vendors/confirm_deliveries/eyJfcmF...
   

4. Vendor Clicks Link:

   • Opens mobile-friendly page
   • Sees list of deliveries to confirm
   • Taps "Confirm Delivery" button for each

5. After Confirmation:

   • Order marked as delivery_confirmed_at
   • If payment captured and vendor uses ACH → ACH payment triggered automatically
   • Page updates to show success

SMS Message Example

Quarry Rentals: Please confirm 3 deliveries from 11/03.
Tap to confirm: https://admin.quarryrents.com/vendors/confirm_deliveries/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJaWt4TmpBME5EQSIsImV4cCI6IjIwMjUtMTEtMTFUMjA6NTI6MDMuODg3WiIsInB1ciI6bnVsbH19--abc123

Testing

Test SMS Confirmation Flow

# Rails console
vendor = Vendor.find_by(name: "Small Bins")
vendor.update!(phone: "(415) 555-1234", preferred_contact_method: "sms")

# Create test order and confirmation
order = Order.create!(
  vendor: vendor,
  delivery_date: Date.yesterday,
  # ... other required fields
)

confirmation = DeliveryConfirmation.create!(
  order: order,
  vendor: vendor,
  confirmation_type: "delivery",
  status: "pending"
)

# Send SMS
sms_service = SmsService.new
result = sms_service.send_vendor_delivery_confirmations(vendor, [confirmation])
puts result.inspect

Test Confirmation Page

1. Generate signed ID in console:

   vendor = Vendor.first
   signed_id = vendor.signed_id(expires_in: 7.days)
   puts "https://admin.quarryrents.com/vendors/confirm_deliveries/#{signed_id}"
   

2. Visit URL in browser

3. Click "Confirm Delivery" buttons

Configuration

Environment Variables

Required for SMS:

SIGNALWIRE_PROJECT_ID=your-project-id
SIGNALWIRE_TOKEN=your-token
SIGNALWIRE_SPACE_URL=yourspace.signalwire.com
SIGNALWIRE_FROM_NUMBER=+14157611123
APP_URL=https://admin.quarryrents.com

SignalWire Setup

1. Log into SignalWire: https://yourspace.signalwire.com
2. Navigate to Phone Numbers
3. Select your phone number
4. Configure Messaging webhook (for replies):
   • Method: POST
   • URL: https://admin.quarryrents.com/webhooks/sms

Benefits

For Non-Tech-Savvy Vendors

• ✅ No password to remember
• ✅ No portal login required
• ✅ Simple one-click confirmation
• ✅ Works on any phone
• ✅ Direct link in text message

For Quarry Rentals

• ✅ Automated confirmations
• ✅ Triggers ACH payments automatically
• ✅ Better vendor adoption
• ✅ Reduced support calls
• ✅ Faster payment processing

Workflow Integration

The SMS confirmation integrates with the ACH payment system:

1. Vendor delivers equipment
   ↓
2. Vendor receives SMS next day (5 PM)
   ↓
3. Vendor clicks link and confirms
   ↓
4. System checks: Customer payment captured? ✓
   ↓
5. ACH payment triggered for next day
   ↓
6. Vendor gets paid automatically

Troubleshooting

SMS Not Sending

1. Check vendor phone number is valid (10+ digits)
2. Verify preferred_contact_method is 'sms' or 'both'
3. Check SignalWire credentials in .env
4. Review logs: tail -f log/production.log | grep SMS

Confirmation Link Expired

Signed IDs expire after 7 days. Vendor will see:

"Invalid or expired confirmation link."

Solution: Resend confirmation by running job again or contact vendor directly.

Vendor Can't See Deliveries

Check:

1. Deliveries are from yesterday (not older)
2. Confirmations are in "pending" status
3. Confirmations were created less than 2 days ago

Future Enhancements

• [ ] SMS reply support ("CONFIRM ALL")
• [ ] Delivery photos via SMS
• [ ] Custom SMS templates per vendor
• [ ] SMS delivery reports/analytics
• [ ] Multi-language SMS support