// server.js - Production webhook handler
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// Webhook signature validation (REQUIRED - prevents replay attacks)
function validateVapiSignature(req) {
  const signature = req.headers['x-vapi-signature'];
  const payload = JSON.stringify(req.body);
  const hash = crypto.createHmac('sha256', process.env.VAPI_SERVER_SECRET)
    .update(payload)
    .digest('hex');
  return signature === hash;
}

app.post('/webhook/vapi', async (req, res) => {
  if (!validateVapiSignature(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  const { message } = req.body;
  
  // Acknowledge immediately (VAPI times out after 5s)
  res.status(200).json({ received: true });
  
  // Process async to avoid timeout
  processVapiEvent(message).catch(console.error);
});

async function processVapiEvent(message) {
  if (message.type === 'function-call') {
    const result = await handleSalesforceQuery(message.functionCall);
    // Return result via VAPI's server message endpoint
    // Note: Endpoint inferred from standard webhook callback patterns
    await fetch(`https://api.vapi.ai/call/${message.call.id}/messages`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.VAPI_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        type: 'function-result',
        functionCallId: message.functionCall.id,
        result: result
      })
    });
  }
}

let salesforceToken = null;
let tokenExpiry = 0;

async function getSalesforceToken() {
  if (salesforceToken && Date.now() < tokenExpiry) {
    return salesforceToken;
  }
  
  // Salesforce OAuth endpoint (NOT a VAPI endpoint)
  const response = await fetch('https://login.salesforce.com/services/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.SALESFORCE_CLIENT_ID,
      client_secret: process.env.SALESFORCE_CLIENT_SECRET
    })
  });
  
  const data = await response.json();
  salesforceToken = data.access_token;
  tokenExpiry = Date.now() + (data.expires_in * 1000) - 60000; // 1min buffer
  return salesforceToken;
}

async function handleSalesforceQuery(functionCall) {
  const token = await getSalesforceToken();
  const { customerEmail } = functionCall.parameters;
  
  // Salesforce REST API query
  const query = `SELECT Id, Name, Email, Phone, Status__c FROM Contact WHERE Email = '${customerEmail}'`;
  const response = await fetch(
    `https://yourinstance.salesforce.com/services/data/v58.0/query?q=${encodeURIComponent(query)}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`Salesforce API error: ${response.status}`);
  }
  
  const result = await response.json();
  return result.records[0] || { error: 'Customer not found' };
}

graph LR
    A[Microphone] --> B[Audio Buffer]
    B --> C[Voice Activity Detection]
    C -->|Speech Detected| D[Speech-to-Text]
    C -->|Silence| E[Error Handling]
    D --> F[Intent Detection]
    F --> G[Response Generation]
    G --> H[Text-to-Speech]
    H --> I[Speaker]
    E -->|Retry| B
    E -->|Fail| J[Log Error]
    J -->|Notify| K[User Notification]

// Test webhook signature validation locally
const testPayload = {
  message: {
    type: "function-call",
    functionCall: {
      name: "handleSalesforceQuery",
      parameters: { query: "test query" }
    }
  }
};

const testSignature = crypto
  .createHmac('sha256', process.env.VAPI_SERVER_SECRET)
  .update(JSON.stringify(testPayload))
  .digest('hex');

// Simulate Vapi webhook call
fetch('http://localhost:3000/webhook/vapi', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-vapi-signature': testSignature
  },
  body: JSON.stringify(testPayload)
}).then(response => {
  if (!response.ok) throw new Error(`Validation failed: ${response.status}`);
  console.log('Webhook validation passed');
});

curl -X POST http://localhost:3000/webhook/vapi \
  -H "Content-Type: application/json" \
  -H "x-vapi-signature: YOUR_TEST_SIGNATURE" \
  -d '{"message":{"type":"function-call","functionCall":{"name":"handleSalesforceQuery","parameters":{"query":"test"}}}}'

// Configure barge-in in assistant config (native handling)
const assistantConfig = {
  model: {
    provider: "openai",
    model: "gpt-4"
  },
  voice: {
    provider: "11labs",
    voiceId: "21m00Tcm4TlvDq8ikWAM"
  },
  transcriber: {
    provider: "deepgram",
    model: "nova-2",
    language: "en",
    endpointing: 200 // ms of silence before turn ends
  },
  // Barge-in handled natively - DO NOT write manual cancellation
  backgroundSound: "office" // Reduces false positives from ambient noise
};

// YOUR server receives this at /webhook/vapi
app.post('/webhook/vapi', async (req, res) => {
  const payload = req.body;
  
  if (payload.message.type === 'transcript') {
    console.log(`[${new Date().toISOString()}] Partial: "${payload.message.transcript}"`);
    // 2024-01-15T14:23:41.234Z Partial: "I just want the track"
    // 2024-01-15T14:23:41.456Z Partial: "I just want the tracking number"
  }
  
  if (payload.message.type === 'function-call') {
    const { name, parameters } = payload.message.functionCall;
    
    if (name === 'handleSalesforceQuery') {
      const salesforceToken = await getSalesforceToken();
      const result = await fetch(`https://yourinstance.salesforce.com/services/data/v58.0/query?q=${encodeURIComponent(parameters.query)}`, {
        headers: { 'Authorization': `Bearer ${salesforceToken}` }
      });
      const data = await result.json();
      
      return res.json({ result: data.records[0].TrackingNumber__c });
    }
  }
  
  res.sendStatus(200);
});

// WRONG: No lock mechanism
async function handleSalesforceQuery(query) {
  if (Date.now() > tokenExpiry) {
    salesforceToken = await getSalesforceToken(); // 800ms+ refresh
  }
  // Race: Another call might hit here while token is refreshing
  const response = await fetch(`https://yourinstance.salesforce.com/services/data/v52.0/query?q=${query}`, {
    headers: { 'Authorization': `Bearer ${salesforceToken}` }
  });
  return response.json();
}

// CORRECT: Token refresh lock with queue
let isRefreshing = false;
let refreshQueue = [];

async function handleSalesforceQuery(query) {
  if (Date.now() > tokenExpiry) {
    if (isRefreshing) {
      // Wait for ongoing refresh instead of starting a new one
      return new Promise((resolve) => {
        refreshQueue.push(async () => {
          const result = await executeSalesforceQuery(query);
          resolve(result);
        });
      });
    }
    isRefreshing = true;
    salesforceToken = await getSalesforceToken();
    tokenExpiry = Date.now() + 3600000;
    isRefreshing = false;
    // Process queued requests
    refreshQueue.forEach(fn => fn());
    refreshQueue = [];
  }
  return executeSalesforceQuery(query);
}

async function executeSalesforceQuery(query) {
  const response = await fetch(`https://yourinstance.salesforce.com/services/data/v52.0/query?q=${query}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${salesforceToken}`,
      'Content-Type': 'application/json'
    }
  });
  if (!response.ok) throw new Error(`Salesforce API error: ${response.status}`);
  return response.json();
}

// Add timestamp validation to catch clock drift
function validateVapiSignature(payload, signature) {
  const hash = crypto
    .createHmac('sha256', process.env.VAPI_SERVER_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  // Check for clock drift (VAPI timestamps are UTC)
  const serverTime = Date.now();
  const vapiTime = new Date(payload.timestamp).getTime();
  const drift = Math.abs(serverTime - vapiTime);
  
  if (drift > 30000) { // 30 second threshold
    console.error(`Clock drift detected: ${drift}ms. Sync your server clock.`);
    // Still validate signature, but log the drift
  }
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(hash)
  );
}

// Implement request batching and caching
const salesforceCache = new Map();
const CACHE_TTL = 300000; // 5 minutes

async function handleSalesforceQuery(query) {
  const cacheKey = query;
  const cached = salesforceCache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data; // Avoid redundant API call
  }
  
  try {
    const response = await fetch(`https://yourinstance.salesforce.com/services/data/v52.0/query?q=${encodeURIComponent(query)}`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${salesforceToken}`,
        'Content-Type': 'application/json'
      },
      timeout: 4000 // Leave 1s buffer for VAPI's 5s limit
    });
    
    if (response.status === 403) {
      const error = await response.json();
      if (error[0]?.errorCode === 'REQUEST_LIMIT_EXCEEDED') {
        // Fallback: Return cached data even if stale
        if (cached) return cached.data;
        throw new Error('Salesforce rate limit exceeded. Upgrade to Enterprise Edition.');
      }
    }
    
    const data = await response.json();
    salesforceCache.set(cacheKey, { data, timestamp: Date.now() });
    return data;
  } catch (error) {
    console.error('Salesforce query failed:', error);
    throw error;
  }
}

// server.js - Production Salesforce + VAPI Integration
const express = require('express');
const crypto = require('crypto');
const fetch = require('node-fetch');

const app = express();
app.use(express.json());

// Salesforce OAuth Configuration
const SF_CLIENT_ID = process.env.SALESFORCE_CLIENT_ID;
const SF_CLIENT_SECRET = process.env.SALESFORCE_CLIENT_SECRET;
const SF_REDIRECT_URI = process.env.SALESFORCE_REDIRECT_URI; // https://yourdomain.com/oauth/callback
const SF_LOGIN_URL = 'https://login.salesforce.com';

// Token Management (in-memory - use Redis in production)
let salesforceToken = null;
let tokenExpiry = 0;
let isRefreshing = false;
let refreshQueue = [];

// Salesforce Query Cache
const salesforceCache = new Map();
const CACHE_TTL = 300000; // 5 minutes

// OAuth Flow - Step 1: Redirect to Salesforce
app.get('/oauth/login', (req, res) => {
  const authUrl = `${SF_LOGIN_URL}/services/oauth2/authorize?` +
    `response_type=code&client_id=${SF_CLIENT_ID}&redirect_uri=${encodeURIComponent(SF_REDIRECT_URI)}`;
  res.redirect(authUrl);
});

// OAuth Flow - Step 2: Handle Callback
app.get('/oauth/callback', async (req, res) => {
  const { code } = req.query;
  if (!code) return res.status(400).send('Missing authorization code');

  try {
    const response = await fetch(`${SF_LOGIN_URL}/services/oauth2/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'authorization_code',
        code: code,
        client_id: SF_CLIENT_ID,
        client_secret: SF_CLIENT_SECRET,
        redirect_uri: SF_REDIRECT_URI
      })
    });

    if (!response.ok) throw new Error(`OAuth failed: ${response.status}`);
    
    const data = await response.json();
    salesforceToken = data.access_token;
    tokenExpiry = Date.now() + (data.expires_in * 1000);
    
    res.send('✅ Salesforce connected! Token expires in ' + data.expires_in + ' seconds');
  } catch (error) {
    console.error('OAuth Error:', error);
    res.status(500).send('OAuth failed: ' + error.message);
  }
});

// Token Refresh with Queue (prevents race conditions)
async function getSalesforceToken() {
  if (salesforceToken && Date.now() < tokenExpiry - 60000) {
    return salesforceToken; // Token valid for >1 minute
  }

  // Queue concurrent requests during refresh
  if (isRefreshing) {
    return new Promise((resolve, reject) => {
      refreshQueue.push({ resolve, reject });
    });
  }

  isRefreshing = true;
  try {
    const response = await fetch(`${SF_LOGIN_URL}/services/oauth2/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: process.env.SALESFORCE_REFRESH_TOKEN,
        client_id: SF_CLIENT_ID,
        client_secret: SF_CLIENT_SECRET
      })
    });

    if (!response.ok) throw new Error(`Token refresh failed: ${response.status}`);
    
    const data = await response.json();
    salesforceToken = data.access_token;
    tokenExpiry = Date.now() + (data.expires_in * 1000);

    // Resolve queued requests
    refreshQueue.forEach(({ resolve }) => resolve(salesforceToken));
    refreshQueue = [];
    
    return salesforceToken;
  } catch (error) {
    refreshQueue.forEach(({ reject }) => reject(error));
    refreshQueue = [];
    throw error;
  } finally {
    isRefreshing = false;
  }
}

// VAPI Webhook Signature Validation
function validateVapiSignature(payload, signature) {
  const hash = crypto
    .createHmac('sha256', process.env.VAPI_SERVER_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signature));
}

// Salesforce Query Executor with Caching
async function executeSalesforceQuery(query) {
  const cacheKey = query;
  const cached = salesforceCache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data; // Return cached result
  }

  const token = await getSalesforceToken();
  const response = await fetch(
    `${process.env.SALESFORCE_INSTANCE_URL}/services/data/v58.0/query?q=${encodeURIComponent(query)}`,
    {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Salesforce query failed: ${response.status} - ${error}`);
  }

  const data = await response.json();
  salesforceCache.set(cacheKey, { data, timestamp: Date.now() });
  
  return data;
}

// VAPI Webhook Handler
app.post('/webhook/vapi', async (req, res) => {
  const signature = req.headers['x-vapi-signature'];
  const payload = req.body;

  // Validate webhook signature
  if (!validateVapiSignature(payload, signature)) {
    console.error('Invalid webhook signature');
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { type, functionCall, call } = payload.message || {};

  // Handle function calls from VAPI assistant
  if (type === 'function-call' && functionCall) {
    try {
      const { name, parameters } = functionCall;

      if (name === 'querySalesforce') {
        const { query } = parameters;
        const result = await executeSalesforceQuery(query);
        
        // Return formatted response to VAPI
        return res.json({
          results: [{
            toolCallId: functionCall.id,
            result: JSON.stringify({
              totalSize: result.totalSize,
              records: result.records.slice(0, 5) // Limit to 5 records for voice
            })
          }]
        });
      }

      return res.status(400).json({ error: 'Unknown function: ' + name });
    } catch (error) {
      console.error('Function execution error:', error);
      return res.json({
        results: [{
          toolCallId: functionCall.id,
          result: JSON.stringify({ error: error.message })
        }]
      });
    }
  }

  // Log other webhook events
  console.log('VAPI Event:', type, call?.id);
  res.sendStatus(200);
});

// Health Check
app.get('/health', (req, res) => {
  const tokenValid = salesforceToken && Date.now() < tokenExpiry;
  res.json({
    status: 'ok',
    salesforce: tokenValid

## FAQ

## Technical Questions

**How do I authenticate VAPI calls to Salesforce without exposing API keys?**

Use OAuth 2.0 with the `authorization_code` grant type. Store `salesforceToken` and `tokenExpiry` server-side, never in client code. When the token expires, call `getSalesforceToken()` to refresh before making Salesforce queries. VAPI sends webhook events to your server; your server handles Salesforce auth. Never pass Salesforce credentials through VAPI's assistant config—only pass the webhook URL and function definitions.

**What happens if VAPI's webhook times out while querying Salesforce?**

VAPI retries the webhook 3 times over 15 seconds. If your Salesforce query takes longer than 5 seconds, the call drops. Use async processing: have your webhook return immediately with a queued status, then update the call state via VAPI's callback API once Salesforce responds. This prevents timeout failures on slow CRM queries.

**Can I use the same VAPI assistant for multiple Salesforce orgs?**

Yes, but pass org-specific metadata in the call config. Include `organizationId` in the call's metadata object, then use it in your webhook handler to route to the correct Salesforce instance. Store separate OAuth tokens per org in your database, keyed by `organizationId`. This avoids hardcoding org details in the assistant config.

## Performance

**How do I reduce latency when VAPI queries Salesforce?**

Cache frequently accessed data (accounts, contacts, case statuses) with a `CACHE_TTL` of 5-10 minutes. Check `salesforceCache` before making API calls. For real-time data (case updates), query Salesforce directly but use connection pooling to reduce handshake overhead. VAPI's STT-to-response latency is typically 800-1200ms; Salesforce queries add 200-600ms depending on network and query complexity.

**What's the maximum number of concurrent VAPI calls querying Salesforce?**

Salesforce API rate limits are 15,000 requests per 24 hours for most orgs. If you run 100 concurrent calls, each making 2 Salesforce queries, you'll hit limits in ~75 minutes. Implement request queuing: batch queries, use Salesforce's bulk API for large datasets, and monitor rate limit headers (`Sforce-Limit-Info`). Set up alerts when usage exceeds 80% of daily quota.

## Platform Comparison

**Should I use VAPI or Twilio for Salesforce voice integration?**

VAPI handles AI orchestration (STT, LLM, TTS) natively; Twilio handles call routing and PSTN connectivity. Use both: Twilio receives inbound calls, routes to VAPI for AI processing, and VAPI's webhooks query Salesforce. VAPI is faster for AI-driven interactions (200-400ms response time); Twilio excels at call management and compliance (call recording, HIPAA). Don't replace one with the other—they're complementary.

**Can I integrate Salesforce directly with Twilio without VAPI?**

Yes, but you'll build the AI layer yourself. Twilio's Studio flows can call Salesforce APIs, but you lose real-time LLM reasoning. VAPI adds intelligence: it understands context, handles interruptions, and makes dynamic decisions. For simple IVR (press 1 for sales), Twilio alone works. For natural conversations that query CRM data, add VAPI.

## Resources

**Twilio**: Get Twilio Voice API → [https://www.twilio.com/try-twilio](https://www.twilio.com/try-twilio)

**VAPI Documentation:** [Official API Reference](https://docs.vapi.ai) – Voice call setup, assistant configuration, webhook events, function calling.

**Salesforce REST API:** [Salesforce Developer Docs](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/) – OAuth 2.0 authentication, SOQL queries, record updates.

**Twilio Voice Integration:** [Twilio Programmable Voice](https://www.twilio.com/docs/voice) – SIP trunking, call routing, DTMF handling for Salesforce workflows.

**GitHub Reference:** [vapi-salesforce-integration](https://github.com/vapi-ai/examples) – Production-ready webhook handlers, token refresh logic, error recovery patterns.

## References

1. https://docs.vapi.ai/quickstart/phone
2. https://docs.vapi.ai/quickstart/web
3. https://docs.vapi.ai/quickstart/introduction
4. https://docs.vapi.ai/chat/quickstart
5. https://docs.vapi.ai/assistants/quickstart
6. https://docs.vapi.ai/workflows/quickstart
7. https://docs.vapi.ai/observability/evals-quickstart