interface VerificationCode {
  id: string;
  value: string;
  expiresAt: Date;
  channel: 'whatsapp' | 'sms';
}

interface ChannelProvider {
  send(target: string, code: string, ttlMs: number): Promise<DeliveryReceipt>;
  supports(target: string): boolean;
}

interface DeliveryReceipt {
  messageId: string;
  status: 'queued' | 'sent' | 'failed';
  channel: 'whatsapp' | 'sms';
  timestamp: number;
}

class WhatsAppDeliveryAdapter implements ChannelProvider {
  constructor(private readonly apiClient: MetaBusinessClient) {}

  supports(target: string): boolean {
    // Validate international format and check internal opt-out registry
    return /^\\+\\d{10,15}$/.test(target) && !this.isOptedOut(target);
  }

  async send(target: string, code: string, ttlMs: number): Promise<DeliveryReceipt> {
    const templateName = 'auth_verification_v2';
    const components = [{ type: 'body', parameters: [{ type: 'text', text: code }] }];
    
    const response = await this.apiClient.messages.create({
      messaging_product: 'whatsapp',
      to: target,
      type: 'template',
      template: { name: templateName, language: { code: 'en' }, components }
    });

    return {
      messageId: response.messa

ges[0].id, status: response.messages[0].status, channel: 'whatsapp', timestamp: Date.now() }; } }

class LegacySmsAdapter implements ChannelProvider { constructor(private readonly gateway: SmsGatewayClient) {}

supports(target: string): boolean { return true; // Universal fallback }

async send(target: string, code: string, ttlMs: number): Promise<DeliveryReceipt> { const result = await this.gateway.send({ to: target, body: Your verification code is ${code}. Valid for ${ttlMs / 60000} minutes., from: process.env.REGISTERED_10DLC_SENDER });

return {
  messageId: result.sid,
  status: result.status === 'accepted' ? 'queued' : 'failed',
  channel: 'sms',
  timestamp: Date.now()
};

} }

### Step 3: Build the Routing Engine with Expiry Synchronization
The critical architectural decision is how to handle fallback timing. If WhatsApp fails and SMS arrives after the original code expires, user trust degrades. The router must regenerate or extend the code safely when falling back.

```typescript
class VerificationRouter {
  constructor(
    private readonly primary: WhatsAppDeliveryAdapter,
    private readonly fallback: LegacySmsAdapter,
    private readonly codeStore: VerificationCodeRepository
  ) {}

  async routeVerification(phoneNumber: string, ttlMs: number = 300_000): Promise<VerificationCode> {
    const codeValue = this.generateSecureCode();
    const codeRecord: VerificationCode = {
      id: crypto.randomUUID(),
      value: codeValue,
      expiresAt: new Date(Date.now() + ttlMs),
      channel: 'whatsapp'
    };

    await this.codeStore.save(codeRecord);

    try {
      const receipt = await this.primary.send(phoneNumber, codeValue, ttlMs);
      if (receipt.status === 'failed') throw new Error('Primary channel rejected');
      return codeRecord;
    } catch {
      // Fallback path: regenerate to ensure fresh expiry window
      const fallbackCode = this.generateSecureCode();
      const fallbackRecord: VerificationCode = {
        ...codeRecord,
        value: fallbackCode,
        channel: 'sms',
        expiresAt: new Date(Date.now() + ttlMs) // Reset TTL on fallback
      };

      await this.codeStore.update(codeRecord.id, fallbackRecord);
      await this.fallback.send(phoneNumber, fallbackCode, ttlMs);
      return fallbackRecord;
    }
  }

  private generateSecureCode(): string {
    return crypto.randomInt(100_000, 999_999).toString();
  }
}

Architecture Rationale

• WhatsApp First: Bypasses carrier filtering, eliminates AIT fraud, reduces cost, and satisfies encryption requirements. The 90–95 percent open rate within three minutes directly improves conversion.
• Automatic Fallback: Preserves coverage for users on feature phones, in low-data regions, or without the application installed. The fallback is not a parallel broadcast; it is a conditional trigger.
• Expiry Reset on Fallback: Prevents the "late code" UX failure. When the primary channel fails, the system issues a fresh code with a new TTL, ensuring the user has the full window to complete verification.
• Repository Decoupling: Storing codes in a dedicated repository (Redis, DynamoDB, or PostgreSQL) allows independent scaling of the verification state from the delivery providers.

Pitfall Guide

1. Asynchronous Expiry Mismatch

Explanation: Broadcasting both channels simultaneously or falling back without resetting the TTL causes the fallback code to arrive after the original expiration. Users abandon the flow, assuming the system is broken. Fix: Never parallel-broadcast. Implement sequential routing with explicit TTL regeneration on fallback. Log the fallback event separately to track primary channel health.

2. Template Approval Bottlenecks

Explanation: Meta requires pre-approved message templates for outbound authentication. Teams often build the integration first, then discover their template is stuck in review for 48–72 hours, blocking launch. Fix: Submit templates during the design phase. Use generic variable placeholders ({{1}}) and maintain a temporary SMS fallback until Meta approves the template. Keep a registry of approved template names and versions.

3. Ignoring Opt-Out Suppression

Explanation: Users can reply STOP to WhatsApp messages. Meta propagates this to your webhook, but many teams fail to persist the opt-out state. Subsequent attempts to send to opted-out numbers trigger account warnings or temporary blocks. Fix: Implement a suppression table keyed by wa_id or phone number. Check this table before every send attempt. Provide an in-app preference center to manage notification channels.

4. Hardcoding Provider Rates

Explanation: Meta's conversation-based pricing and SMS termination fees fluctuate by region and volume tier. Hardcoding rates in billing dashboards or cost calculators leads to budget overruns and inaccurate unit economics. Fix: Pull rates dynamically from provider APIs or maintain a versioned rate card in your configuration service. Implement cost tracking per verification attempt, not per message sent.

5. Missing Global Rate Limits

Explanation: Even with WhatsApp's reduced fraud surface, attackers can still abuse your endpoint to trigger high-volume template sends, incurring costs or triggering Meta's spam filters. Fix: Apply layered rate limiting: per-IP, per-phone number, and per-account. Implement exponential backoff for repeated failures. Add a lightweight challenge (CAPTCHA or device fingerprinting) before triggering the OTP flow.

6. Assuming E2EE Solves All Threats

Explanation: End-to-end encryption protects transit, but it does not prevent device compromise, social engineering, or credential stuffing. Teams sometimes relax other security controls after switching channels. Fix: Treat WhatsApp as a delivery improvement, not a complete security overhaul. Maintain device binding, anomaly detection, and step-up authentication for high-risk actions.

7. Failing to Monitor 10DLC Reputation

Explanation: When SMS is used as fallback, unregistered or poorly maintained sender IDs trigger carrier filtering. The fallback fails silently, leaving the user stranded. Fix: Register all fallback numbers under 10DLC compliance. Monitor sender reputation scores via your gateway dashboard. Implement retry logic with a secondary registered sender if the primary reputation drops below threshold.

Production Bundle

Action Checklist

• Register WhatsApp Business API account and submit authentication templates for approval
• Implement sequential routing logic with primary WhatsApp and conditional SMS fallback
• Configure shared verification code repository with TTL enforcement and fallback regeneration
• Deploy opt-out suppression registry and webhook listener for Meta delivery receipts
• Apply layered rate limiting (IP, phone, account) and lightweight challenge before OTP trigger
• Register fallback SMS numbers under 10DLC and verify sender reputation thresholds
• Instrument metrics: primary success rate, fallback trigger rate, average delivery latency, cost per verification
• Run chaos tests: simulate WhatsApp API downtime, network timeouts, and template rejections to validate fallback behavior

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Regulated Fintech / Banking	WhatsApp primary, SMS fallback disabled for auth	Compliance mandates encrypted, app-bound possession; SMS fails strong customer authentication	Higher upfront compliance cost, eliminates $71B industry fraud exposure
High-Volume Consumer App	WhatsApp primary, SMS fallback enabled	Maximizes conversion with 90%+ open rates; fallback preserves coverage for 5-10% edge cases	~85% reduction in per-message cost; scales efficiently to millions of verifications
Emerging Market Focus (Africa/SE Asia)	WhatsApp primary, lightweight SMS fallback	Highest WhatsApp penetration coincides with highest SMS pumping risk and carrier filtering	Eliminates AIT termination fees; reduces cost by 90%+ in 58% of target countries
Low-Bandwidth / Feature Phone Regions	SMS primary, WhatsApp fallback (if app detected)	Data connectivity is unreliable; SMS remains the only guaranteed delivery path	Higher per-message cost, but necessary for market coverage; monitor DND filtering closely

Configuration Template

# verification-router.config.yaml
channels:
  primary:
    type: whatsapp
    provider: meta_business_api
    template: auth_verification_v2
    timeout_ms: 5000
    retry_on_failure: false
  fallback:
    type: sms
    provider: legacy_gateway
    sender_id: ${REGISTERED_10DLC_SENDER}
    timeout_ms: 8000
    retry_on_failure: true
    max_retries: 2

lifecycle:
  ttl_ms: 300000
  regenerate_on_fallback: true
  max_attempts_per_phone: 3
  cooldown_ms: 60000

security:
  rate_limit:
    per_ip: 5
    per_phone: 3
    window_ms: 300000
  challenge_threshold: 2
  suppression_table: redis_opt_out_registry

monitoring:
  metrics:
    - primary_delivery_success
    - fallback_triggered
    - average_latency_ms
    - cost_per_verification
  alerting:
    fallback_rate_threshold: 0.15
    latency_p95_threshold_ms: 12000

Quick Start Guide

1. Initialize the Router: Deploy the VerificationRouter class with injected WhatsAppDeliveryAdapter and LegacySmsAdapter instances. Point the code repository to a low-latency store (Redis recommended).
2. Configure Templates & Numbers: Submit your WhatsApp authentication template to Meta. Register your fallback SMS number under 10DLC compliance and verify sender reputation in your gateway dashboard.
3. Wire the Auth Flow: Replace your existing OTP trigger with router.routeVerification(phoneNumber, 300000). Store the returned VerificationCode in your session or database. Validate user input against the stored value and TTL.
4. Instrument & Validate: Enable delivery receipt webhooks for both channels. Track fallback_triggered and primary_delivery_success metrics. Run a controlled load test simulating WhatsApp API timeouts to confirm fallback regeneration and TTL reset behavior.