Skip to main content

Twilio Configuration Error Fix

Date: October 25, 2025
Branch: communication-phase-6
Issue: Cloud Run backend throwing repeated Twilio configuration errors

Problem​

The backend service in Cloud Run was throwing repeated errors:

Error: Twilio is not configured. Please set TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN.

Root Cause​

  1. SMS/WhatsApp/Messenger messages were being queued for delivery
  2. When the communication queue processor tried to send them, it checked if Twilio was configured
  3. Since Twilio credentials were not set in the Cloud Run environment, the send failed
  4. The queue retried the failed messages with exponential backoff (1min, 5min, 15min, 1hour)
  5. This created repeated error logs in Cloud Run

Why This Happened​

The system was designed with a "fail-open" approach where channels could be configured later. However, there was no validation before queuing messages to ensure the provider was available. This meant:

  • Messages could be queued even if the channel wasn't configured
  • Errors only appeared during processing
  • Failed messages were retried unnecessarily

Solution Implemented​

Changes Made​

File: apps/backend/src/communications/application/communications.service.ts

  1. Added TwilioProvider Injection

    • Injected TwilioProvider into the CommunicationsService constructor
    • This allows checking Twilio configuration before queuing messages

  2. Added Provider Validation

    • Created validateChannelProvider() private method
    • Checks if Twilio is configured for SMS/WhatsApp/Messenger channels
    • Throws a clear error if the provider is not configured
    • Called at the start of the send() method (Step 1)

  3. User-Friendly Error Messages

    • If a channel is not configured, users get a clear message:

      SMS channel is not configured. Please contact your system administrator to enable SMS communications.

How It Works Now​

async send(data: SendCommunicationDto) {
  // 1. Check if channel provider is configured (NEW!)
  this.validateChannelProvider(data.channel);
  
  // 2. Check preferences
  // 3. Fetch template
  // 4. Validate content
  // 5. Validate attachments
  // 6. Create communication record
  // 7. Save attachments
  // 8. Enqueue for sending
}

The validation happens before the message is queued, preventing:

  • Unnecessary database writes
  • Queue processing overhead
  • Retry attempts
  • Error log spam

Next Steps​

If you want to enable SMS/WhatsApp communications:

  1. Get Twilio Credentials

  2. Set Environment Variables in Cloud Run

    gcloud run services update flowpos-backend \
      --region us-central1 \
      --update-env-vars TWILIO_ACCOUNT_SID=your_account_sid,TWILIO_AUTH_TOKEN=your_auth_token,TWILIO_PHONE_NUMBER=your_twilio_number

  3. For WhatsApp (optional)

    gcloud run services update flowpos-backend \
      --region us-central1 \
      --update-env-vars TWILIO_WHATSAPP_NUMBER=your_whatsapp_number

  4. For Messaging Service (optional, alternative to phone number)

    gcloud run services update flowpos-backend \
      --region us-central1 \
      --update-env-vars TWILIO_MESSAGING_SERVICE_SID=your_messaging_service_sid

Option B: Disable SMS/WhatsApp Channels​

If you don't need these channels:

  1. Use Business Communication Configuration

    • SMS and WhatsApp are disabled by default in business configs
    • Make sure your business configurations have isEnabled: false for these channels
    • No additional action needed if you're using the default configuration

  2. Verify Configuration

    curl https://your-api-url/business-communication-config?businessId=YOUR_BUSINESS_ID

Prevention​

The fix prevents future errors by:

  1. Early Validation - Checks provider configuration before queuing
  2. Clear Errors - Users get actionable error messages
  3. No Retries - Failed validation doesn't enter the retry loop
  4. Logging - Warning logs when unconfigured channels are attempted

Testing​

To test the fix:

  1. With Twilio Configured

    # SMS should work
    curl -X POST https://your-api-url/communications/send \
      -H "Content-Type: application/json" \
      -d '{
        "channel": "sms",
        "recipientContact": "+1234567890",
        "content": "Test message",
        "type": "general_notification"
      }'

  2. Without Twilio Configured

    # Should fail fast with clear error message
    # No queue processing, no retries, no error log spam
  • apps/backend/src/communications/application/communications.service.ts - Main fix
  • apps/backend/src/communications/infrastructure/providers/twilio.provider.ts - Provider configuration
  • apps/backend/src/communications/application/adapters/sms-adapter.service.ts - SMS adapter
  • apps/backend/src/communication-queue/application/communication-queue.service.ts - Queue processor

Additional Notes​

Email Channel​

Email does not require special configuration checks as it uses the built-in email provider (Resend/SendGrid) which should always be configured.

Future Channels​

When adding new communication channels:

  1. Add provider configuration check to TwilioProvider or create new provider
  2. Update validateChannelProvider() method to check the new channel
  3. Follow the same pattern: validate before queuing

Monitoring​

To monitor communication health:

-- Check failed communications
SELECT channel, type, status, error_message, COUNT(*)
FROM communication
WHERE status = 'failed'
  AND created_at > NOW() - INTERVAL '24 hours'
GROUP BY channel, type, status, error_message;

-- Check queue status
SELECT status, COUNT(*), AVG(attempts)
FROM communication_queue
WHERE status IN ('pending', 'failed')
GROUP BY status;

References​