Troubleshooting Guide

# Test webhook directly
curl -X POST https://api.goblue.app/v1/forms/YOUR_FORM_ID/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Test",
    "lastName": "User",
    "phoneNumber": "+1234567890"
  }'

// Wrong: Field name mismatch
{
  "first_name": "John",  // Underscore format
  "phoneNumber": "+1234567890"
}
// Template: Hi {{firstName}}, ...  // camelCase format

// Correct: Matching field names
{
  "firstName": "John",   // camelCase matches template
  "phoneNumber": "+1234567890"
}

# Check response time
time curl -X POST https://api.goblue.app/v1/forms/YOUR_FORM_ID/webhook \
  -H "Content-Type: application/json" \
  -d @test-data.json

// Wrong: Mismatched braces
Hi {firstName}, thanks for {{serviceType} inquiry!

// Wrong: Spaces in variable names
Hi {{first name}}, thanks for your inquiry!

// Wrong: Special characters
Hi {{firstName}}, thanks for your {{service-type}} inquiry!

// Correct: Proper syntax
Hi {{firstName}}, thanks for your {{serviceType}} inquiry!

function validateTemplate(template) {
  const variables = template.match(/\{\{([^}]+)\}\}/g) || [];
  const issues = [];
  
  variables.forEach(variable => {
    const varName = variable.replace(/\{\{|\}\}/g, '').trim();
    
    if (varName.includes(' ')) {
      issues.push(`Variable "${varName}" contains spaces`);
    }
    
    if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(varName)) {
      issues.push(`Variable "${varName}" contains invalid characters`);
    }
  });
  
  return issues;
}

Settings → Shortcuts → Advanced
✓ Allow Running Scripts
✓ Allow Sharing Large Amounts of Data  
✓ Allow Untrusted Shortcuts (if using custom shortcuts)

// Add validation in shortcut
function validateRecipient(message) {
  // Check phone number format
  if (!/^\+\d{10,15}$/.test(message.phoneNumber)) {
    throw new Error(`Invalid phone: ${message.phoneNumber}`);
  }
  
  // Verify message content matches recipient
  if (!message.content.includes(message.firstName)) {
    console.warn('Name mismatch in message');
  }
  
  return true;
}

// Add try-catch equivalent logic in shortcuts

1. Get Messages from API
2. If (No Messages Found):
   → Exit Shortcut
3. For Each Message:
   → Try: Send Message
   → If Error: Log Error, Continue to Next
4. Update Status for Successful Messages

// Check delivery patterns
const failureAnalysis = {
  androidUsers: [], // May need SMS fallback
  longMessages: [], // May be truncated or split
  internationalNumbers: [], // May have formatting issues
  blockedNumbers: [] // Recipient blocked sender
};

// Problem: Emoji causing encoding issues
Original: "Thanks for your order! 🎉"
Received: "Thanks for your order! □"

// Problem: Line breaks not preserved
Template:
Hi John,

Thanks for your inquiry.

Best regards,
Sarah

Received: "Hi John, Thanks for your inquiry. Best regards, Sarah"

// Problem: Special characters
Original: "Visit our café"
Received: "Visit our caf?"

// Sanitize message content
function sanitizeMessage(content) {
  return content
    .replace(/[^\x00-\x7F]/g, '') // Remove non-ASCII characters
    .replace(/\n\n/g, '\n') // Normalize line breaks
    .trim(); // Remove extra whitespace
}

// Test with different character sets
const testMessages = [
  'Basic ASCII text',
  'Text with émojis 🎉',
  'Multi-line\ntext\nformatting',
  'Special chars: café, naïve, résumé'
];

// Implement proper rate limiting
class RateLimiter {
  constructor(maxPerMinute = 30) {
    this.maxPerMinute = maxPerMinute;
    this.queue = [];
    this.processing = false;
  }
  
  async sendMessage(message) {
    return new Promise((resolve) => {
      this.queue.push({ message, resolve });
      this.processQueue();
    });
  }
  
  async processQueue() {
    if (this.processing || this.queue.length === 0) return;
    
    this.processing = true;
    const startTime = Date.now();
    let processedCount = 0;
    
    while (this.queue.length > 0 && processedCount < this.maxPerMinute) {
      const { message, resolve } = this.queue.shift();
      
      try {
        await this.actualSendMessage(message);
        resolve({ success: true });
      } catch (error) {
        resolve({ success: false, error });
      }
      
      processedCount++;
      
      // Add small delay between messages
      await new Promise(r => setTimeout(r, 2000)); // 2 seconds
    }
    
    this.processing = false;
    
    // If more messages in queue, schedule next batch
    if (this.queue.length > 0) {
      const elapsed = Date.now() - startTime;
      const waitTime = Math.max(0, 60000 - elapsed); // Wait until next minute
      setTimeout(() => this.processQueue(), waitTime);
    }
  }
}

// Phone number format variations
const variations = [
  '+1234567890',
  '1234567890', 
  '(123) 456-7890',
  '123-456-7890',
  '123.456.7890'
];
// All should be normalized to same format

function normalizePhoneNumber(phone) {
  // Remove all non-digit characters except +
  let normalized = phone.replace(/[^\d+]/g, '');
  
  // Add country code if missing
  if (!normalized.startsWith('+')) {
    if (normalized.length === 10) {
      normalized = '+1' + normalized; // US default
    } else if (normalized.length === 11 && normalized.startsWith('1')) {
      normalized = '+' + normalized;
    }
  }
  
  return normalized;
}

// Use normalized phone as unique identifier
const normalizedPhone = normalizePhoneNumber(webhookData.phoneNumber);

function validateContactData(data) {
  const errors = [];
  
  // Required fields
  if (!data.phoneNumber) {
    errors.push('Phone number is required');
  }
  
  // Phone number format
  if (data.phoneNumber && !/^\+\d{10,15}$/.test(data.phoneNumber)) {
    errors.push('Invalid phone number format');
  }
  
  // Name validation
  if (data.firstName && data.firstName.length > 50) {
    errors.push('First name too long');
  }
  
  // Email validation
  if (data.email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
    errors.push('Invalid email format');
  }
  
  return errors;
}

// Check if status updates are being sent
async function debugStatusUpdate(contactId, newStatus) {
  try {
    const response = await fetch(`/api/contacts/${contactId}`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ status: newStatus })
    });
    
    if (!response.ok) {
      console.error('Status update failed:', response.statusText);
      return false;
    }
    
    const updated = await response.json();
    console.log('Status updated:', updated);
    return true;
  } catch (error) {
    console.error('Status update error:', error);
    return false;
  }
}

async function monitorQueueHealth() {
  const queueStats = await getQueueStatistics();
  
  const warnings = [];
  
  if (queueStats.queuedMessages > 1000) {
    warnings.push('High queue volume detected');
  }
  
  if (queueStats.averageProcessingTime > 300) { // 5 minutes
    warnings.push('Slow processing detected');
  }
  
  if (queueStats.failureRate > 0.05) { // 5%
    warnings.push('High failure rate detected');
  }
  
  return warnings;
}

# Test API key validity
curl -I https://api.goblue.app/v1/messages/YOUR_API_KEY

# Expected: 200 OK
# If 401: Invalid API key
# If 403: Key lacks permissions

async function checkAccountLimits() {
  const usage = await getAccountUsage();
  
  const warnings = [];
  
  if (usage.messages / usage.messageLimit > 0.9) {
    warnings.push('Approaching monthly message limit');
  }
  
  if (usage.forms >= usage.formLimit) {
    warnings.push('Maximum forms limit reached');
  }
  
  return warnings;
}

class NetworkDiagnostics {
  async testConnectivity() {
    const tests = [
      { name: 'GoBlue API', url: 'https://api.goblue.app/health' },
      { name: 'DNS Resolution', url: 'https://8.8.8.8' },
      { name: 'General Internet', url: 'https://google.com' }
    ];
    
    const results = [];
    
    for (const test of tests) {
      const start = Date.now();
      try {
        const response = await fetch(test.url, { 
          method: 'HEAD',
          timeout: 10000 
        });
        
        results.push({
          name: test.name,
          success: response.ok,
          responseTime: Date.now() - start,
          status: response.status
        });
      } catch (error) {
        results.push({
          name: test.name,
          success: false,
          error: error.message,
          responseTime: Date.now() - start
        });
      }
    }
    
    return results;
  }
}