Best Aircall Phone Validation API & Sales Team Integration 2025

// Aircall API configuration
import axios from 'axios';

class AircallClient {
  constructor(apiId, apiToken) {
    this.apiId = apiId;
    this.apiToken = apiToken;
    this.baseURL = 'https://api.aircall.io/v1';
    this.headers = {
      'Authorization': `Basic ${Buffer.from(`${apiId}:${apiToken}`).toString('base64')}`,
      'Content-Type': 'application/json'
    };
  }

  async getCompany() {
    try {
      const response = await axios.get(`${this.baseURL}/company`, {
        headers: this.headers
      });
      return response.data;
    } catch (error) {
      console.error('Aircall API error:', error.response?.data || error.message);
      throw error;
    }
  }

  async getCalls(options = {}) {
    const params = new URLSearchParams({
      page: options.page || 1,
      per_page: options.per_page || 50,
      ...options.filters
    });

    const response = await axios.get(
      `${this.baseURL}/calls?${params}`,
      { headers: this.headers }
    );
    
    return response.data;
  }

  async updateCall(callId, data) {
    const response = await axios.put(
      `${this.baseURL}/calls/${callId}`,
      data,
      { headers: this.headers }
    );
    
    return response.data;
  }

  async getUsers() {
    const response = await axios.get(`${this.baseURL}/users`, {
      headers: this.headers
    });
    return response.data;
  }

  async createContact(contactData) {
    const response = await axios.post(
      `${this.baseURL}/contacts`,
      contactData,
      { headers: this.headers }
    );
    return response.data;
  }
}

const aircall = new AircallClient(
  process.env.AIRCALL_API_ID,
  process.env.AIRCALL_API_TOKEN
);

// Test the connection
const company = await aircall.getCompany();
console.log('Connected to Aircall company:', company.company.name);

// 1lookup configuration for Aircall sales teams
import { OneLookupClient } from '@1lookup/sdk';

const oneLookup = new OneLookupClient({
  apiKey: process.env.ONELOOKUP_API_KEY,
  environment: 'production',
  timeout: 3000, // Fast response for sales calls
  retryAttempts: 2,
  salesOptimization: true, // Enable sales-specific features
  leadScoringEnabled: true,
  crmIntegration: true
});

// Configure sales-specific validation parameters
const salesValidationConfig = {
  includeCarrierInfo: true,
  includeLocationInfo: true,
  includeDemographics: true,
  includeLeadScoring: true,
  includeBehavioralData: true,
  checkBusinessHours: true,
  optimizeForSales: true,
  enableCallTiming: true
};

// Verify service connectivity for sales operations
const salesHealthCheck = await oneLookup.sales.healthCheck();
console.log('1lookup sales features status:', salesHealthCheck.status);

// Initialize lead scoring model
const leadScoringModel = await oneLookup.sales.initializeScoring({
  industry: process.env.TARGET_INDUSTRY || 'technology',
  salesModel: process.env.SALES_MODEL || 'b2b',
  averageDealSize: process.env.AVG_DEAL_SIZE || 50000,
  salesCycle: process.env.SALES_CYCLE_DAYS || 45
});

console.log('Lead scoring model initialized:', leadScoringModel.version);

// Real-time Aircall call enhancement webhook
import express from 'express';
const app = express();

app.use(express.json());

// Aircall webhook endpoint for call events
app.post('/webhooks/aircall/call', async (req, res) => {
  try {
    const { event, data } = req.body;
    console.log(`Received Aircall event: ${event}`);

    // Handle different call events
    switch (event) {
      case 'call.created':
        await handleCallCreated(data);
        break;
      case 'call.answered':
        await handleCallAnswered(data);
        break;
      case 'call.ended':
        await handleCallEnded(data);
        break;
      case 'call.assigned':
        await handleCallAssigned(data);
        break;
    }

    res.status(200).json({ status: 'processed' });
    
  } catch (error) {
    console.error('Aircall webhook processing error:', error);
    res.status(500).json({ error: 'Processing failed' });
  }
});

async function handleCallCreated(callData) {
  // Validate and score the prospect immediately when call is created
  const phoneNumber = callData.raw_digits;
  if (!phoneNumber) return;

  try {
    // Get comprehensive prospect intelligence
    const intelligence = await oneLookup.sales.analyzeProspect({
      phone: phoneNumber,
      ...salesValidationConfig,
      context: {
        source: 'aircall',
        user_id: callData.user?.id,
        direction: callData.direction,
        created_at: callData.created_at
      }
    });

    // Calculate lead score for sales prioritization
    const leadScore = await calculateSalesLeadScore({
      intelligence: intelligence,
      callData: callData,
      historicalData: await getHistoricalCallData(phoneNumber)
    });

    // Update Aircall with prospect insights
    await aircall.updateCall(callData.id, {
      tags: generateCallTags(intelligence, leadScore),
      note: generateProspectNote(intelligence, leadScore)
    });

    // Notify sales team if high-value prospect
    if (leadScore > 80) {
      await notifySalesTeam({
        callId: callData.id,
        phoneNumber: phoneNumber,
        leadScore: leadScore,
        intelligence: intelligence,
        priority: 'high'
      });
    }

    // Update CRM if integration is enabled
    if (process.env.CRM_SYNC_ENABLED === 'true') {
      await syncProspectToCRM({
        phoneNumber: phoneNumber,
        intelligence: intelligence,
        leadScore: leadScore,
        aircallData: callData
      });
    }

  } catch (error) {
    console.error('Call enhancement error:', error);
  }
}

async function handleCallAnswered(callData) {
  // Provide real-time insights to the agent
  const phoneNumber = callData.raw_digits;
  
  try {
    // Get quick prospect context
    const quickInsights = await oneLookup.sales.getQuickInsights({
      phone: phoneNumber,
      includeConversationStarters: true,
      includeRiskFactors: true,
      includePreviousInteractions: true
    });

    // Send insights to agent's dashboard
    await sendAgentInsights({
      userId: callData.user?.id,
      callId: callData.id,
      insights: quickInsights,
      suggestedApproach: generateSalesApproach(quickInsights)
    });

  } catch (error) {
    console.error('Real-time insights error:', error);
  }
}

async function handleCallEnded(callData) {
  // Analyze call outcome and update scoring model
  const phoneNumber = callData.raw_digits;
  
  try {
    // Analyze call performance
    const callAnalysis = {
      duration: callData.duration,
      outcome: callData.tags?.find(tag => tag.includes('outcome')),
      answered: callData.answered,
      direction: callData.direction,
      recorded: callData.recording ? true : false
    };

    // Update lead scoring model with outcome
    await oneLookup.sales.updateScoringModel({
      phone: phoneNumber,
      outcome: callAnalysis,
      feedback: 'call_completed'
    });

    // Schedule follow-up if needed
    const followUpRecommendation = await calculateFollowUpTiming({
      callOutcome: callAnalysis,
      prospectData: await getProspectData(phoneNumber),
      salesContext: await getSalesContext(callData.user?.id)
    });

    if (followUpRecommendation.recommended) {
      await scheduleFollowUp({
        phoneNumber: phoneNumber,
        userId: callData.user?.id,
        timing: followUpRecommendation.timing,
        approach: followUpRecommendation.approach,
        priority: followUpRecommendation.priority
      });
    }

  } catch (error) {
    console.error('Call outcome analysis error:', error);
  }
}

async function calculateSalesLeadScore({ intelligence, callData, historicalData }) {
  let score = 50; // Base score

  // Phone validation quality
  if (intelligence.isValid) score += 20;
  if (intelligence.confidence > 90) score += 10;

  // Geographic targeting
  if (intelligence.locationInfo) {
    const targetRegions = process.env.TARGET_REGIONS?.split(',') || [];
    if (targetRegions.includes(intelligence.locationInfo.region)) {
      score += 15;
    }
  }

  // Business vs consumer indicators
  if (intelligence.lineType === 'business') {
    score += 25;
  } else if (intelligence.lineType === 'mobile') {
    score += 10; // Mobile can be good for decision makers
  }

  // Time-based factors
  const callHour = new Date(callData.created_at).getHours();
  if (callHour >= 9 && callHour <= 17) { // Business hours
    score += 10;
  }

  // Historical performance
  if (historicalData.previousCalls > 0) {
    if (historicalData.positiveOutcomes > 0) {
      score += 20; // Previous positive interaction
    } else {
      score -= 10; // Previous unsuccessful attempts
    }
  }

  // Fraud/spam penalty
  if (intelligence.fraudScore > 0.7) {
    score -= 30;
  }

  // Company size indicators (if available in demographics)
  if (intelligence.demographics?.companySize) {
    if (intelligence.demographics.companySize === 'enterprise') {
      score += 20;
    } else if (intelligence.demographics.companySize === 'mid-market') {
      score += 15;
    }
  }

  return Math.max(0, Math.min(100, Math.round(score)));
}

function generateCallTags(intelligence, leadScore) {
  const tags = [];
  
  // Lead quality tags
  if (leadScore > 80) tags.push('high_quality_lead');
  else if (leadScore > 60) tags.push('medium_quality_lead');
  else tags.push('low_quality_lead');

  // Validation tags
  tags.push(`validation_${intelligence.confidence > 90 ? 'high' : 'medium'}`);
  
  // Location tags
  if (intelligence.locationInfo) {
    tags.push(`location_${intelligence.locationInfo.region.toLowerCase().replace(' ', '_')}`);
  }

  // Line type tags
  tags.push(`line_type_${intelligence.lineType}`);

  // Priority tags
  if (leadScore > 75) tags.push('priority_follow_up');
  if (intelligence.fraudScore > 0.5) tags.push('fraud_risk');

  return tags;
}

function generateProspectNote(intelligence, leadScore) {
  let note = `PROSPECT INTELLIGENCE (Score: ${leadScore}/100)\n`;
  note += `Validation: ${intelligence.confidence}% confidence\n`;
  
  if (intelligence.locationInfo) {
    note += `Location: ${intelligence.locationInfo.city}, ${intelligence.locationInfo.region}\n`;
  }
  
  note += `Line Type: ${intelligence.lineType}\n`;
  note += `Carrier: ${intelligence.carrierInfo?.name || 'Unknown'}\n`;

  if (intelligence.demographics) {
    note += `Demographics: ${Object.entries(intelligence.demographics)
      .map(([key, value]) => `${key}: ${value}`)
      .join(', ')}\n`;
  }

  if (leadScore > 80) {
    note += `\n🔥 HIGH PRIORITY PROSPECT - Prioritize this call!`;
  }

  if (intelligence.fraudScore > 0.5) {
    note += `\n⚠️ Fraud Risk: ${(intelligence.fraudScore * 100).toFixed(1)}%`;
  }

  return note;
}

app.listen(3000, () => {
  console.log('Aircall webhook server running on port 3000');
});

// Power dialer optimization for Aircall
class AircallPowerDialerOptimizer {
  constructor(aircallClient, oneLookupClient) {
    this.aircall = aircallClient;
    this.lookup = oneLookupClient;
  }

  async optimizeCallList(prospectList, campaignSettings = {}) {
    console.log(`Optimizing ${prospectList.length} prospects for power dialing`);
    
    const optimizedList = [];
    const invalidNumbers = [];
    const highRiskNumbers = [];

    // Process prospects in parallel batches
    const batchSize = 50;
    for (let i = 0; i < prospectList.length; i += batchSize) {
      const batch = prospectList.slice(i, i + batchSize);
      
      const batchResults = await Promise.allSettled(
        batch.map(prospect => this.analyzeProspect(prospect, campaignSettings))
      );

      // Process batch results
      for (let j = 0; j < batchResults.length; j++) {
        const result = batchResults[j];
        const prospect = batch[j];

        if (result.status === 'fulfilled' && result.value) {
          const analysis = result.value;
          
          if (analysis.isValid && analysis.fraudScore < 0.7) {
            optimizedList.push({
              ...prospect,
              leadScore: analysis.leadScore,
              dialPriority: this.calculateDialPriority(analysis),
              optimalTiming: analysis.optimalCallTime,
              expectedConnectRate: analysis.connectProbability,
              intelligence: analysis
            });
          } else if (!analysis.isValid) {
            invalidNumbers.push({
              ...prospect,
              reason: 'invalid_number',
              errors: analysis.errors
            });
          } else {
            highRiskNumbers.push({
              ...prospect,
              reason: 'high_fraud_risk',
              fraudScore: analysis.fraudScore
            });
          }
        } else {
          // Validation failed, add to end of list with low priority
          optimizedList.push({
            ...prospect,
            leadScore: 25,
            dialPriority: 99,
            validationFailed: true
          });
        }
      }
    }

    // Sort by dial priority and optimal timing
    optimizedList.sort((a, b) => {
      // First by priority
      if (a.dialPriority !== b.dialPriority) {
        return a.dialPriority - b.dialPriority;
      }
      // Then by lead score
      return b.leadScore - a.leadScore;
    });

    // Group by optimal time zones for sequential dialing
    const timeZoneGroups = this.groupByTimeZones(optimizedList);

    return {
      optimizedList: optimizedList,
      invalidNumbers: invalidNumbers,
      highRiskNumbers: highRiskNumbers,
      timeZoneGroups: timeZoneGroups,
      summary: {
        totalProcessed: prospectList.length,
        validForDialing: optimizedList.length,
        invalid: invalidNumbers.length,
        highRisk: highRiskNumbers.length,
        expectedConnectRate: this.calculateExpectedConnectRate(optimizedList)
      }
    };
  }

  async analyzeProspect(prospect, campaignSettings) {
    try {
      // Get comprehensive prospect analysis
      const analysis = await this.lookup.sales.analyzeProspect({
        phone: prospect.phoneNumber,
        context: {
          campaign: campaignSettings.name,
          industry: campaignSettings.industry,
          territory: prospect.territory,
          source: prospect.source
        },
        includeCarrierInfo: true,
        includeLocationInfo: true,
        includeOptimalTiming: true,
        includeFraudScore: true,
        includeConnectProbability: true,
        includeDemographics: true
      });

      // Calculate lead score specific to this campaign
      const leadScore = await this.calculateCampaignLeadScore({
        prospect: prospect,
        analysis: analysis,
        campaignSettings: campaignSettings
      });

      return {
        ...analysis,
        leadScore: leadScore,
        dialPriority: this.calculateDialPriority(analysis),
        optimalCallTime: this.calculateOptimalCallTime(analysis),
        connectProbability: analysis.connectProbability || 0.5
      };

    } catch (error) {
      console.error(`Prospect analysis failed for ${prospect.phoneNumber}:`, error);
      return null;
    }
  }

  calculateDialPriority(analysis) {
    let priority = 50;

    // High-value prospects get top priority
    if (analysis.leadScore > 80) priority = 1;
    else if (analysis.leadScore > 60) priority = 2;
    else if (analysis.leadScore > 40) priority = 3;
    else priority = 4;

    // Adjust for connect probability
    if (analysis.connectProbability > 0.7) priority -= 1;
    else if (analysis.connectProbability < 0.3) priority += 1;

    // Business hours adjustment
    const currentHour = new Date().getHours();
    const prospectTimezone = analysis.locationInfo?.timezone;
    
    if (prospectTimezone) {
      const prospectHour = new Date().toLocaleString('en-US', {
        timeZone: prospectTimezone,
        hour: 'numeric',
        hour12: false
      });
      
      // If it's business hours for the prospect, increase priority
      if (prospectHour >= 9 && prospectHour <= 17) {
        priority -= 1;
      }
    }

    return Math.max(1, Math.min(99, priority));
  }

  calculateOptimalCallTime(analysis) {
    const baseTime = new Date();
    
    // Consider prospect's timezone
    if (analysis.locationInfo?.timezone) {
      const prospectTime = new Date().toLocaleString('en-US', {
        timeZone: analysis.locationInfo.timezone
      });
      
      const prospectHour = new Date(prospectTime).getHours();
      
      // If outside business hours, suggest next business day
      if (prospectHour < 9) {
        const nextCall = new Date();
        nextCall.setHours(9, 0, 0, 0);
        return nextCall;
      } else if (prospectHour >= 17) {
        const nextCall = new Date();
        nextCall.setDate(nextCall.getDate() + 1);
        nextCall.setHours(9, 0, 0, 0);
        return nextCall;
      }
    }

    // If in business hours, call now or soon
    return new Date(baseTime.getTime() + (5 * 60 * 1000)); // 5 minutes from now
  }

  async calculateCampaignLeadScore({ prospect, analysis, campaignSettings }) {
    let score = 50;

    // Base validation score
    if (analysis.isValid) score += 20;
    if (analysis.confidence > 90) score += 10;

    // Geographic targeting for campaign
    if (campaignSettings.targetRegions && analysis.locationInfo) {
      if (campaignSettings.targetRegions.includes(analysis.locationInfo.region)) {
        score += 20;
      }
    }

    // Industry targeting
    if (campaignSettings.industry && analysis.demographics?.industry) {
      if (analysis.demographics.industry === campaignSettings.industry) {
        score += 25;
      }
    }

    // Company size targeting
    if (campaignSettings.targetCompanySize && analysis.demographics?.companySize) {
      if (analysis.demographics.companySize === campaignSettings.targetCompanySize) {
        score += 15;
      }
    }

    // Historical performance for similar prospects
    const historicalPerformance = await this.getHistoricalPerformance({
      carrier: analysis.carrierInfo?.name,
      region: analysis.locationInfo?.region,
      lineType: analysis.lineType,
      campaign: campaignSettings.name
    });

    if (historicalPerformance.conversationRate > 0.3) {
      score += 15;
    }

    // Time-based scoring
    const currentHour = new Date().getHours();
    if (currentHour >= 10 && currentHour <= 16) { // Peak calling hours
      score += 10;
    }

    // Fraud penalty
    if (analysis.fraudScore > 0.5) {
      score -= Math.round(analysis.fraudScore * 40);
    }

    return Math.max(0, Math.min(100, Math.round(score)));
  }

  groupByTimeZones(prospects) {
    const groups = {};
    
    prospects.forEach(prospect => {
      const timezone = prospect.intelligence?.locationInfo?.timezone || 'Unknown';
      
      if (!groups[timezone]) {
        groups[timezone] = [];
      }
      
      groups[timezone].push(prospect);
    });

    // Sort each group by lead score
    Object.keys(groups).forEach(timezone => {
      groups[timezone].sort((a, b) => b.leadScore - a.leadScore);
    });

    return groups;
  }

  calculateExpectedConnectRate(prospects) {
    const totalConnectProbability = prospects.reduce((sum, p) => {
      return sum + (p.expectedConnectRate || 0.5);
    }, 0);
    
    return prospects.length > 0 ? (totalConnectProbability / prospects.length) : 0;
  }

  async getHistoricalPerformance(criteria) {
    // This would query your analytics database for historical performance
    // Return mock data for now
    return {
      conversationRate: 0.35,
      averageCallDuration: 120,
      conversionRate: 0.12
    };
  }
}

// Usage example
const dialerOptimizer = new AircallPowerDialerOptimizer(aircall, oneLookup);

const campaignSettings = {
  name: 'Q1 SaaS Prospects',
  industry: 'technology',
  targetRegions: ['California', 'New York', 'Texas'],
  targetCompanySize: 'mid-market'
};

const prospects = [
  { id: 1, phoneNumber: '+1234567890', name: 'John Doe', company: 'Tech Corp' },
  { id: 2, phoneNumber: '+1987654321', name: 'Jane Smith', company: 'Innovation Ltd' }
];

const optimizationResult = await dialerOptimizer.optimizeCallList(prospects, campaignSettings);
console.log('Dialing optimization complete:', optimizationResult.summary);