npm install axios dotenv

// Production-grade server setup with shared session state
const express = require('express');
const crypto = require('crypto');
const app = express();

// Session store tracks customer context across voice + digital
const sessions = new Map();
const SESSION_TTL = 1800000; // 30 min

app.use(express.json());

// Webhook signature validation (REQUIRED for production)
function validateWebhook(req, secret) {
  const signature = req.headers['x-vapi-signature'];
  const payload = JSON.stringify(req.body);
  const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hash));
}

const assistantConfig = {
  model: {
    provider: "openai",
    model: "gpt-4",
    messages: [{
      role: "system",
      content: "You handle voice interactions. Check session context for prior digital conversations."
    }]
  },
  voice: {
    provider: "11labs",
    voiceId: "21m00Tcm4TlvDq8ikWAM"
  },
  transcriber: {
    provider: "deepgram",
    model: "nova-2",
    language: "en"
  },
  serverUrl: process.env.WEBHOOK_URL,
  serverUrlSecret: process.env.VAPI_SECRET
};

flowchart LR
    A[Customer] -->|Voice Call| B[VAPI]
    A -->|SMS/WhatsApp| C[Twilio]
    B -->|Webhook| D[Your Server]
    C -->|Webhook| D
    D -->|Session State| E[Redis]
    D -->|Context| B
    D -->|Response| C
    B -->|Audio| A
    C -->|Message| A

// Handles both VAPI voice events and Twilio digital events
app.post('/webhook/omnichannel', async (req, res) => {
  if (!validateWebhook(req, process.env.VAPI_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const { type, call, message } = req.body;
  const customerId = call?.customer?.number || message?.from;
  
  // Get or create unified session
  let session = sessions.get(customerId);
  if (!session) {
    session = {
      customerId,
      channels: [],
      context: {},
      lastActivity: Date.now()
    };
    sessions.set(customerId, session);
    
    // Auto-cleanup after TTL
    setTimeout(() => sessions.delete(customerId), SESSION_TTL);
  }

  // Track channel usage
  const channel = call ? 'voice' : 'digital';
  if (!session.channels.includes(channel)) {
    session.channels.push(channel);
  }

  // Handle voice events
  if (type === 'function-call') {
    const { name, parameters } = message.functionCall;
    
    // Voice assistant can access digital conversation history
    if (name === 'get_conversation_history') {
      return res.json({
        result: {
          history: session.context.messages || [],
          previousChannel: session.channels[session.channels.length - 2]
        }
      });
    }
  }

  // Update session context
  session.lastActivity = Date.now();
  session.context.lastMessage = message?.content || call?.transcript;

  res.sendStatus(200);
});

// Before starting VAPI call, enrich with digital context
async function initiateVoiceCall(phoneNumber) {
  const session = sessions.get(phoneNumber);
  const contextMessages = session?.context.messages || [];

  try {
    const response = await fetch('https://api.vapi.ai/call', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + process.env.VAPI_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        assistant: assistantConfig,
        phoneNumber: phoneNumber,
        metadata: {
          previousChannel: session?.channels[0],
          conversationHistory: contextMessages.slice(-5) // Last 5 messages
        }
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    console.error('VAPI call failed:', error);
    throw error;
  }
}

// Prevent concurrent channel access
if (session.isProcessing) {
  return res.status(429).json({ error: 'Channel switch in progress' });
}
session.isProcessing = true;

const isStale = Date.now() - session.lastActivity > SESSION_TTL;
if (isStale) {
  session.context = {}; // Reset context
}

graph LR
    Mic[Microphone Input]
    ABuffer[Audio Buffering]
    VAD[Voice Activity Detection]
    STT[Speech-to-Text Engine]
    NLU[Natural Language Understanding]
    API[External API Call]
    LLM[Large Language Model]
    TTS[Text-to-Speech Engine]
    Speaker[Speaker Output]
    Error[Error Handling]

    Mic-->ABuffer
    ABuffer-->VAD
    VAD-->|Speech Detected|STT
    VAD-->|Silence|Error
    STT-->NLU
    NLU-->API
    API-->LLM
    LLM-->TTS
    TTS-->Speaker
    Error-->Speaker

// Test webhook signature validation locally
const testPayload = {
  message: {
    type: 'function-call',
    call: { id: 'test-call-123' },
    functionCall: {
      name: 'getCustomerContext',
      parameters: { customerId: 'cust_456' }
    }
  }
};

// Generate test signature using your webhook secret
const testSignature = crypto
  .createHmac('sha256', process.env.VAPI_WEBHOOK_SECRET)
  .update(JSON.stringify(testPayload))
  .digest('hex');

// Simulate webhook request
fetch('http://localhost:3000/webhook/vapi', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-vapi-signature': testSignature
  },
  body: JSON.stringify(testPayload)
})
.then(res => res.json())
.then(data => console.log('Webhook response:', data))
.catch(error => console.error('Validation failed:', error));

# Test invalid signature (should return 401)
curl -X POST http://localhost:3000/webhook/vapi \
  -H "Content-Type: application/json" \
  -H "x-vapi-signature: invalid_sig" \
  -d '{"message":{"type":"function-call"}}'

# Test valid webhook flow
curl -X POST http://localhost:3000/webhook/vapi \
  -H "Content-Type: application/json" \
  -H "x-vapi-signature: YOUR_VALID_SIGNATURE" \
  -d '{"message":{"type":"function-call","functionCall":{"name":"getCustomerContext","parameters":{"customerId":"cust_789"}}}}'

// Handle channel switch mid-conversation
app.post('/webhook/vapi', async (req, res) => {
  const { type, call, message } = req.body;
  
  if (type === 'function-call' && message.functionCall.name === 'switchChannel') {
    const { customerId, targetChannel } = message.functionCall.parameters;
    const session = sessions[customerId];
    
    if (!session) {
      return res.json({ result: 'Session not found' });
    }
    
    // Cancel any pending voice synthesis
    if (session.channels.voice?.isProcessing) {
      session.channels.voice.isProcessing = false;
      session.channels.voice.pendingAudio = null; // Flush buffer
    }
    
    // Transfer context to new channel
    session.channels[targetChannel] = {
      active: true,
      context: session.channels.voice?.context || [],
      lastActivity: Date.now()
    };
    
    session.channels.voice.active = false;
    
    return res.json({
      result: `Switched to ${targetChannel}. Previous context preserved.`
    });
  }
  
  res.sendStatus(200);
});

{
  "timestamp": "2024-01-15T14:23:41.234Z",
  "type": "transcript",
  "call": { "id": "call_abc123" },
  "transcript": { "text": "What's the pricing for enterpr—", "partial": true }
}
{
  "timestamp": "2024-01-15T14:23:41.456Z",
  "type": "function-call",
  "functionCall": { "name": "switchChannel", "parameters": { "customerId": "cust_789", "targetChannel": "chat" } }
}
{
  "timestamp": "2024-01-15T14:23:41.678Z",
  "type": "hang",
  "call": { "id": "call_abc123" }
}

// WRONG: Direct session mutation causes race conditions
app.post('/webhook/vapi', async (req, res) => {
  const { customerId } = req.body.message.call;
  sessions[customerId] = { channel: 'voice', context: [] }; // Overwrites chat state
});

// CORRECT: Merge channel state with locking
const channelLocks = new Map();

app.post('/webhook/vapi', async (req, res) => {
  const { customerId, type } = req.body.message;
  
  // Acquire lock to prevent concurrent writes
  if (channelLocks.has(customerId)) {
    return res.status(429).json({ error: 'Channel switch in progress' });
  }
  
  channelLocks.set(customerId, true);
  
  try {
    const session = sessions[customerId] || { channels: {}, contextMessages: [] };
    
    // Preserve existing context when switching channels
    session.channels[type === 'function-call' ? 'voice' : 'digital'] = {
      lastActive: Date.now(),
      metadata: req.body.message.call?.metadata || {}
    };
    
    sessions[customerId] = session;
    res.json({ success: true });
  } finally {
    channelLocks.delete(customerId);
  }
});

app.post('/webhook/vapi', async (req, res) => {
  res.status(200).json({ received: true }); // Respond immediately
  
  // Process async - don't block webhook response
  setImmediate(async () => {
    const { customerId } = req.body.message.call;
    const session = sessions[customerId];
    
    if (session) {
      // Fetch cross-channel context without blocking webhook
      const [twilioHistory, crmData] = await Promise.all([
        fetch(`https://conversations.twilio.com/v1/Conversations/${customerId}/Messages`),
        fetch(`https://api.crm.example/customers/${customerId}`)
      ]);
      
      session.contextMessages = await buildUnifiedContext(twilioHistory, crmData);
    }
  });
});

// Check session staleness before using context
const isStale = (session) => {
  const now = Date.now();
  return Object.values(session.channels).every(
    ch => now - ch.lastActive > SESSION_TTL
  );
};

// Clean up stale sessions every 60 seconds
setInterval(() => {
  Object.keys(sessions).forEach(customerId => {
    if (isStale(sessions[customerId])) {
      delete sessions[customerId];
    }
  });
}, 60000);

This is the full production server that handles omnichannel orchestration. Copy-paste this into `server.js` and run it. The code unifies voice calls, SMS, and WhatsApp through a single webhook handler that maintains conversation context across all channels.

```javascript
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// Session store with channel-aware context
const sessions = {};
const channelLocks = {}; // Prevent race conditions across channels
const SESSION_TTL = 1800000; // 30 minutes

// Cleanup stale sessions every 5 minutes
setInterval(() => {
  const now = Date.now();
  Object.keys(sessions).forEach(customerId => {
    if (now - sessions[customerId].lastActivity > SESSION_TTL) {
      delete sessions[customerId];
      delete channelLocks[customerId];
    }
  });
}, 300000);

// Webhook signature validation (CRITICAL for production)
function validateWebhook(payload, signature) {
  const hash = crypto
    .createHmac('sha256', process.env.VAPI_SERVER_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(hash)
  );
}

// Unified webhook handler for ALL channels
app.post('/webhook/omnichannel', async (req, res) => {
  const signature = req.headers['x-vapi-signature'];
  if (!validateWebhook(req.body, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { type, call, functionCall } = req.body;
  const customerId = call?.metadata?.customerId || 'unknown';
  const channel = call?.metadata?.channel || 'voice'; // voice, sms, whatsapp

  // Acquire lock to prevent overlapping responses
  if (channelLocks[customerId]) {
    return res.status(200).json({ result: 'Processing in progress' });
  }
  channelLocks[customerId] = true;

  try {
    // Initialize or retrieve session with channel context
    if (!sessions[customerId]) {
      sessions[customerId] = {
        contextMessages: [],
        channels: new Set(),
        lastActivity: Date.now(),
        activeCallId: null,
        pendingResponses: []
      };
    }

    const session = sessions[customerId];
    session.channels.add(channel);
    session.lastActivity = Date.now();

    // Handle function calls from assistant
    if (type === 'function-call' && functionCall?.name === 'getCustomerContext') {
      const { customerId: reqCustomerId } = functionCall.parameters;
      
      // Return unified context across ALL channels
      const contextMessages = session.contextMessages
        .slice(-10) // Last 10 interactions
        .map(msg => `[${msg.channel}] ${msg.content}`)
        .join('\n');

      const result = {
        customerId: reqCustomerId,
        activeChannels: Array.from(session.channels),
        recentContext: contextMessages,
        lastActivity: new Date(session.lastActivity).toISOString(),
        totalInteractions: session.contextMessages.length
      };

      res.json({ result });

      // Store this interaction
      session.contextMessages.push({
        channel,
        content: `Context retrieved at ${new Date().toISOString()}`,
        timestamp: Date.now()
      });
    } 
    // Handle call status updates
    else if (type === 'status-update') {
      const status = call?.status;
      session.contextMessages.push({
        channel,
        content: `Call status: ${status}`,
        timestamp: Date.now()
      });
      
      if (status === 'ended') {
        session.activeCallId = null;
      }
      
      res.status(200).json({ result: 'Status updated' });
    }
    // Handle end-of-call reports
    else if (type === 'end-of-call-report') {
      const duration = call?.duration || 0;
      const endReason = call?.endedReason || 'unknown';
      
      // Archive conversation for this channel
      session.contextMessages.push({
        channel,
        content: `Call ended. Duration: ${duration}s. Reason: ${endReason}`,
        timestamp: Date.now()
      });
      
      // Extract transcript if available
      if (call?.transcript) {
        session.contextMessages.push({
          channel,
          content: `Transcript: ${call.transcript}`,
          timestamp: Date.now()
        });
      }
      
      res.status(200).json({ result: 'Call archived' });
    }
    // Handle assistant requests
    else if (type === 'assistant-request') {
      const messages = call?.messages || [];
      const lastMessage = messages[messages.length - 1];
      
      if (lastMessage) {
        session.contextMessages.push({
          channel,
          content: lastMessage.content,
          timestamp: Date.now()
        });
      }
      
      res.status(200).json({ result: 'Message logged' });
    }
    // Default handler for other events
    else {
      res.status(200).json({ result: 'Event received' });
    }
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Internal server error', message: error.message });
  } finally {
    delete channelLocks[customerId];
  }
});

// Initiate voice call with channel metadata
async function initiateVoiceCall(customerId, phoneNumber) {
  const assistantConfig = {
    model: {
      provider: 'openai',
      model: 'gpt-4',
      messages: [
        {
          role: 'system',
          content: 'You are a customer support agent with access to omnichannel conversation history. Use getCustomerContext to retrieve past interactions across voice, SMS, and WhatsApp. Always acknowledge previous conversations when available.'
        }
      ],
      functions: [
        {
          name: 'getCustomerContext',
          description: 'Retrieve customer conversation history across all channels',
          parameters: {
            type: 'object',
            properties: {
              customerId: {
                type: 'string',
                description: 'The unique customer identifier'
              }
            },
            required: ['customerId']
          }
        }
      ]
    },
    voice: {
      provider: 'elevenlabs',
      voiceId: '21m00Tcm4TlvDq8ikWAM'
    },
    transcriber: {
      provider: 'deepgram',
      language: 'en',
      model: 'nova-2'
    },
    serverUrl: `${process.env.SERVER_URL}/webhook/omnichannel`,
    serverUrlSecret: process.env.VAPI_SERVER_SECRET
  };

  try {
    const response = await fetch('https://api.vapi.ai/call', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.VAPI_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        assistant: assistantConfig,
        phoneNumberId: process.env.VAPI_PHONE_NUMBER_ID,
        customer: {
          number: phoneNumber
        },
        metadata: { 
          customerId, 
          channel: 'voice',
          initiatedAt: new Date().toISOString()
        }
      })
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`HTTP ${response.status}: ${errorText}`);
    }

    const callData = await response.json();
    
    // Store active call ID in session
    if (

## FAQ

## Technical Questions

**How do I prevent voice and digital channels from sending duplicate messages to the same customer?**

Use channel-level locking with session state management. When a customer initiates contact via voice (Twilio), store the `customerId` and `channel` in your sessions object with a lock flag. Before routing a digital message (SMS, email) to that same customer, check if an active voice session exists for that `customerId`. If it does, queue the digital message or defer it until the voice call ends. This prevents the bot from responding twice—once via voice and once via text—which destroys the customer experience.

**What's the latency impact of orchestrating voice and digital simultaneously?**

Voice calls add 200-400ms round-trip latency (Twilio → your server → VAPI). Digital channels (SMS, email) add 500ms-2s depending on carrier. If you're synchronizing responses across both channels, the slowest channel wins—your response time becomes 2-3 seconds minimum. Decouple them: handle voice in real-time, queue digital messages asynchronously. Use webhooks to trigger digital follow-ups after the voice call completes, not during it.

**How do I maintain conversation context across voice and digital handoffs?**

Store `contextMessages` in your session object keyed by `customerId`. When a customer switches from voice to digital (or vice versa), retrieve the conversation history from that session and inject it into the new channel's `messages` array. Include role, content, and timestamp for each message. This gives the assistant full context without re-asking questions. Clean up stale sessions after `SESSION_TTL` (typically 24 hours) to avoid memory bloat.

## Performance

**Why does my omnichannel system feel slow when handling peak traffic?**

Synchronous webhook processing blocks your event loop. When VAPI or Twilio fires a webhook, you're validating the signature, querying the database, and calling external APIs in sequence. Under load, this queues up. Solution: validate the webhook signature synchronously (required for security), then immediately return a 200 response. Process the actual business logic asynchronously in a background queue (Bull, RabbitMQ, or AWS SQS). This keeps your webhook handler under 100ms.

**Should I use connection pooling for omnichannel integrations?**

Yes. Each voice call to Twilio and each VAPI request opens a new TCP connection by default. Under load, you'll exhaust socket limits and see ECONNREFUSED errors. Use HTTP keep-alive and connection pooling in your HTTP client (axios with `httpAgent` and `httpsAgent` configured). For database queries triggered by voice/digital events, use a connection pool with a max size of 10-20 connections. This reduces latency by 50-100ms per request.

## Platform Comparison

**When should I use VAPI vs. Twilio for voice orchestration?**

VAPI handles voice AI orchestration—transcription, LLM reasoning, function calling, and voice synthesis in one platform. Twilio handles carrier connectivity and call routing. Use VAPI when you need intelligent voice agents with real-time function calling (e.g., checking inventory, booking appointments). Use Twilio when you need basic IVR, call transfer, or PSTN connectivity. In omnichannel systems, they're complementary: Twilio routes the inbound call, VAPI powers the agent logic.

**Can I use the same assistant configuration across voice and digital channels?**

Partially. The `model`, `messages`, and `functionCall` logic stay the same. The `voice` and `transcriber` configs are voice-only—they don't apply to SMS or email. For digital channels, strip out voice-specific keys and add channel-specific formatting (e.g., character limits for SMS, HTML for email). Store a base `assistantConfig` with shared logic, then extend it per channel. This avoids duplicating your LLM prompt across platforms.

## Resources

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

**Official Documentation**
- [VAPI Voice AI Platform Docs](https://docs.vapi.ai) – Complete API reference for voice assistant configuration, function calling, and webhook integration
- [Twilio Voice API Docs](https://www.twilio.com/docs/voice) – Multi-channel voice routing, call control, and PSTN integration

**GitHub & Implementation**
- [VAPI GitHub Examples](https://github.com/VapiAI) – Production-grade code samples for omnichannel orchestration and real-time call handling
- [Twilio Node.js SDK](https://github.com/twilio/twilio-node) – Official SDK for programmatic call management and channel routing

**Integration Patterns**
- VAPI Webhook Events – Real-time call state updates (ringing, answered, ended) for unified customer interaction management
- Twilio Studio – Visual workflow builder for multi-channel voice and messaging orchestration across touchpoints

## 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/assistants/quickstart
5. https://docs.vapi.ai/chat/quickstart
6. https://docs.vapi.ai/outbound-campaigns/quickstart
7. https://docs.vapi.ai/workflows/quickstart
8. https://docs.vapi.ai/observability/evals-quickstart
9. https://docs.vapi.ai/server-url/developing-locally
10. https://docs.vapi.ai/assistants/structured-outputs-quickstart