Best RingCentral Phone Validation API & SMS Verification Integration 2025

// Bulk validation for enterprise contact lists
async function bulkValidateContacts(contactList, batchSize = 1000) {
  const results = [];
  const batches = [];
  
  // Split contacts into batches
  for (let i = 0; i < contactList.length; i += batchSize) {
    batches.push(contactList.slice(i, i + batchSize));
  }

  for (const batch of batches) {
    try {
      // Validate batch using 1lookup bulk API
      const validation = await oneLookup.phone.validateBulk({
        phones: batch.map(contact => ({
          phone: contact.phoneNumber,
          id: contact.id,
          metadata: { 
            source: contact.source,
            campaign: contact.campaignId 
          }
        })),
        includeCarrierInfo: true,
        includeTCPAInfo: true,
        includeRiskScore: true
      });

      // Process results
      validation.results.forEach(result => {
        const contact = batch.find(c => c.id === result.id);
        
        // Create RingCentral contact if valid
        if (result.isValid && result.riskScore < 0.3) {
          results.push({
            ...contact,
            validatedPhone: result.e164Format,
            carrierInfo: result.carrierInfo,
            tcpaCompliant: result.tcpaInfo.isCompliant,
            status: 'valid'
          });
        } else {
          results.push({
            ...contact,
            status: 'invalid',
            reason: result.errors || 'High risk score'
          });
        }
      });

      // Rate limiting delay
      await new Promise(resolve => setTimeout(resolve, 100));

    } catch (error) {
      console.error(`Batch validation error: ${error.message}`);
    }
  }

  // Import valid contacts to RingCentral
  const validContacts = results.filter(r => r.status === 'valid');
  await importToRingCentral(validContacts);

  return {
    total: contactList.length,
    valid: validContacts.length,
    invalid: results.length - validContacts.length,
    results: results
  };
}

// Import contacts to RingCentral directory
async function importToRingCentral(contacts) {
  for (const contact of contacts) {
    try {
      await rcsdk.platform().post('/restapi/v1.0/account/~/directory/contacts', {
        firstName: contact.firstName,
        lastName: contact.lastName,
        businessPhone: contact.validatedPhone,
        email: contact.email,
        company: contact.company,
        jobTitle: contact.title,
        notes: `Validated: ${new Date().toISOString()}\nCarrier: ${contact.carrierInfo.name}`
      });
    } catch (error) {
      console.error(`Failed to import contact ${contact.id}: ${error.message}`);
    }
  }
}

// Intelligent call routing with validation
class IntelligentCallRouter {
  constructor(ringcentralSDK, onelookupClient) {
    this.rc = ringcentralSDK;
    this.lookup = onelookupClient;
    this.routingRules = {
      'verizon': { priority: 1, timeout: 30 },
      'att': { priority: 2, timeout: 25 },
      'tmobile': { priority: 3, timeout: 20 },
      'sprint': { priority: 4, timeout: 15 },
      'default': { priority: 5, timeout: 10 }
    };
  }

  async routeCall(phoneNumber, agentPool, campaignType) {
    try {
      // 1. Validate and analyze the phone number
      const analysis = await this.lookup.phone.analyze({
        phone: phoneNumber,
        includeCarrierInfo: true,
        includeLocationInfo: true,
        includeRiskAssessment: true,
        includeBehavioralData: true
      });

      if (!analysis.isValid) {
        return { success: false, reason: 'Invalid phone number' };
      }

      // 2. Get routing strategy based on carrier
      const carrier = analysis.carrierInfo.name.toLowerCase();
      const routing = this.routingRules[carrier] || this.routingRules.default;

      // 3. Select optimal agent based on carrier and location
      const agent = await this.selectAgent(agentPool, {
        carrier: carrier,
        timezone: analysis.locationInfo.timezone,
        riskScore: analysis.riskScore,
        campaignType: campaignType
      });

      // 4. Configure call parameters
      const callConfig = {
        from: { phoneNumber: agent.phoneNumber },
        to: { phoneNumber: analysis.e164Format },
        callerId: { phoneNumber: agent.callerIdNumber },
        timeout: routing.timeout,
        recordCall: campaignType === 'sales',
        playPrompt: analysis.riskScore > 0.5,
        metadata: {
          validationId: analysis.id,
          carrier: carrier,
          riskScore: analysis.riskScore,
          agentId: agent.id
        }
      };

      // 5. Initiate the call
      const call = await this.rc.platform().post('/restapi/v1.0/account/~/extension/~/ring-out', callConfig);

      // 6. Track call metrics
      await this.trackCallMetrics({
        callId: call.json().id,
        phoneNumber: phoneNumber,
        carrier: carrier,
        agent: agent.id,
        validationData: analysis
      });

      return {
        success: true,
        callId: call.json().id,
        agent: agent,
        routing: routing,
        validationData: analysis
      };

    } catch (error) {
      console.error('Call routing error:', error);
      return { success: false, reason: error.message };
    }
  }

  async selectAgent(agentPool, criteria) {
    // AI-powered agent selection algorithm
    const scoredAgents = agentPool.map(agent => {
      let score = 0;

      // Carrier expertise bonus
      if (agent.carrierExpertise.includes(criteria.carrier)) {
        score += 10;
      }

      // Timezone compatibility
      const timezoneScore = this.calculateTimezoneScore(agent.timezone, criteria.timezone);
      score += timezoneScore * 5;

      // Risk handling capability
      if (criteria.riskScore > 0.7 && agent.riskHandlingExperience > 0.8) {
        score += 15;
      }

      // Campaign type expertise
      if (agent.campaignExpertise.includes(criteria.campaignType)) {
        score += 8;
      }

      // Current availability
      if (agent.status === 'available') {
        score += 20;
      } else if (agent.status === 'busy' && agent.queuePosition < 3) {
        score += 10;
      }

      return { ...agent, score };
    });

    // Return highest scoring available agent
    return scoredAgents
      .sort((a, b) => b.score - a.score)
      .find(agent => agent.status === 'available' || agent.queuePosition < 5);
  }

  calculateTimezoneScore(agentTZ, customerTZ) {
    const agentHour = new Date().toLocaleString('en-US', { timeZone: agentTZ, hour: 'numeric', hour12: false });
    const customerHour = new Date().toLocaleString('en-US', { timeZone: customerTZ, hour: 'numeric', hour12: false });
    
    const hourDiff = Math.abs(parseInt(agentHour) - parseInt(customerHour));
    
    // Best score for same timezone, decreasing score for larger differences
    return Math.max(0, 10 - hourDiff);
  }

  async trackCallMetrics(callData) {
    // Store call metrics for analytics
    await this.rc.platform().post('/restapi/v1.0/account/~/call-log', {
      ...callData,
      timestamp: new Date().toISOString(),
      source: '1lookup-integration'
    });
  }
}

// Usage example
const router = new IntelligentCallRouter(rcsdk, oneLookup);
const result = await router.routeCall('+1234567890', agentPool, 'sales');