DEV Community: Shashi Kiran

Series: Building Cloud Call Centres with Vonage APIs — Day 4 of 30

Shashi Kiran — Thu, 26 Mar 2026 10:30:54 +0000

Vonage Client SDK: Building Your First Voice App for a Cloud Call Centre

← Day 3: Setup from Scratch | Day 5: Call Routing & Business Rules →

🎯 What You'll Build Today

By the end of this post you will have:

✅ A browser-based softphone that receives inbound calls
✅ An agent login system using Vonage JWTs
✅ Answer / Hang up / Mute controls working in the browser
✅ Real-time call status display (ringing, connected, duration)
✅ Your first working agent desktop component

No phone hardware. No SIP client. Just a browser tab.

🗺️ What We're Building

┌──────────────────────────────────────────────────────────────────┐
│                    TODAY'S ARCHITECTURE                          │
│                                                                  │
│  Caller's Phone                                                  │
│       │                                                          │
│       │ dials virtual number                                     │
│       ▼                                                          │
│  ┌──────────┐    webhook     ┌──────────────┐                   │
│  │  Vonage  │──────────────► │  Your Node   │                   │
│  │ Platform │                │  Backend     │                   │
│  └────┬─────┘ ◄──── NCCO ───│  server.js   │                   │
│       │                      └──────────────┘                   │
│       │ WebRTC audio stream                                      │
│       │                                                          │
│       ▼                                                          │
│  ┌──────────────────────────────────────────┐                   │
│  │         AGENT'S BROWSER                  │                   │
│  │                                          │                   │
│  │   Vonage Client SDK (JavaScript)         │                   │
│  │                                          │                   │
│  │  ┌────────────────────────────────────┐  │                   │
│  │  │      SOFTPHONE COMPONENT           │  │                   │
│  │  │                                    │  │                   │
│  │  │  Status: 🟢 Available              │  │                   │
│  │  │  Caller: +44 7700 900001           │  │                   │
│  │  │  Duration: 00:32                   │  │                   │
│  │  │                                    │  │                   │
│  │  │  [Answer] [Hang Up] [Mute]         │  │                   │
│  │  └────────────────────────────────────┘  │                   │
│  └──────────────────────────────────────────┘                   │
└──────────────────────────────────────────────────────────────────┘

🧠 How the Vonage Client SDK Works

Before writing code, understand the authentication flow:

┌──────────────────────────────────────────────────────────────┐
│              CLIENT SDK AUTHENTICATION FLOW                  │
│                                                              │
│  STEP 1: Agent opens browser                                 │
│          │                                                   │
│          ▼                                                   │
│  STEP 2: Browser requests JWT from your backend              │
│          GET /auth/token?agent=alice                         │
│          │                                                   │
│          ▼                                                   │
│  STEP 3: Your backend generates JWT                          │
│          signed with your Vonage private.key                 │
│          JWT payload:                                        │
│          {                                                   │
│            sub: "alice",          ← agent username          │
│            acl: { voice: {} },    ← permissions             │
│            exp: now + 86400,      ← expires in 24h          │
│            application_id: "xxx"  ← your app ID             │
│          }                                                   │
│          │                                                   │
│          ▼                                                   │
│  STEP 4: Browser receives JWT                                │
│          Vonage Client SDK logs in with JWT                  │
│          │                                                   │
│          ▼                                                   │
│  STEP 5: SDK connects to Vonage's WebSocket server           │
│          Agent is now "online" and reachable                 │
│          │                                                   │
│          ▼                                                   │
│  STEP 6: Inbound call arrives                                │
│          SDK fires: client.on('callInvite', ...)             │
│          Browser rings / shows notification                  │
└──────────────────────────────────────────────────────────────┘

The key insight: the JWT ties a username (e.g. "alice") to your Vonage application. When your NCCO routes a call to user: "alice", Vonage knows which browser session to ring.

STEP 1 — Install Dependencies

Add to your existing project from Day 3:

npm install @vonage/jwt express-static

For the frontend, the Vonage Client SDK is loaded via CDN — no npm needed for the browser side.

STEP 2 — Add JWT Generation to Your Backend

Add a new route to server.js that generates agent tokens:

// server.js — add these imports at the top
import { tokenGenerate } from '@vonage/jwt';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// ──────────────────────────────────────────────
// JWT TOKEN ENDPOINT
// Agents call this to get their login token
// ──────────────────────────────────────────────
app.get('/auth/token', (req, res) => {
  const agentName = req.query.agent;

  if (!agentName) {
    return res.status(400).json({ error: 'agent query param required' });
  }

  // Sanitise agent name — alphanumeric and hyphens only
  const sanitised = agentName.replace(/[^a-zA-Z0-9-_]/g, '');

  const token = tokenGenerate(
    process.env.VONAGE_APPLICATION_ID,
    process.env.VONAGE_PRIVATE_KEY_PATH,
    {
      subject: sanitised,
      expiryTime: Math.floor(Date.now() / 1000) + 86400, // 24 hours
      acl: {
        paths: {
          '/*/users/**': {},
          '/*/conversations/**': {},
          '/*/sessions/**': {},
          '/*/devices/**': {},
          '/*/image/**': {},
          '/*/media/**': {},
          '/*/applications/**': {},
          '/*/push/**': {},
          '/*/knocking/**': {},
          '/*/legs/**': {}
        }
      }
    }
  );

  console.log(`🔑 JWT generated for agent: ${sanitised}`);

  res.json({
    token,
    agent: sanitised,
    expiresIn: 86400
  });
});

// Serve the agent desktop HTML
app.use(express.static(path.join(__dirname, 'public')));

STEP 3 — Update Your Answer Webhook for Agent Routing

Update the answer webhook to route the call to a specific agent:

// server.js — update the answer webhook
app.get('/webhooks/answer', (req, res) => {
  const from = req.query.from;
  const to = req.query.to;
  const uuid = req.query.uuid;

  console.log(`📞 Inbound call from ${from} to ${to} [${uuid}]`);

  // In a real system you'd look up which agent to route to
  // For now we route to our test agent "alice"
  const targetAgent = 'alice';

  const ncco = [
    {
      action: 'talk',
      text: `Thank you for calling. Connecting you to an agent now. Please hold.`,
      language: 'en-GB',
      style: 1
    },
    {
      action: 'connect',
      from: to,  // Your virtual number as the "from"
      endpoint: [
        {
          type: 'app',
          user: targetAgent   // Route to this agent username
        }
      ],
      timeout: 30,            // Ring agent for 30 seconds
      eventUrl: [`${process.env.BASE_URL}/webhooks/connect-event`]
    }
  ];

  res.json(ncco);
});

// ──────────────────────────────────────────────
// CONNECT EVENT WEBHOOK
// Fired when the connect action changes state
// ──────────────────────────────────────────────
app.post('/webhooks/connect-event', (req, res) => {
  console.log('🔗 Connect event:', req.body);

  if (req.body.status === 'timeout') {
    console.log('⏱️  Agent did not answer — implement voicemail/queue here');
  }

  res.status(200).end();
});

Add BASE_URL to your .env:

BASE_URL=https://abc123.ngrok.io

STEP 4 — Build the Agent Desktop

Create the public folder and agent desktop:

mkdir public
touch public/index.html

<!-- public/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Cloud Call Centre — Agent Desktop</title>

  <!-- Vonage Client SDK from CDN -->
  <script src="https://cdn.jsdelivr.net/npm/@vonage/client-sdk@latest/dist/vonageClientSDK.js"></script>

  <style>
    * { box-sizing: border-box; margin: 0; padding: 0; }

    body {
      font-family: 'Segoe UI', system-ui, sans-serif;
      background: #050a14;
      color: #e2e8f0;
      min-height: 100vh;
      display: flex;
      align-items: center;
      justify-content: center;
    }

    .container {
      width: 400px;
    }

    .header {
      text-align: center;
      margin-bottom: 2rem;
    }

    .header h1 {
      font-size: 1.4rem;
      color: #38bdf8;
      margin-bottom: 0.25rem;
    }

    .header p {
      font-size: 0.8rem;
      color: #475569;
    }

    /* LOGIN PANEL */
    .login-panel {
      background: #0a1628;
      border: 1px solid #1e3a5f;
      border-radius: 12px;
      padding: 2rem;
    }

    .login-panel h2 {
      font-size: 1rem;
      margin-bottom: 1.5rem;
      color: #94a3b8;
    }

    .form-group {
      margin-bottom: 1rem;
    }

    .form-group label {
      display: block;
      font-size: 0.75rem;
      color: #64748b;
      margin-bottom: 0.4rem;
      letter-spacing: 0.05em;
      text-transform: uppercase;
    }

    .form-group input {
      width: 100%;
      padding: 0.65rem 0.9rem;
      background: #0f1e35;
      border: 1px solid #1e3a5f;
      border-radius: 8px;
      color: #e2e8f0;
      font-size: 0.9rem;
      outline: none;
      transition: border-color 0.2s;
    }

    .form-group input:focus {
      border-color: #38bdf8;
    }

    /* BUTTONS */
    .btn {
      width: 100%;
      padding: 0.75rem;
      border: none;
      border-radius: 8px;
      font-size: 0.9rem;
      font-weight: 600;
      cursor: pointer;
      transition: all 0.2s;
    }

    .btn-primary {
      background: #0ea5e9;
      color: white;
    }

    .btn-primary:hover { background: #0284c7; }
    .btn-primary:disabled { background: #1e3a5f; color: #475569; cursor: not-allowed; }

    .btn-success {
      background: #10b981;
      color: white;
    }

    .btn-success:hover { background: #059669; }

    .btn-danger {
      background: #ef4444;
      color: white;
    }

    .btn-danger:hover { background: #dc2626; }

    .btn-warning {
      background: #f59e0b;
      color: #0f172a;
    }

    .btn-warning:hover { background: #d97706; }

    .btn-sm {
      width: auto;
      padding: 0.5rem 1.25rem;
      font-size: 0.8rem;
    }

    /* SOFTPHONE PANEL */
    .softphone {
      background: #0a1628;
      border: 1px solid #1e3a5f;
      border-radius: 12px;
      padding: 2rem;
      display: none;
    }

    .softphone.visible { display: block; }

    /* STATUS INDICATOR */
    .status-bar {
      display: flex;
      align-items: center;
      justify-content: space-between;
      margin-bottom: 1.5rem;
      padding-bottom: 1rem;
      border-bottom: 1px solid #1e3a5f;
    }

    .status-indicator {
      display: flex;
      align-items: center;
      gap: 0.5rem;
    }

    .status-dot {
      width: 10px;
      height: 10px;
      border-radius: 50%;
      background: #64748b;
      transition: background 0.3s;
    }

    .status-dot.available { background: #10b981; box-shadow: 0 0 8px #10b981; }
    .status-dot.ringing   { background: #f59e0b; box-shadow: 0 0 8px #f59e0b; animation: pulse 1s infinite; }
    .status-dot.connected { background: #3b82f6; box-shadow: 0 0 8px #3b82f6; }
    .status-dot.offline   { background: #ef4444; }

    @keyframes pulse {
      0%, 100% { opacity: 1; }
      50%       { opacity: 0.4; }
    }

    .status-text {
      font-size: 0.85rem;
      font-weight: 600;
      color: #94a3b8;
    }

    .agent-name {
      font-size: 0.75rem;
      color: #475569;
    }

    /* CALL INFO */
    .call-info {
      background: #0f1e35;
      border-radius: 8px;
      padding: 1.25rem;
      margin-bottom: 1.5rem;
      min-height: 90px;
      display: flex;
      flex-direction: column;
      justify-content: center;
    }

    .call-info .label {
      font-size: 0.65rem;
      color: #475569;
      letter-spacing: 0.1em;
      text-transform: uppercase;
      margin-bottom: 0.3rem;
    }

    .call-info .value {
      font-size: 1.1rem;
      color: #f1f5f9;
      font-weight: 600;
    }

    .call-info .sub {
      font-size: 0.75rem;
      color: #64748b;
      margin-top: 0.2rem;
    }

    /* CALL CONTROLS */
    .call-controls {
      display: grid;
      grid-template-columns: 1fr 1fr 1fr;
      gap: 0.75rem;
      margin-bottom: 1rem;
    }

    /* LOG */
    .log {
      margin-top: 1.5rem;
      padding-top: 1rem;
      border-top: 1px solid #1e3a5f;
    }

    .log-title {
      font-size: 0.65rem;
      color: #334155;
      letter-spacing: 0.1em;
      text-transform: uppercase;
      margin-bottom: 0.5rem;
    }

    .log-entries {
      max-height: 120px;
      overflow-y: auto;
    }

    .log-entry {
      font-size: 0.72rem;
      color: #475569;
      padding: 0.2rem 0;
      border-bottom: 1px solid #0f1e35;
    }

    .log-entry .time {
      color: #334155;
      margin-right: 0.5rem;
    }

    .log-entry.info  { color: #38bdf8; }
    .log-entry.warn  { color: #f59e0b; }
    .log-entry.error { color: #ef4444; }
    .log-entry.success { color: #10b981; }
  </style>
</head>
<body>

<div class="container">

  <div class="header">
    <h1>☁️ Cloud Call Centre</h1>
    <p>Agent Desktop — Day 4 Demo</p>
  </div>

  <!-- LOGIN PANEL -->
  <div class="login-panel" id="loginPanel">
    <h2>Agent Login</h2>
    <div class="form-group">
      <label>Agent Username</label>
      <input type="text" id="agentName" value="alice" placeholder="e.g. alice" />
    </div>
    <button class="btn btn-primary" id="loginBtn" onclick="loginAgent()">
      Connect to Call Centre
    </button>
    <div id="loginStatus" style="margin-top:1rem; font-size:0.8rem; color:#475569;"></div>
  </div>

  <!-- SOFTPHONE PANEL -->
  <div class="softphone" id="softphone">

    <div class="status-bar">
      <div class="status-indicator">
        <div class="status-dot available" id="statusDot"></div>
        <span class="status-text" id="statusText">Available</span>
      </div>
      <span class="agent-name" id="agentLabel">agent: —</span>
    </div>

    <div class="call-info" id="callInfo">
      <div class="label">Waiting for calls</div>
      <div class="value" id="callerNumber">—</div>
      <div class="sub" id="callDuration"></div>
    </div>

    <div class="call-controls">
      <button class="btn btn-success" id="answerBtn" onclick="answerCall()" disabled>
        📞 Answer
      </button>
      <button class="btn btn-danger" id="hangupBtn" onclick="hangupCall()" disabled>
        📵 Hang Up
      </button>
      <button class="btn btn-warning" id="muteBtn" onclick="toggleMute()" disabled>
        🎤 Mute
      </button>
    </div>

    <button class="btn btn-sm" style="background:#1e3a5f;color:#94a3b8;margin-top:0.5rem;" onclick="logout()">
      Logout
    </button>

    <div class="log">
      <div class="log-title">Activity Log</div>
      <div class="log-entries" id="logEntries"></div>
    </div>

  </div>

</div>

<script>
  // ── STATE ──────────────────────────────────────────────
  let vonageClient = null;
  let currentCall  = null;
  let isMuted      = false;
  let callTimer    = null;
  let callSeconds  = 0;

  // ── LOGGING ────────────────────────────────────────────
  function addLog(message, type = 'info') {
    const entries = document.getElementById('logEntries');
    const entry   = document.createElement('div');
    const time    = new Date().toLocaleTimeString();
    entry.className = `log-entry ${type}`;
    entry.innerHTML = `<span class="time">${time}</span>${message}`;
    entries.prepend(entry);
  }

  // ── STATUS HELPERS ─────────────────────────────────────
  function setStatus(state, label) {
    const dot  = document.getElementById('statusDot');
    const text = document.getElementById('statusText');
    dot.className  = `status-dot ${state}`;
    text.textContent = label;
  }

  function updateCallInfo(number, subText) {
    document.getElementById('callerNumber').textContent = number || '—';
    document.getElementById('callDuration').textContent = subText || '';
    document.querySelector('.call-info .label').textContent =
      number ? 'Incoming call from' : 'Waiting for calls';
  }

  function setButtons(state) {
    const answerBtn = document.getElementById('answerBtn');
    const hangupBtn = document.getElementById('hangupBtn');
    const muteBtn   = document.getElementById('muteBtn');

    answerBtn.disabled = state !== 'ringing';
    hangupBtn.disabled = state !== 'connected';
    muteBtn.disabled   = state !== 'connected';
  }

  // ── CALL TIMER ─────────────────────────────────────────
  function startTimer() {
    callSeconds = 0;
    callTimer = setInterval(() => {
      callSeconds++;
      const m = String(Math.floor(callSeconds / 60)).padStart(2, '0');
      const s = String(callSeconds % 60).padStart(2, '0');
      document.getElementById('callDuration').textContent = `Duration: ${m}:${s}`;
    }, 1000);
  }

  function stopTimer() {
    clearInterval(callTimer);
    callTimer = null;
  }

  // ── LOGIN ──────────────────────────────────────────────
  async function loginAgent() {
    const agentName = document.getElementById('agentName').value.trim();
    const loginBtn  = document.getElementById('loginBtn');
    const statusEl  = document.getElementById('loginStatus');

    if (!agentName) {
      statusEl.textContent = '⚠️ Please enter an agent username.';
      return;
    }

    loginBtn.disabled = true;
    statusEl.textContent = 'Fetching credentials…';

    try {
      // 1. Get JWT from your backend
      const res   = await fetch(`/auth/token?agent=${encodeURIComponent(agentName)}`);
      const data  = await res.json();

      statusEl.textContent = 'Connecting to Vonage…';

      // 2. Initialise the Vonage Client SDK
      vonageClient = new VonageClient();

      // 3. Log in with JWT
      await vonageClient.createSession(data.token);

      // 4. Register call event listeners
      registerCallListeners();

      // 5. Show softphone UI
      document.getElementById('loginPanel').style.display = 'none';
      document.getElementById('softphone').classList.add('visible');
      document.getElementById('agentLabel').textContent = `agent: ${agentName}`;

      setStatus('available', 'Available');
      addLog(`Logged in as ${agentName}`, 'success');

    } catch (err) {
      loginBtn.disabled = false;
      statusEl.textContent = `❌ Login failed: ${err.message}`;
      console.error('Login error:', err);
    }
  }

  // ── CALL EVENT LISTENERS ───────────────────────────────
  function registerCallListeners() {

    // Inbound call arrives
    vonageClient.on('callInvite', (callId, from, channelType) => {
      console.log('📞 Incoming call:', { callId, from, channelType });

      currentCall = callId;
      isMuted = false;

      setStatus('ringing', 'Ringing…');
      updateCallInfo(from, 'Incoming call…');
      setButtons('ringing');

      addLog(`📞 Incoming call from ${from}`, 'warn');
    });

    // Call was answered
    vonageClient.on('callAnswered', (callId) => {
      console.log('✅ Call answered:', callId);

      setStatus('connected', 'Connected');
      setButtons('connected');
      startTimer();

      addLog('✅ Call connected', 'success');
    });

    // Call ended
    vonageClient.on('callHangup', (callId, callQuality, reason) => {
      console.log('📵 Call ended:', { callId, reason });

      stopTimer();
      currentCall = null;
      isMuted = false;

      setStatus('available', 'Available');
      updateCallInfo(null);
      setButtons('idle');

      addLog(`📵 Call ended — ${reason || 'completed'}`, 'info');
    });

    // Connection state changes
    vonageClient.on('sessionError', (err) => {
      addLog(`⚠️ Session error: ${err.message}`, 'error');
    });
  }

  // ── CALL CONTROLS ──────────────────────────────────────
  async function answerCall() {
    if (!currentCall) return;
    try {
      await vonageClient.answer(currentCall);
      addLog('Answered call', 'success');
    } catch (err) {
      addLog(`Failed to answer: ${err.message}`, 'error');
    }
  }

  async function hangupCall() {
    if (!currentCall) return;
    try {
      await vonageClient.hangup(currentCall);
      addLog('Hung up call', 'info');
    } catch (err) {
      addLog(`Failed to hang up: ${err.message}`, 'error');
    }
  }

  async function toggleMute() {
    if (!currentCall) return;
    try {
      isMuted = !isMuted;
      await vonageClient.mute(currentCall, isMuted);
      const muteBtn = document.getElementById('muteBtn');
      muteBtn.textContent = isMuted ? '🔇 Unmute' : '🎤 Mute';
      addLog(isMuted ? 'Microphone muted' : 'Microphone unmuted', 'info');
    } catch (err) {
      addLog(`Mute error: ${err.message}`, 'error');
    }
  }

  function logout() {
    if (vonageClient) vonageClient.deleteSession();
    location.reload();
  }
</script>

</body>
</html>

STEP 5 — Test the Full Flow

5.1 Start everything

Terminal 1 — server:

node server.js

Terminal 2 — ngrok:

ngrok http 3000

5.2 Open the agent desktop

Navigate to http://localhost:3000 in your browser.

┌──────────────────────────────────────────────┐
│         Cloud Call Centre                    │
│         Agent Desktop — Day 4 Demo           │
│                                              │
│  Agent Login                                 │
│  ┌──────────────────────────────────────┐    │
│  │  Agent Username: alice               │    │
│  └──────────────────────────────────────┘    │
│                                              │
│  [Connect to Call Centre]                    │
└──────────────────────────────────────────────┘

5.3 Log in as "alice"

Click Connect to Call Centre. The page fetches a JWT for alice and connects to Vonage. You'll see:

┌──────────────────────────────────────────────┐
│  🟢 Available              agent: alice      │
│                                              │
│  Waiting for calls                           │
│  —                                           │
│                                              │
│  [Answer ✗]  [Hang Up ✗]  [Mute ✗]          │
│                                              │
│  Activity Log                                │
│  09:12:01  Logged in as alice                │
└──────────────────────────────────────────────┘

5.4 Call your virtual number

Call your Vonage number from your phone. Watch the browser:

┌──────────────────────────────────────────────┐
│  🟡 Ringing…               agent: alice      │
│                                              │
│  Incoming call from                          │
│  +44 7700 900001                             │
│  Incoming call…                              │
│                                              │
│  [Answer ✅]  [Hang Up ✗]  [Mute ✗]         │
│                                              │
│  Activity Log                                │
│  09:12:44  📞 Incoming call from +44770...   │
│  09:12:01  Logged in as alice                │
└──────────────────────────────────────────────┘

Click Answer — the caller hears the hold music stop and you're connected via WebRTC audio in the browser.

How the Data Flows

CALL FLOW WITH CLIENT SDK

Your Phone                  Vonage              Your Server          Browser (alice)
    │                          │                     │                     │
    │── dials number ─────────►│                     │                     │
    │                          │── GET /answer ──────►│                     │
    │                          │◄── NCCO (connect ───│                     │
    │                          │    to user:alice)   │                     │
    │                          │                     │                     │
    │                          │── callInvite ───────────────────────────►│
    │                          │                     │                     │
    │                          │                     │           user clicks Answer
    │                          │◄──────────────────────────────── answer()│
    │                          │                     │                     │
    │◄──── WebRTC audio ───────────────────────────────────────────────────│
    │      established         │                     │                     │
    │                          │                     │                     │
    │  conversation happening  │                     │                     │
    │                          │                     │                     │
    │                          │◄────── hangup() ────────────────────────│
    │── call ends ────────────►│                     │                     │
    │                          │── POST /event ──────►│                     │
    │                          │   {completed}       │                     │

🛠️ Troubleshooting

ISSUE: "callInvite" never fires in browser
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fix 1: Check the NCCO connect action uses type: "app"
       and user: "alice" (must match the JWT subject)
Fix 2: Check the JWT was generated with the correct
       applicationId from your .env
Fix 3: Open browser devtools console — SDK errors appear here

────────────────────────────────────────────────────────────

ISSUE: No audio after answering
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fix: Browser must have microphone permission granted
     Check: Site Settings → Microphone → Allow
     The SDK needs mic access for WebRTC

────────────────────────────────────────────────────────────

ISSUE: JWT token error 401
━━━━━━━━━━━━━━━━━━━━━━━━━
Fix: Verify VONAGE_APPLICATION_ID and
     VONAGE_PRIVATE_KEY_PATH match the application
     that owns your phone number

✅ Day 4 Checklist

  □ JWT token endpoint /auth/token working
  □ Agent login succeeds in browser
  □ Status dot shows green "Available"
  □ Inbound call triggers "Ringing" status
  □ Answer button connects audio via WebRTC
  □ Caller hears agent and vice versa
  □ Hang Up ends the call cleanly
  □ Mute toggles microphone
  □ Activity log shows events in real time
  □ Call events logged in server terminal

🚀 What's Next

Day 5 covers the routing engine — skills-based routing, queues, business hours, and priority. We'll extend today's agent desktop to support multiple agents with different skills and route calls intelligently between them.

← Day 3: Setup from Scratch | Day 4 of 30 | Day 5: Call Routing →

Series: Building Cloud Call Centres with Vonage APIs — Day 3 of 30

Shashi Kiran — Thu, 26 Mar 2026 10:30:32 +0000

Setting Up Your Cloud Call Centre with Vonage from Scratch

← Day 2: Architecture Deep Dive | Day 4: Vonage Client SDK →

🎯 What You'll Build Today

By the end of this post your local machine will be fully wired to Vonage's platform. You'll have:

✅ A Vonage API account with credentials
✅ The Vonage CLI installed and authenticated
✅ A real virtual phone number provisioned
✅ ngrok tunnelling your localhost to the internet
✅ A Node.js webhook server that answers a real phone call
✅ Your phone ringing and hearing "Hello from your Cloud Call Centre"

This is the foundation everything else in this series is built on. Let's go.

🗺️ What We're Building Today

┌─────────────────────────────────────────────────────────────────┐
│                   TODAY'S SETUP GOAL                            │
│                                                                 │
│  Your Phone                                                     │
│  (caller)                                                       │
│      │                                                          │
│      │  dials virtual number                                    │
│      ▼                                                          │
│  ┌─────────────┐                                                │
│  │   Vonage    │  ── fires webhook ──►  ngrok tunnel            │
│  │   Platform  │                             │                  │
│  └─────────────┘                             │ forwards to      │
│                                              ▼                  │
│                                    ┌──────────────────┐        │
│                                    │  localhost:3000   │        │
│                                    │  (your Node.js   │        │
│                                    │   server)        │        │
│                                    └────────┬─────────┘        │
│                                             │                   │
│                                             │ returns NCCO      │
│                                             ▼                   │
│                                    ┌──────────────────┐        │
│                                    │  Vonage executes │        │
│                                    │  "Hello from     │        │
│                                    │   your Cloud     │        │
│                                    │   Call Centre"   │        │
│                                    └──────────────────┘        │
└─────────────────────────────────────────────────────────────────┘

📋 Prerequisites

Before we start, make sure you have these installed:

Tool	Version	Check command
Node.js	18+	`node --version`
npm	9+	`npm --version`
Git	Any	`git --version`
A terminal	—	—
A real phone	—	For testing calls

STEP 1 — Create Your Vonage API Account

1.1 Sign Up

Head to dashboard.nexmo.com/sign-up and create a free account. You'll receive:

€2 free credit to make test calls
A test virtual number (in some regions)
Full API access immediately — no credit card required for trial

1.2 Find Your API Credentials

Once logged in, your API credentials are on the dashboard home page:

┌──────────────────────────────────────────────────────┐
│           VONAGE API DASHBOARD                       │
│                                                      │
│  ┌────────────────────────────────────────────────┐  │
│  │  API key:      a1b2c3d4                        │  │
│  │  API secret:   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
│  These are your master credentials.                  │
│  NEVER commit these to git.                          │
│  Store them in a .env file (shown below).            │
└──────────────────────────────────────────────────────┘

⚠️ Security rule from Day 1: API keys go in .env files only. Add .env to your .gitignore before your first commit. We'll cover secrets management properly in Week 6.

STEP 2 — Install the Vonage CLI

The Vonage CLI is your command-line control panel for managing numbers, applications, and credentials.

2.1 Install

npm install -g @vonage/cli

2.2 Verify installation

vonage --version
# Expected output: @vonage/cli/x.x.x ...

2.3 Authenticate with your credentials

vonage config:set --apiKey=YOUR_API_KEY --apiSecret=YOUR_API_SECRET

You'll see:

✔ API key and secret saved to ~/.vonage/credentials

2.4 Verify authentication works

vonage balance
# Expected output:
# Current balance: 2.00000 EUR

If you see your balance, you're authenticated. ✅

STEP 3 — Create a Vonage Application

A Vonage Application is a configuration object that links your phone numbers and webhook URLs together. Think of it as the "container" for your call centre.

┌──────────────────────────────────────────────────────────────┐
│                  VONAGE APPLICATION                          │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Application ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx│   │
│  │  Name: "my-cloud-call-centre"                        │   │
│  └──────────────────────────────────────────────────────┘   │
│                          │                                   │
│         ┌────────────────┼────────────────┐                  │
│         ▼                ▼                ▼                  │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐             │
│   │ WEBHOOK  │    │  PRIVATE │    │  LINKED  │             │
│   │  URLS    │    │   KEY    │    │ NUMBERS  │             │
│   │          │    │          │    │          │             │
│   │ answer   │    │ RSA key  │    │ +44 xxx  │             │
│   │ event    │    │ for JWT  │    │ +1 xxx   │             │
│   │ fallback │    │ auth     │    │          │             │
│   └──────────┘    └──────────┘    └──────────┘             │
└──────────────────────────────────────────────────────────────┘

3.1 Create the application via CLI

vonage apps:create \
  --name="my-cloud-call-centre" \
  --voice_answer_url="https://placeholder.ngrok.io/webhooks/answer" \
  --voice_event_url="https://placeholder.ngrok.io/webhooks/event" \
  --voice_fallback_url="https://placeholder.ngrok.io/webhooks/fallback"

You'll see output like:

Application created: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Private key saved to: private.key

📝 Save your Application ID. You'll need it in your .env file.

The CLI automatically generates an RSA key pair and saves private.key to your current directory. This key is used to generate JWTs for authenticating API calls. Never commit this file to git.

3.2 List your applications to confirm

vonage apps:list
# Output:
# ID                                    Name
# xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  my-cloud-call-centre

STEP 4 — Buy a Virtual Phone Number

4.1 Search for available numbers

# Search for UK numbers
vonage numbers:search GB

# Search for US numbers
vonage numbers:search US

# Search for a specific area code (US example)
vonage numbers:search US --pattern=212

You'll see output like:

Country  MSisdn          Type    Monthly Cost
GB       447700900000    mobile  1.25 EUR
GB       447700900001    mobile  1.25 EUR
GB       441212345678    landline 0.50 EUR

4.2 Buy a number

vonage numbers:buy 447700900000 GB
# Output: Number 447700900000 successfully purchased

💡 Trial accounts: On a free trial account, Vonage gives you a test number and limits calls to verified numbers only. To call any number, add a payment method to upgrade.

4.3 Link the number to your application

vonage apps:link --number=447700900000 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# Output: Number 447700900000 linked to application xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The flow now looks like this:

Someone dials 447700900000
        │
        ▼
Vonage looks up: which application owns this number?
        │
        ▼
Application: my-cloud-call-centre
        │
        ▼
Fire webhook to: answer_url
(currently pointing to placeholder — we'll fix this next)

STEP 5 — Set Up ngrok

ngrok creates a secure tunnel from a public URL to your local machine. Vonage needs a public HTTPS URL to send webhooks — ngrok provides that during development.

┌──────────────────────────────────────────────────────────────┐
│                    HOW NGROK WORKS                           │
│                                                              │
│  Vonage                ngrok servers           Your machine  │
│  Platform                                                    │
│     │                                               │        │
│     │  POST https://                                │        │
│     │  abc123.ngrok.io  ──────────────────────►    │        │
│     │  /webhooks/answer                        localhost     │
│     │                                          :3000         │
│     │                                               │        │
│     │         ◄──────────────────────────────── 200 OK      │
│     │                                          + NCCO JSON   │
└──────────────────────────────────────────────────────────────┘

5.1 Install ngrok

# macOS
brew install ngrok

# Windows / Linux — download from https://ngrok.com/download
# or via npm:
npm install -g ngrok

5.2 Sign up for a free ngrok account

Go to ngrok.com and sign up. Get your auth token from the dashboard.

ngrok config add-authtoken YOUR_NGROK_TOKEN

5.3 Start the tunnel

We'll start our Node.js server on port 3000, so:

ngrok http 3000

You'll see:

ngrok

Session Status                online
Account                       your@email.com
Version                       3.x.x
Region                        Europe (eu)
Latency                       -
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Copy your ngrok URL — e.g. https://abc123.ngrok.io. You'll use this in your .env and Vonage application config.

⚠️ Free ngrok URLs change every restart. Each time you restart ngrok on the free plan, you get a new URL and must update Vonage. We'll cover using a stable domain in Day 29 (CI/CD). For now, just update the URL when needed.

STEP 6 — Update Your Vonage Application Webhook URLs

Now that you have a real ngrok URL, update your Vonage application:

vonage apps:update xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --voice_answer_url="https://abc123.ngrok.io/webhooks/answer" \
  --voice_event_url="https://abc123.ngrok.io/webhooks/event" \
  --voice_fallback_url="https://abc123.ngrok.io/webhooks/fallback"

Confirm the update:

vonage apps:show xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

STEP 7 — Build Your First Webhook Server

Now we write code. Let's build the Node.js server that answers calls.

7.1 Create the project

mkdir cloud-call-centre
cd cloud-call-centre
npm init -y
npm install express @vonage/server-sdk dotenv

7.2 Create your .env file

touch .env

Add your credentials:

# .env
VONAGE_API_KEY=your_api_key
VONAGE_API_SECRET=your_api_secret
VONAGE_APPLICATION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
VONAGE_PRIVATE_KEY_PATH=./private.key
VONAGE_NUMBER=447700900000
PORT=3000

7.3 Create .gitignore

touch .gitignore

# .gitignore
.env
private.key
node_modules/

✅ Always create .gitignore before your first git commit.

7.4 Create the server

// server.js
import 'dotenv/config';
import express from 'express';

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

// ──────────────────────────────────────────────
// ANSWER WEBHOOK
// Vonage calls this when someone dials your number
// You must return an NCCO array
// ──────────────────────────────────────────────
app.get('/webhooks/answer', (req, res) => {
  console.log('📞 Inbound call received:', {
    from: req.query.from,
    to: req.query.to,
    uuid: req.query.uuid,
    timestamp: new Date().toISOString()
  });

  // NCCO — the script for this call
  const ncco = [
    {
      action: 'talk',
      text: 'Hello! Welcome to your Cloud Call Centre, powered by Vonage. Your setup is working perfectly. Well done!',
      language: 'en-GB',
      style: 1  // Natural voice style
    },
    {
      action: 'talk',
      text: 'This is Day 3 of the Building Cloud Call Centres series. Stay tuned for more.',
      language: 'en-GB',
      style: 1
    }
  ];

  res.json(ncco);
});

// ──────────────────────────────────────────────
// EVENT WEBHOOK
// Vonage sends call status updates here
// Always return 200 OK
// ──────────────────────────────────────────────
app.post('/webhooks/event', (req, res) => {
  const event = req.body;

  console.log(`📊 Call event [${event.status}]:`, {
    uuid: event.uuid,
    status: event.status,
    direction: event.direction,
    from: event.from,
    to: event.to,
    timestamp: event.timestamp
  });

  // Log specific events we care about
  switch (event.status) {
    case 'started':
      console.log('   → Call started, waiting for answer');
      break;
    case 'ringing':
      console.log('   → Phone is ringing');
      break;
    case 'answered':
      console.log('   → Call answered!');
      break;
    case 'completed':
      console.log(`   → Call completed. Duration: ${event.duration}s`);
      break;
    case 'failed':
      console.error('   → Call failed:', event.reason);
      break;
  }

  res.status(200).end();
});

// ──────────────────────────────────────────────
// FALLBACK WEBHOOK
// Vonage calls this if the answer webhook fails
// Keep this simple and reliable
// ──────────────────────────────────────────────
app.get('/webhooks/fallback', (req, res) => {
  console.error('⚠️  Fallback webhook triggered — answer webhook failed');

  const ncco = [
    {
      action: 'talk',
      text: 'We are sorry, we are experiencing technical difficulties. Please call back shortly.',
      language: 'en-GB'
    }
  ];

  res.json(ncco);
});

// ──────────────────────────────────────────────
// HEALTH CHECK
// Useful for monitoring and load balancers
// ──────────────────────────────────────────────
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    service: 'cloud-call-centre',
    timestamp: new Date().toISOString(),
    uptime: process.uptime()
  });
});

// ──────────────────────────────────────────────
// START SERVER
// ──────────────────────────────────────────────
const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`
╔══════════════════════════════════════════════╗
║       Cloud Call Centre — Day 3 Setup        ║
╠══════════════════════════════════════════════╣
║  Server running on port ${PORT}                  ║
║                                              ║
║  Webhook endpoints:                          ║
║  GET  /webhooks/answer   ← inbound calls     ║
║  POST /webhooks/event    ← call events       ║
║  GET  /webhooks/fallback ← error fallback    ║
║  GET  /health            ← health check      ║
╚══════════════════════════════════════════════╝
  `);
});

7.5 Update package.json to use ES modules

{
  "name": "cloud-call-centre",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js"
  },
  "dependencies": {
    "@vonage/server-sdk": "^3.x.x",
    "dotenv": "^16.x.x",
    "express": "^4.x.x"
  }
}

STEP 8 — Test Everything End-to-End

8.1 Start your server

In terminal 1:

node server.js

You should see:

╔══════════════════════════════════════════════╗
║       Cloud Call Centre — Day 3 Setup        ║
╠══════════════════════════════════════════════╣
║  Server running on port 3000                 ║
...

8.2 Start ngrok

In terminal 2:

ngrok http 3000

8.3 Test the health endpoint

In terminal 3:

curl https://abc123.ngrok.io/health
# Output:
# {"status":"ok","service":"cloud-call-centre","timestamp":"...","uptime":12.3}

8.4 Test the answer webhook manually

Before calling, verify the NCCO response looks correct:

curl "https://abc123.ngrok.io/webhooks/answer?from=447700900001&to=447700900000&uuid=test-uuid-123"

Expected output:

[
  {
    "action": "talk",
    "text": "Hello! Welcome to your Cloud Call Centre, powered by Vonage. Your setup is working perfectly. Well done!",
    "language": "en-GB",
    "style": 1
  },
  {
    "action": "talk",
    "text": "This is Day 3 of the Building Cloud Call Centres series. Stay tuned for more.",
    "language": "en-GB",
    "style": 1
  }
]

8.5 Make the real call

Call your Vonage virtual number from your phone.

Watch your server terminal — you should see:

📞 Inbound call received: {
  from: '+447700900001',
  to: '+447700900000',
  uuid: '63f61863-4a51-4f6b-86e1-46edebio0391',
  timestamp: '2024-01-15T09:00:00.000Z'
}

📊 Call event [started]: { uuid: '63f...', status: 'started', ... }
📊 Call event [ringing]: { uuid: '63f...', status: 'ringing', ... }
📊 Call event [answered]: { uuid: '63f...', status: 'answered', ... }
   → Call answered!
📊 Call event [completed]: { uuid: '63f...', status: 'completed', ... }
   → Call completed. Duration: 18s

And on your phone you'll hear the welcome message spoken aloud. 🎉

STEP 9 — Understanding What Just Happened

Let's trace the exact sequence of what occurred:

YOUR PHONE                VONAGE                 YOUR SERVER (localhost)
    │                        │                           │
    │  dials virtual number  │                           │
    │───────────────────────►│                           │
    │                        │                           │
    │                        │  GET /webhooks/answer     │
    │                        │  ?from=...&to=...         │
    │                        │──────────────────────────►│
    │                        │                           │
    │                        │                           │  Build NCCO
    │                        │                           │  based on query params
    │                        │                           │
    │                        │  200 OK + NCCO JSON       │
    │                        │◄──────────────────────────│
    │                        │                           │
    │                        │  Executes NCCO:           │
    │                        │  • Converts text to speech│
    │                        │  • Streams audio to caller│
    │                        │                           │
    │  hears: "Hello!        │                           │
    │  Welcome to your..."   │                           │
    │◄───────────────────────│                           │
    │                        │                           │
    │  call ends             │                           │
    │───────────────────────►│                           │
    │                        │                           │
    │                        │  POST /webhooks/event     │
    │                        │  {status: "completed"}    │
    │                        │──────────────────────────►│
    │                        │                           │
    │                        │  200 OK                   │
    │                        │◄──────────────────────────│

STEP 10 — Project Structure & Next Steps

Your project should now look like this:

cloud-call-centre/
│
├── .env                  ← credentials (NEVER commit)
├── .gitignore            ← excludes .env and private.key
├── private.key           ← RSA key (NEVER commit)
├── package.json
├── server.js             ← main webhook server
│
└── (coming in future days)
    ├── routes/
    │   ├── voice.js      ← Day 6: Voice routing
    │   ├── sms.js        ← Day 7: SMS channel
    │   └── chat.js       ← Day 8: Web chat
    ├── ncco/
    │   └── builder.js    ← Day 11: IVR builder
    ├── agents/
    │   └── router.js     ← Day 5: Skills routing
    └── analytics/
        └── cdr.js        ← Day 21: CDR processing

We'll grow this folder structure day by day throughout the series.

🛠️ Troubleshooting Common Issues

ISSUE: ngrok URL not reachable
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Symptom: curl to ngrok URL times out
Fix:     Check your server is running on the correct port
         Check ngrok is pointing to the same port
         Try: curl http://localhost:3000/health first

─────────────────────────────────────────────────────────

ISSUE: Vonage webhook not firing
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Symptom: Phone rings but server logs nothing
Fix 1:   Check your application's answer_url is updated
         to the current ngrok URL
         vonage apps:show YOUR_APP_ID
Fix 2:   Check the number is linked to the application
         vonage numbers:list

─────────────────────────────────────────────────────────

ISSUE: "Trial account" error on outbound
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Symptom: "Non-Vonage number" error for inbound from
         unverified numbers on trial account
Fix:     Add your personal number to the verified list
         at dashboard.vonage.com → Test numbers

─────────────────────────────────────────────────────────

ISSUE: NCCO not executing (silent call)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Symptom: Call connects but no audio plays
Fix 1:   Check your NCCO JSON is valid
         (no trailing commas, proper array format)
Fix 2:   Check Content-Type is application/json
         (Express json() middleware handles this)
Fix 3:   Check the answer webhook returns 200
         not 201 or 204

─────────────────────────────────────────────────────────

ISSUE: private.key not found error
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Symptom: SDK throws ENOENT error on private.key
Fix:     Make sure private.key is in your project root
         The CLI saves it to wherever you ran
         vonage apps:create
         Copy it to your project directory

📦 Making an Outbound Call (Bonus)

Want to make Vonage call YOU instead of the other way around? Here's a quick bonus snippet:

// make-call.js — run with: node make-call.js
import Vonage from '@vonage/server-sdk';
import 'dotenv/config';

const vonage = new Vonage({
  apiKey: process.env.VONAGE_API_KEY,
  apiSecret: process.env.VONAGE_API_SECRET,
  applicationId: process.env.VONAGE_APPLICATION_ID,
  privateKey: process.env.VONAGE_PRIVATE_KEY_PATH
});

const response = await vonage.voice.createOutboundCall({
  to: [{
    type: 'phone',
    number: 'YOUR_PERSONAL_PHONE_NUMBER'  // e.g. 447700900001
  }],
  from: {
    type: 'phone',
    number: process.env.VONAGE_NUMBER
  },
  ncco: [
    {
      action: 'talk',
      text: 'Hello! This is an outbound call from your Cloud Call Centre. It works!'
    }
  ]
});

console.log('Outbound call created:', response);

Run it:

node make-call.js

Your phone will ring within seconds. When you answer, you'll hear the message. This is how automated outbound notifications, call-backs, and proactive outreach work — we'll use this extensively in later days.

✅ Day 3 Checklist

Before moving to Day 4, confirm:

  □ Vonage API account created
  □ vonage CLI installed and authenticated
  □ vonage balance shows credit
  □ Vonage Application created (note the App ID)
  □ private.key saved and in .gitignore
  □ Virtual phone number purchased
  □ Number linked to application
  □ ngrok installed and tunnel running
  □ Vonage application webhook URLs updated to ngrok URL
  □ Node.js server running on port 3000
  □ GET /health returns 200 OK
  □ GET /webhooks/answer returns valid NCCO JSON
  □ Real phone call received and voice played ← THE MAGIC MOMENT
  □ Server logs show call events (started, ringing, answered, completed)
  □ .env and private.key are in .gitignore

📁 Full File Reference

Here's every file from today in one place for reference:

.env

VONAGE_API_KEY=your_api_key
VONAGE_API_SECRET=your_api_secret
VONAGE_APPLICATION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
VONAGE_PRIVATE_KEY_PATH=./private.key
VONAGE_NUMBER=447700900000
PORT=3000

.gitignore

.env
private.key
node_modules/

package.json

{
  "name": "cloud-call-centre",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js"
  },
  "dependencies": {
    "@vonage/server-sdk": "^3.x.x",
    "dotenv": "^16.x.x",
    "express": "^4.x.x"
  }
}

🚀 What's Next

In Day 4 we go deeper on the Vonage Client SDK — building a browser-based softphone so your agents can answer calls directly in a web page. No phone hardware required.

You'll build a React component that:

Logs an agent in to Vonage
Listens for inbound calls
Answers / hangs up via browser UI
Shows the caller's number

This is the foundation of your agent desktop.

💬 Discussion

Did you get your first call working? Drop a 📞 in the comments!
What language are you using for your backend — Node.js or Python?
Any setup issues not covered in the troubleshooting section?

Series: Building Cloud Call Centres with Vonage APIs
← Day 2: Architecture Deep Dive | Day 3 of 30 | Day 4: Vonage Client SDK →

Series: Building Cloud Call Centres with Vonage APIs — Day 2 of 30

Shashi Kiran — Wed, 11 Mar 2026 13:03:01 +0000

Cloud Call Centre Architecture Deep Dive with Vonage

← Day 1: What is a Cloud Call Centre? | Day 3: Setup from Scratch →

🎯 What You'll Learn Today

By the end of this post, you'll be able to:

Explain every architectural component of a Vonage-powered cloud call centre
Understand how data flows between components in real time
Identify where your application code plugs into the Vonage platform
Make informed design decisions before writing a single line of code
Spot common architectural mistakes before they cost you in production

This is the post you'll come back to as a reference throughout the series.

🗺️ The 10,000-Foot View

Before going deep, let's establish the complete picture. A production cloud call centre built on Vonage has six architectural zones:

┌─────────────────────────────────────────────────────────────────────┐
│                  VONAGE CLOUD CALL CENTRE — ZONES                   │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  ZONE 1: CUSTOMER-FACING CHANNELS                            │  │
│  │  Voice · SMS · WhatsApp · Web Chat · Email · Video           │  │
│  └───────────────────────────┬───────────────────────────────────┘  │
│                              │                                      │
│  ┌───────────────────────────▼───────────────────────────────────┐  │
│  │  ZONE 2: VONAGE NETWORK LAYER                                │  │
│  │  PSTN Gateway · SIP Trunking · WebRTC Bridge · Number Pool   │  │
│  └───────────────────────────┬───────────────────────────────────┘  │
│                              │                                      │
│  ┌───────────────────────────▼───────────────────────────────────┐  │
│  │  ZONE 3: YOUR APPLICATION LAYER  ◄── YOU BUILD THIS          │  │
│  │  Webhook Handlers · NCCO Logic · Business Rules · State       │  │
│  └────────┬──────────────────┬──────────────────┬────────────────┘  │
│           │                  │                  │                   │
│  ┌────────▼────────┐ ┌───────▼───────┐ ┌───────▼────────┐         │
│  │  ZONE 4: AI &   │ │  ZONE 5:      │ │  ZONE 6:       │         │
│  │  AUTOMATION     │ │  AGENT LAYER  │ │  DATA LAYER    │         │
│  │                 │ │               │ │                │         │
│  │ IVR · Bots      │ │ Desktop · CRM │ │ CDRs · Reports │         │
│  │ Transcription   │ │ Skills Routing│ │ Analytics · DB │         │
│  │ Sentiment       │ │ Queuing       │ │ Compliance     │         │
│  └─────────────────┘ └───────────────┘ └────────────────┘         │
└─────────────────────────────────────────────────────────────────────┘

Now let's go deep into each zone.

🔵 Zone 1: Customer-Facing Channels

This is where your customers actually reach you. Vonage supports seven distinct channel types, all of which can be unified into a single routing and conversation system.

                    CUSTOMER ENTRY POINTS
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
  ┌──────────┐      ┌──────────┐      ┌──────────┐
  │  📞 PSTN │      │ 💬 Chat  │      │ 📱 Mobile│
  │  Voice   │      │  Web     │      │  Apps    │
  │          │      │  Widget  │      │          │
  │ Dial a   │      │ Embedded │      │ In-app   │
  │ number   │      │ on your  │      │ support  │
  │          │      │ website  │      │          │
  └────┬─────┘      └────┬─────┘      └────┬─────┘
       │                 │                  │
        ─────────────────┼──────────────────
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
  ┌──────────┐    ┌──────────┐    ┌──────────┐
  │ 📲 SMS   │    │📱WhatsApp│    │ 📧 Email │
  │          │    │          │    │          │
  │ Two-way  │    │ Business │    │ Inbound  │
  │ text     │    │ messaging│    │ support  │
  │          │    │          │    │ tickets  │
  └────┬─────┘    └────┬─────┘    └────┬─────┘
       │               │               │
        ───────────────┼───────────────
                       │
                       ▼
              VONAGE API LAYER
              (Zone 2 receives
               all of the above)

Key insight: Channels are just data

From an architectural perspective, every channel above eventually becomes a Vonage Conversation — a unified data structure that holds messages, participants, and events regardless of which channel they came from. This is the superpower of Vonage's design. More on this in Zone 3.

🔵 Zone 2: The Vonage Network Layer

This is Vonage's infrastructure — the part you don't manage directly but absolutely need to understand.

┌──────────────────────────────────────────────────────────────┐
│                  VONAGE NETWORK LAYER                        │
│                                                              │
│  ┌─────────────────┐     ┌─────────────────────────────┐   │
│  │  PSTN GATEWAY   │     │     WEBRTC BRIDGE           │   │
│  │                 │     │                             │   │
│  │  Converts       │     │  Converts browser/app       │   │
│  │  traditional    │     │  audio (WebRTC) ◄──►        │   │
│  │  phone calls    │     │  traditional telephony      │   │
│  │  to IP packets  │     │  (RTP/SIP)                  │   │
│  └────────┬────────┘     └──────────────┬──────────────┘   │
│           │                             │                    │
│           └──────────────┬──────────────┘                    │
│                          │                                   │
│                 ┌────────▼────────┐                          │
│                 │  MEDIA SERVER   │                          │
│                 │                 │                          │
│                 │ • Audio mixing  │                          │
│                 │ • Recording     │                          │
│                 │ • DTMF detect   │                          │
│                 │ • Transcoding   │                          │
│                 └────────┬────────┘                          │
│                          │                                   │
│  ┌─────────────────┐     │     ┌─────────────────────────┐  │
│  │  NUMBER POOL    │     │     │   SIP TRUNKING          │  │
│  │                 │     │     │                         │  │
│  │  Virtual phone  │     │     │  Connect your existing  │  │
│  │  numbers in     │─────┘     │  PBX or SIP provider    │  │
│  │  160+ countries │           │  to Vonage              │  │
│  └─────────────────┘           └─────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

What is a Vonage Virtual Number?

When a customer dials your call centre number, they dial a Vonage virtual number — a phone number hosted in Vonage's platform. This number is linked to your application via a webhook URL. The moment a call arrives, Vonage pings your server.

Customer dials: +44 20 7946 0123
                        │
                        ▼
         Is this a Vonage virtual number?
                        │
                       YES
                        │
                        ▼
         Look up the Answer Webhook URL
         for this number → https://yourapp.com/webhook/answer
                        │
                        ▼
         HTTP GET to your server
                        │
                        ▼
         Your server returns NCCO JSON
                        │
                        ▼
         Vonage executes the NCCO actions

This webhook-driven model is fundamental. Vonage never makes decisions — your code does.

🔵 Zone 3: Your Application Layer

This is where you live as a developer. Your application is the brain of the call centre.

┌───────────────────────────────────────────────────────────────────┐
│                   YOUR APPLICATION LAYER                          │
│                                                                   │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                  WEBHOOK HANDLERS                           │  │
│  │                                                             │  │
│  │  POST /webhooks/answer    ← Vonage fires when a call arrives│  │
│  │  POST /webhooks/event     ← Vonage fires on call events     │  │
│  │  POST /webhooks/fallback  ← Vonage fires on errors          │  │
│  │  POST /webhooks/recording ← Vonage fires when rec. ready    │  │
│  │  POST /webhooks/message   ← Vonage fires on SMS/chat msg    │  │
│  └───────────────────┬─────────────────────────────────────────┘  │
│                      │                                            │
│                      ▼                                            │
│  ┌─────────────────────────────────────────────────────────┐      │
│  │                  BUSINESS LOGIC                         │  │
│  │                                                         │  │
│  │  • Which IVR menu to present?                           │  │
│  │  • Which agent skill is needed?                         │  │
│  │  • Is it within business hours?                         │  │
│  │  • Is this customer a VIP? (CRM lookup)                 │  │
│  │  • Should this call be recorded?                        │  │
│  │  • What language should the IVR speak?                  │  │
│  └───────────────────┬─────────────────────────────────────┘  │
│                      │                                         │
│                      ▼                                         │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │                  NCCO BUILDER                           │  │
│  │                                                         │  │
│  │  Dynamically construct NCCO JSON based on logic above   │  │
│  │  Return it to Vonage as the HTTP response               │  │
│  └───────────────────┬─────────────────────────────────────┘  │
│                      │                                         │
│          ┌───────────┼───────────┐                            │
│          ▼           ▼           ▼                            │
│    Vonage API    Database     External                        │
│    Calls         (State)      Services                        │
│    (outbound)                 (CRM, AI)                       │
└───────────────────────────────────────────────────────────────┘

The Webhook Request/Response Cycle

Every interaction in a Vonage call centre follows this pattern:

  YOUR SERVER                          VONAGE
       │                                  │
       │                                  │  Customer dials in
       │                                  │◄─────────────────
       │                                  │
       │  POST /webhooks/answer           │
       │◄─────────────────────────────────│
       │  Body: { from, to, uuid, ... }   │
       │                                  │
       │  200 OK + NCCO JSON              │
       │─────────────────────────────────►│
       │                                  │
       │                                  │  Executes NCCO
       │                                  │  (plays greeting,
       │                                  │   records, connects)
       │                                  │
       │  POST /webhooks/event            │
       │◄─────────────────────────────────│
       │  Body: { status: "answered" }    │
       │                                  │
       │  200 OK                          │
       │─────────────────────────────────►│
       │                                  │
       │  POST /webhooks/event            │
       │◄─────────────────────────────────│
       │  Body: { status: "completed",    │
       │          duration: 245 }         │
       │                                  │
       │  200 OK                          │
       │─────────────────────────────────►│

⚠️ Critical rule: Your webhook endpoints must respond within 3 seconds. Vonage will time out and try the fallback URL if you take too long. Keep business logic fast — offload heavy work asynchronously.

🔵 The Conversation API: Vonage's Unified Data Model

The Conversation API is the single most important API to understand in this stack. It is the data layer that unifies every channel.

┌──────────────────────────────────────────────────────────────┐
│              CONVERSATION API DATA MODEL                     │
│                                                              │
│                    CONVERSATION                              │
│              ┌─────────────────────┐                        │
│              │  id: CON-abc123      │                        │
│              │  display_name:       │                        │
│              │   "Support - Alice"  │                        │
│              │  state: ACTIVE       │                        │
│              └──────────┬──────────┘                        │
│                         │                                    │
│         ┌───────────────┼────────────────┐                  │
│         ▼               ▼                ▼                  │
│    ┌─────────┐     ┌─────────┐     ┌─────────┐             │
│    │ MEMBER  │     │ MEMBER  │     │ MEMBER  │             │
│    │         │     │         │     │         │             │
│    │Customer │     │  Agent  │     │  Bot    │             │
│    │ Alice   │     │  Bob    │     │ (IVR)   │             │
│    │         │     │         │     │         │             │
│    │ channel:│     │ channel:│     │ channel:│             │
│    │  voice  │     │   app   │     │   app   │             │
│    └────┬────┘     └────┬────┘     └────┬────┘             │
│         │               │               │                   │
│         └───────────────┼───────────────┘                   │
│                         │                                    │
│                         ▼                                    │
│              ┌──────────────────┐                           │
│              │     EVENTS       │                           │
│              │                  │                           │
│              │ • member:joined  │                           │
│              │ • member:left    │                           │
│              │ • audio:say:done │                           │
│              │ • audio:record   │                           │
│              │ • message:submit │                           │
│              └──────────────────┘                           │
└──────────────────────────────────────────────────────────────┘

Why This Matters

The magic of the Conversation API is that a customer can start on web chat, escalate to voice, and both interactions live in the same Conversation object. The agent sees the full history.

SAME CUSTOMER — DIFFERENT CHANNELS — ONE CONVERSATION

  10:00 AM  Customer opens web chat
            "Hi, I have a billing question."
                    │
                    ▼ Conversation CON-abc123 created

  10:04 AM  Customer frustrated, clicks "Call Me."
            Voice call initiated
                    │
                    ▼ Voice MEMBER added to CON-abc123

  10:05 AM  Agent answers
            Sees: "This customer was chatting
                   about billing since 10:00."
                    │
                    ▼ Full context preserved, no repeat needed

  10:12 AM  Issue resolved
            Both chat messages and call recordings
            stored in CON-abc123

🔵 Zone 4: The AI & Automation Layer

This zone sits between your application logic and the customer. It handles contacts that don't immediately need a human agent.

┌────────────────────────────────────────────────────────────────┐
│                    AI & AUTOMATION LAYER                       │
│                                                                │
│                         INBOUND CONTACT                        │
│                               │                                │
│                               ▼                                │
│             ┌─────────────────────────────────┐               │
│             │         IVR / BOT LAYER         │               │
│             │                                 │               │
│             │  Can this be resolved without   │               │
│             │  a human agent?                 │               │
│             └────────────────┬────────────────┘               │
│                              │                                 │
│               ┌──────────────┼──────────────┐                 │
│               │              │              │                 │
│               ▼              ▼              ▼                 │
│         ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│         │  DTMF    │  │   NLU    │  │ SELF     │            │
│         │  IVR     │  │   Bot    │  │ SERVICE  │            │
│         │          │  │          │  │          │            │
│         │ Press 1  │  │ "I want  │  │ Balance  │            │
│         │ for Sales│  │  to check│  │ check,   │            │
│         │ Press 2  │  │  my bill"│  │ order    │            │
│         │ for Supp.│  │          │  │ status,  │            │
│         └────┬─────┘  └────┬─────┘  │ FAQs     │            │
│              │             │        └────┬─────┘            │
│              │             │             │                   │
│              └─────────────┼─────────────┘                   │
│                            │                                  │
│                     Resolved?                                 │
│                     │       │                                 │
│                    YES      NO                                │
│                     │       │                                 │
│                     ▼       ▼                                 │
│               End call  Escalate to                           │
│                         human agent                           │
│                         (with context)                        │
└────────────────────────────────────────────────────────────────┘

Real-Time AI Assistants

Beyond IVR, Vonage's audio streaming capability allows you to run AI models during a live call:

                    LIVE CALL AI PIPELINE

  Customer speaking ──► Vonage Media Server
                              │
                              │ Audio stream (WebSocket)
                              ▼
                      Your App / ASR Service
                       (e.g., Google STT,
                        AWS Transcribe)
                              │
                              │ Text transcript
                              ▼
                        NLU / LLM Layer
                     (Intent detection,
                      sentiment scoring,
                      suggested responses)
                              │
                              │ Insights via WebSocket
                              ▼
                       Agent Desktop UI
                     (Shows agent: "Customer
                      seems frustrated,
                      suggest discount offer")

🔵 Zone 5: The Agent Layer

The agent layer is what your agents interact with every day. Understanding its components is critical to designing a good agent experience.

┌──────────────────────────────────────────────────────────────┐
│                     AGENT LAYER                              │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                 AGENT DESKTOP                       │    │
│  │                                                     │    │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────┐  │    │
│  │  │  SOFTPHONE   │  │  CUSTOMER    │  │  QUEUE   │  │    │
│  │  │              │  │  CONTEXT     │  │  STATUS  │  │    │
│  │  │ Answer/Hold  │  │              │  │          │  │    │
│  │  │ Transfer     │  │ Name, account│  │ Waiting: │  │    │
│  │  │ Conference   │  │ history,     │  │    4     │  │    │
│  │  │ Mute/unmute  │  │ previous     │  │ Avg wait:│  │    │
│  │  │              │  │ contacts,    │  │  1m 20s  │  │    │
│  │  │ [WebRTC]     │  │ open tickets │  │          │  │    │
│  │  └──────────────┘  └──────────────┘  └──────────┘  │    │
│  └──────────────────────────┬────────────────────────────┘    │
│                             │                                │
│  ┌──────────────────────────▼────────────────────────────┐   │
│  │              VONAGE CLIENT SDK                        │   │
│  │                                                       │   │
│  │  Handles all WebRTC audio in the browser              │   │
│  │  Listens for incoming calls                           │   │
│  │  Emits events: call:received, call:answered, etc.     │   │
│  └──────────────────────────┬────────────────────────────┘   │
│                             │                                 │
│           ┌─────────────────┼─────────────────┐              │
│           ▼                 ▼                 ▼              │
│    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│    │  ROUTING    │  │    SKILLS   │  │   AGENT     │        │
│    │  ENGINE     │  │  MANAGEMENT │  │   STATUS    │        │
│    │             │  │             │  │             │        │
│    │ Which agent │  │ Define skill│  │ Available   │        │
│    │ gets this   │  │ groups:     │  │ Busy        │        │
│    │ contact?    │  │ • Billing   │  │ Wrap-up     │        │
│    │             │  │ • Technical │  │ Offline     │        │
│    │ Priority,   │  │ • Spanish   │  │             │        │
│    │ skills,     │  │ • VIP       │  │             │        │
│    │ availability│  │             │  │             │        │
│    └─────────────┘  └─────────────┘  └─────────────┘        │
└──────────────────────────────────────────────────────────────┘

Skills-Based Routing Flow

  INBOUND CONTACT ARRIVES
           │
           ▼
  What skill does this contact need?
  (determined by IVR input or channel)
           │
    ┌──────┴──────┐
    │             │
    ▼             ▼
  Billing      Technical
  Support      Support
    │             │
    ▼             ▼
  Find available agent    Find available agent
  with BILLING skill      with TECHNICAL skill
    │                         │
    ▼                         ▼
  Agent found?           Agent found?
  │         │            │         │
 YES        NO          YES        NO
  │         │            │         │
  ▼         ▼            ▼         ▼
Connect   Queue      Connect    Queue
 now     customer    now      customer
          │                      │
          ▼                      ▼
     Wait for the next      Offer callback
     available agent        or voicemail

🔵 Zone 6: The Data Layer

Every interaction generates data. This zone is responsible for storing, processing, and surfacing that data.

┌──────────────────────────────────────────────────────────────┐
│                      DATA LAYER                              │
│                                                              │
│  DATA SOURCES                                                │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌─────────┐  │
│  │ Call      │  │ Vonage    │  │ Agent     │  │ CSAT    │  │
│  │ Events    │  │ Reports   │  │ Activity  │  │ Surveys │  │
│  │ (webhooks)│  │ API (CDRs)│  │ (status)  │  │         │  │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └────┬────┘  │
│        │              │              │              │        │
│        └──────────────┼──────────────┘──────────────┘        │
│                       │                                      │
│                       ▼                                      │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                 DATA PIPELINE                          │  │
│  │                                                        │  │
│  │  Ingest ──► Normalise ──► Store ──► Query ──► Visualise│  │
│  └────────────────────────────────────────────────────────┘  │
│                       │                                      │
│         ┌─────────────┼─────────────┐                       │
│         ▼             ▼             ▼                       │
│  ┌─────────────┐ ┌─────────┐ ┌──────────────┐             │
│  │  REAL-TIME  │ │HISTORICAL│ │  COMPLIANCE  │             │
│  │  DASHBOARD  │ │REPORTING │ │  & AUDIT     │             │
│  │             │ │          │ │              │             │
│  │ Live queue  │ │ Daily CDR│ │ Call records │             │
│  │ Agent status│ │ Trends   │ │ Retention    │             │
│  │ SLA alerts  │ │ CSAT avg │ │ GDPR logs    │             │
│  │ Active calls│ │ Handle   │ │ PCI masking  │             │
│  │             │ │   time   │ │              │             │
│  └─────────────┘ └─────────┘ └──────────────┘             │
└──────────────────────────────────────────────────────────────┘

What's in a CDR?

A Call Detail Record (CDR) from Vonage's Reports API contains:

{
  "record_index": 0,
  "call_uuid": "63f61863-4a51-4f6b-86e1-46edebio0391",
  "conversation_uuid": "CON-abc123",
  "direction": "inbound",
  "from": "+441234567890",
  "to": "+442079460123",
  "date_start": "2024-01-15T09:00:00Z",
  "date_end": "2024-01-15T09:04:05Z",
  "duration": "245",
  "rate": "0.00450",
  "price": "0.01838",
  "network": "GB-FIXED",
  "status": "completed",
  "recording_url": "https://api.nexmo.com/v1/files/...",
  "agent_id": "agent-bob",
  "queue_time": "32",
  "handle_time": "213"
}

We'll use this data in Week 5 to build real-time dashboards and analytics.

🔄 End-to-End Architecture: Putting It All Together

Now let's trace a complete, realistic scenario from start to finish. A customer calls with a billing dispute:

STEP 1: CALL ARRIVES
━━━━━━━━━━━━━━━━━━━━
Customer dials +44 20 7946 0123
        │
        ▼
Vonage receives call on virtual number
        │
        ▼
POST /webhooks/answer fired to your app
        │
        ▼
Your app queries CRM: "Is this a known customer?"
        │
       YES — VIP customer identified
        │
        ▼
NCCO returned: Skip standard IVR, play VIP greeting


STEP 2: IVR / INTENT DETECTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NCCO: "Welcome back, Sarah. How can we help you today?"
        │
        ▼
Customer speaks: "I have a problem with my bill."
        │
        ▼
Vonage ASR detects speech → sends to NLU
        │
        ▼
Intent: BILLING_DISPUTE, Sentiment: NEGATIVE
        │
        ▼
Routing decision: needs BILLING_SENIOR skill


STEP 3: ROUTING
━━━━━━━━━━━━━━━
Query agent pool: who has BILLING_SENIOR skill?
        │
        ▼
Agent Bob — Available ✅
Agent Carol — Busy ❌
Agent Dave — Wrap-up ❌
        │
        ▼
Assign to Agent Bob


STEP 4: AGENT NOTIFICATION
━━━━━━━━━━━━━━━━━━━━━━━━━━
Vonage Client SDK fires call:received on Bob's browser
        │
        ▼
Agent desktop shows:
  • Customer: Sarah Johnson
  • Account value: £4,200/yr (VIP)
  • Intent: Billing dispute
  • Sentiment: Negative ⚠️
  • Previous contacts: 2 (last: billing, 3 months ago)
  • Suggested action: "Offer goodwill credit"
        │
        ▼
Bob clicks "Answer"


STEP 5: CONNECTED
━━━━━━━━━━━━━━━━━
WebRTC audio channel established
Both parties connected
Recording starts (with consent tone)
Real-time transcription begins → feeds AI assistant


STEP 6: RESOLUTION & POST-CALL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Call ends (Bob clicks "End")
        │
        ▼
Vonage fires POST /webhooks/event {status: "completed"}
        │
        ├──► CDR written to database
        ├──► Recording stored in object storage
        ├──► CRM updated with call outcome
        ├──► CSAT survey SMS sent to Sarah
        └──► Analytics dashboard updated in real time

⚡ Architecture Decision: Stateless vs Stateful

One of the most important architectural decisions you'll make is how your application manages state during a call.

Option A: Stateless (Recommended for simplicity)

┌──────────────────────────────────────────────────────────────┐
│  STATELESS ARCHITECTURE                                      │
│                                                              │
│  Each webhook request contains everything you need           │
│  No in-memory state — all state from Vonage or DB            │
│                                                              │
│  Webhook arrives                                             │
│      │                                                       │
│      ▼                                                       │
│  Extract call UUID from request                              │
│      │                                                       │
│      ▼                                                       │
│  Fetch state from Redis/DB using UUID                        │
│      │                                                       │
│      ▼                                                       │
│  Apply business logic                                        │
│      │                                                       │
│      ▼                                                       │
│  Return NCCO / 200 OK                                        │
│                                                              │
│  ✅ Scales horizontally — run 10 instances, no problem       │
│  ✅ Survives server restarts                                  │
│  ✅ Easy to debug — each request is self-contained           │
└──────────────────────────────────────────────────────────────┘

Option B: Stateful (Simpler but fragile)

┌──────────────────────────────────────────────────────────────┐
│  STATEFUL ARCHITECTURE                                       │
│                                                              │
│  Call state stored in application memory (Map, object)       │
│                                                              │
│  // In-memory call store                                     │
│  const calls = new Map();                                    │
│  calls.set(callUUID, { step: 'ivr', customer: 'sarah' });   │
│                                                              │
│  ❌ Fails if server restarts mid-call                        │
│  ❌ Doesn't scale — webhook must hit same instance           │
│  ❌ Memory leak risk on high volume                           │
│  ⚠️  OK for local dev / prototypes only                      │
└──────────────────────────────────────────────────────────────┘

💡 Recommendation: Use Redis as your state store from Day 1. It's fast enough for real-time call state and survives restarts.

🌐 Deployment Architecture

Where do you run your application backend? Here are the three common patterns:

PATTERN 1: SINGLE SERVER (Dev/Small scale)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Vonage ──► Your VPS/EC2 ──► App + Redis
  Simple but single point of failure


PATTERN 2: CONTAINERISED (Recommended)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Vonage ──► Load Balancer
                 │
          ┌──────┼──────┐
          ▼      ▼      ▼
       App 1  App 2  App 3  (stateless)
          │      │      │
          └──────┼──────┘
                 ▼
              Redis
              (shared state)
  Scales horizontally, survives instance failure


PATTERN 3: SERVERLESS (Event-driven)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Vonage ──► API Gateway ──► Lambda/Cloud Functions
                                      │
                                   DynamoDB / Redis
  Pay-per-call, infinite scale
  Watch for cold start latency (must respond in 3s!)

🔒 Security Architecture Overview

Security sits across every zone. Here's where each control lives:

┌──────────────────────────────────────────────────────────────┐
│               SECURITY CONTROLS BY ZONE                     │
│                                                              │
│  Zone 1 (Channels)                                           │
│    • Number masking for privacy                              │
│    • TLS 1.2+ for all channel data in transit                │
│                                                              │
│  Zone 2 (Vonage Network)                                     │
│    • SRTP for encrypted audio                                │
│    • Vonage signs all webhooks (JWT / signature header)      │
│                                                              │
│  Zone 3 (Your App)                                           │
│    • Validate Vonage webhook signatures on every request     │
│    • Store API keys in environment variables / secrets mgr   │
│    • HTTPS-only endpoints                                    │
│                                                              │
│  Zone 4 (AI Layer)                                           │
│    • PCI: Pause recording during card number input           │
│    • GDPR: Consent before recording                          │
│                                                              │
│  Zone 5 (Agent Layer)                                        │
│    • JWT-based agent authentication                          │
│    • Role-based access control (RBAC)                        │
│    • Screen recording audit logs                             │
│                                                              │
│  Zone 6 (Data Layer)                                         │
│    • Encryption at rest for recordings                       │
│    • Retention policies (auto-delete after N days)           │
│    • Audit trail for all data access                         │
└──────────────────────────────────────────────────────────────┘

We'll implement all of these in Week 6. For now, just know where they belong.

📐 Designing for Scale: Numbers to Know

Before you design, know your scale targets. Here are reference figures for Vonage architecture:

Metric	Small (Startup)	Medium (SME)	Large (Enterprise)
Concurrent calls	< 50	50–500	500–5,000+
Agents	5–20	20–200	200–2,000+
Webhook response budget	3 seconds	3 seconds	3 seconds
Recommended state store	Redis single	Redis cluster	Redis cluster + read replicas
Recommended deploy	Single container	K8s / ECS	K8s multi-region
CDR storage	PostgreSQL	PostgreSQL + S3	Data warehouse (Snowflake / BigQuery)

🧪 Architecture Anti-Patterns to Avoid

Learn from common mistakes before you make them:

❌ ANTI-PATTERN 1: Synchronous CRM lookup in webhook handler
   Webhook fires → you query Salesforce → Salesforce takes 4s
   Result: Vonage times out, call fails

   ✅ FIX: Cache CRM data in Redis (TTL 5 min)
           or query async + use default NCCO if not ready

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ ANTI-PATTERN 2: One webhook URL for everything
   POST /webhook handles ALL events
   Complex if/else logic, hard to debug

   ✅ FIX: Separate routes per event type
           /webhooks/answer
           /webhooks/event
           /webhooks/recording

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ ANTI-PATTERN 3: Storing recordings on your app server
   Recordings fill disk, no redundancy, not CDN-cached

   ✅ FIX: Stream recordings directly to S3/GCS on receipt
           Use presigned URLs for agent access

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ ANTI-PATTERN 4: No fallback webhook URL
   Your server goes down mid-call
   Vonage has nowhere to send events → call hangs

   ✅ FIX: Always configure a fallback URL
           Use a secondary server or a simple Lambda
           that queues events for retry

🗂️ Technology Stack Reference

Here's a recommended stack for building on Vonage. We'll use this throughout the series:

┌──────────────────────────────────────────────────────────────┐
│           RECOMMENDED TECHNOLOGY STACK                       │
│                                                              │
│  Backend Language   │  Node.js 20 (Express or Fastify)       │
│                     │  Python 3.12 (FastAPI)                 │
│                     │  (examples in both throughout series)  │
│                     │                                        │
│  State Store        │  Redis 7                               │
│                     │                                        │
│  Database           │  PostgreSQL 16 (for CDRs, records)     │
│                     │                                        │
│  Message Queue      │  Redis Pub/Sub or BullMQ               │
│                     │  (async post-call processing)          │
│                     │                                        │
│  Object Storage     │  AWS S3 or GCS                         │
│                     │  (recordings, exports)                 │
│                     │                                        │
│  Agent Desktop      │  React 18 + Vonage Client SDK          │
│                     │                                        │
│  Infrastructure     │  Docker + docker-compose (local dev)   │
│                     │  Kubernetes or ECS (production)        │
│                     │                                        │
│  CI/CD              │  GitHub Actions                        │
│                     │                                        │
│  Local Tunnelling   │  ngrok (Vonage webhooks in local dev)  │
└──────────────────────────────────────────────────────────────┘

✅ Architecture Checklist

Before starting to build, run through this checklist:

ARCHITECTURE PLANNING CHECKLIST

  Channels
  □ Which channels do you need? (voice, SMS, chat, WhatsApp)
  □ Do you need omnichannel (unified history across channels)?

  Routing
  □ What skills/queues do you need?
  □ Do you need time-of-day routing?
  □ What's the overflow strategy (queue, voicemail, callback)?

  IVR / Automation
  □ DTMF menus or natural language?
  □ What can be self-served without an agent?
  □ What's the escalation path?

  Application
  □ What language/framework for the backend?
  □ Where are webhook handlers deployed?
  □ What's your state store? (Redis recommended)
  □ Fallback webhook URL configured?

  Agent Experience
  □ Custom agent desktop or existing CRM embed?
  □ What context does the agent need at call answer?
  □ What post-call wrap-up workflow is needed?

  Data & Analytics
  □ Where are CDRs stored?
  □ What real-time metrics do supervisors need?
  □ What's the recording retention policy?

  Security
  □ Webhook signature validation in place?
  □ API keys in secrets manager (not code)?
  □ Recording encryption and access control?
  □ GDPR consent flow for recordings?

🚀 What's Next

In Day 3, we get hands-on. We'll:

Create your Vonage API account
Install the Vonage CLI
Buy a virtual phone number
Set up ngrok for local webhook development
Deploy a working "Hello World" call handler that answers a real phone call

By the end of Day 3 you'll be able to call a real phone number and have your code answer it.

💬 Discussion

Now that you've seen the full architecture:

Which zone are you most interested to build first?
Are you building for a startup, migrating from an on-premise PBX, or adding call centre capabilities to an existing product?
Any architectural patterns from your own experience you'd add?

Drop a comment below — your questions shape the depth of future posts.

📌 Bookmark this post — it's your architecture reference for the entire series.

🔔 Follow for Day 3: Setup from Scratch — tomorrow.

Series: Building Cloud Call Centres with Vonage APIs
← Day 1: What is a Cloud Call Centre? | Day 2 of 30 | Day 3: Setup from Scratch →

Series: Building Cloud Call Centres with Vonage APIs — Day 1 of 30

Shashi Kiran — Tue, 10 Mar 2026 19:11:17 +0000

What is a Cloud Call Centre? A Developer's Introduction with Vonage

👋 Who Is This For?

Whether you're a backend developer being handed a brief to "build a contact centre", a solutions architect evaluating CCaaS platforms, or a curious engineer who has never touched telephony before — this series is for you.

Over 30 posts, we'll go from zero to production-ready cloud call centre, using Vonage APIs as our backbone. We'll cover voice, SMS, WhatsApp, web chat, AI/IVR, analytics, security, and DevOps — with real code, real diagrams, and real decisions.

Today we start at the very beginning: What exactly is a cloud call centre, and why does Vonage make it a uniquely developer-friendly choice?

📞 Traditional Call Centres vs Cloud Call Centres

Before we write a single line of code, let's understand the problem we're solving.

The Old World: On-Premise PBX

A traditional call centre looked like this:

┌─────────────────────────────────────────────────┐
│              ON-PREMISE CALL CENTRE             │
│                                                 │
│  PSTN Lines ──► PBX Hardware ──► Agent Phones  │
│                     │                           │
│                 IVR Server                      │
│                 (on-site)                       │
│                     │                           │
│              ACD (Auto Call                     │
│              Distributor)                       │
│                     │                           │
│           ┌─────────┴──────────┐                │
│        Agent 1             Agent 2              │
│        Desktop             Desktop              │
└─────────────────────────────────────────────────┘

PBX = Private Branch Exchange
ACD = Automatic Call Distributor

The problems with this model:

💸 Massive upfront hardware costs (PBX systems cost tens of thousands)
🔧 Dedicated IT staff to maintain physical servers
📍 Agents must be physically present
📈 Scaling up means buying more hardware
🔗 Each channel (voice, email, chat) is a separate silo
🐌 Any change requires a vendor engineer on-site

The New World: Cloud Call Centre

A cloud call centre moves all of that infrastructure off-premise and onto APIs:

┌──────────────────────────────────────────────────────────────┐
│                    CLOUD CALL CENTRE                         │
│                                                              │
│   Customer                  Vonage Cloud                     │
│   Channels                  Platform                         │
│                                                              │
│  📞 Phone Call ──────────►  ┌──────────────┐                │
│  💬 Web Chat  ──────────►  │   Routing &  │ ──► Agent A     │
│  📱 WhatsApp  ──────────►  │   Queuing    │     (anywhere)  │
│  💻 SMS       ──────────►  │   Engine     │ ──► Agent B     │
│  📧 Email     ──────────►  └──────────────┘     (anywhere)  │
│                                   │                          │
│                          ┌────────┴────────┐                 │
│                       Analytics         AI/IVR               │
│                       Dashboard         Bot Layer            │
└──────────────────────────────────────────────────────────────┘

The benefits:

✅ No hardware — infrastructure runs in Vonage's cloud
✅ Agents work from anywhere (laptop + headset = fully functional agent)
✅ Scale from 1 to 1,000 agents with an API call
✅ All channels unified in one platform
✅ Pay per use — no idle hardware costs
✅ You — the developer — control everything via APIs

🏗️ The Anatomy of a Cloud Call Centre

A cloud call centre is made up of several distinct layers. Understanding these layers is essential before we start building.

┌────────────────────────────────────────────────────────────┐
│                CLOUD CALL CENTRE LAYERS                    │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  LAYER 5 │  Reporting & Analytics                         │
│          │  (Dashboards, CDRs, KPIs, CSAT)                │
│          │                                                 │
├──────────┼─────────────────────────────────────────────────┤
│          │                                                 │
│  LAYER 4 │  Agent Desktop / CRM                           │
│          │  (What agents see and use)                      │
│          │                                                 │
├──────────┼─────────────────────────────────────────────────┤
│          │                                                 │
│  LAYER 3 │  Routing Engine                                │
│          │  (Skills-based, priority, time-of-day)         │
│          │                                                 │
├──────────┼─────────────────────────────────────────────────┤
│          │                                                 │
│  LAYER 2 │  Automation & AI                               │
│          │  (IVR, Chatbots, Transcription, Sentiment)     │
│          │                                                 │
├──────────┼─────────────────────────────────────────────────┤
│          │                                                 │
│  LAYER 1 │  Channel Connectors                            │
│          │  (Voice, SMS, WhatsApp, Chat, Email)           │
│          │                                                 │
└──────────┴─────────────────────────────────────────────────┘

We will build every single one of these layers across this 30-post series. Each post maps to a specific layer and capability.

🔌 Where Vonage Fits In

Vonage (now part of Ericsson) provides a suite of Communication APIs that power every layer of the stack above. Unlike traditional CCaaS vendors that give you a fixed product to configure, Vonage gives you programmable building blocks.

Here's the Vonage API landscape relevant to cloud call centres:

┌─────────────────────────────────────────────────────────────┐
│                  VONAGE API ECOSYSTEM                       │
│                                                             │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐    │
│  │  Voice API  │  │ Messages API │  │Conversation API│    │
│  │             │  │              │  │                │    │
│  │ • Inbound   │  │ • SMS        │  │ • Unified      │    │
│  │   calls     │  │ • WhatsApp   │  │   channel      │    │
│  │ • Outbound  │  │ • Facebook   │  │   history      │    │
│  │   calls     │  │   Messenger  │  │ • Members      │    │
│  │ • Recording │  │ • Viber      │  │ • Events       │    │
│  │ • NCCO flow │  │ • MMS        │  │ • Webhooks     │    │
│  └─────────────┘  └──────────────┘  └────────────────┘    │
│                                                             │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐    │
│  │  Client SDK │  │   Video API  │  │  Reports API   │    │
│  │             │  │              │  │                │    │
│  │ • Browser   │  │ • WebRTC     │  │ • CDRs         │    │
│  │   calling   │  │   video      │  │ • Usage data   │    │
│  │ • iOS/Android│  │   calls      │  │ • Billing      │    │
│  │ • Agent     │  │ • Screen     │  │   records      │    │
│  │   desktop   │  │   share      │  │                │    │
│  └─────────────┘  └──────────────┘  └────────────────┘    │
└─────────────────────────────────────────────────────────────┘

The Key Differentiator: NCCO

One of Vonage's most powerful concepts is the Nexmo Call Control Object (NCCO) — a JSON structure that controls what happens during a call. Instead of clicking through a GUI, you write JSON:

[
  {
    "action": "talk",
    "text": "Welcome to Cloud Call Centre. Please hold while we connect you."
  },
  {
    "action": "record",
    "eventUrl": ["https://yourapp.com/webhooks/recording"]
  },
  {
    "action": "connect",
    "endpoint": [
      {
        "type": "app",
        "user": "agent-alice"
      }
    ]
  }
]

This single JSON snippet: greets the caller, starts recording, and connects them to an agent named Alice. We'll go deep on NCCO in Day 6.

🔄 How a Call Flows Through a Cloud Call Centre

Let's trace the journey of a single inbound call — from a customer picking up the phone to speaking with an agent:

Customer dials
0800 123 456
     │
     ▼
┌─────────────┐
│  PSTN / VoIP│  ← Public telephone network
│  Network    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Vonage    │  ← Your virtual phone number lives here
│   Platform  │    Vonage receives the call
└──────┬──────┘
       │  HTTP webhook fired to your app
       ▼
┌─────────────┐
│  Your App   │  ← Your Node.js / Python / any language backend
│  (Backend)  │    Returns NCCO JSON instructions
└──────┬──────┘
       │  NCCO tells Vonage what to do
       ▼
┌─────────────┐
│   IVR / Bot │  ← "Press 1 for Sales, 2 for Support"
│   Layer     │    or AI-powered natural language
└──────┬──────┘
       │  Customer selects option / intent detected
       ▼
┌─────────────┐
│   Routing   │  ← Find the best available agent
│   Engine    │    based on skills, priority, wait time
└──────┬──────┘
       │  Agent matched
       ▼
┌─────────────┐
│  Agent      │  ← Agent's browser or app rings
│  Desktop    │    via Vonage Client SDK (WebRTC)
└──────┬──────┘
       │
       ▼
   🎉 Customer and Agent
      connected!
       │
       ▼
┌─────────────┐
│  Post-Call  │  ← Recording stored, CDR logged,
│  Processing │    CSAT survey triggered, CRM updated
└─────────────┘

This entire flow is programmable. Every step fires a webhook to your backend. You control the logic.

🆚 Vonage vs The Alternatives

You might be wondering: why Vonage? Let's do a quick honest comparison:

┌──────────────┬────────────┬──────────────┬──────────┬──────────────┐
│ Feature      │  Vonage    │ Twilio Flex  │ AWS      │ Genesys      │
│              │            │              │ Connect  │ Cloud        │
├──────────────┼────────────┼──────────────┼──────────┼──────────────┤
│ API-first    │     ✅     │      ✅      │    ⚠️    │     ❌       │
│ approach     │            │              │          │              │
├──────────────┼────────────┼──────────────┼──────────┼──────────────┤
│ Developer    │   High     │    High      │ Medium   │    Low       │
│ experience   │            │              │          │              │
├──────────────┼────────────┼──────────────┼──────────┼──────────────┤
│ Pricing      │  Per-use   │  Per-use     │ Per-use  │  License     │
│ model        │            │              │          │  based       │
├──────────────┼────────────┼──────────────┼──────────┼──────────────┤
│ Omnichannel  │     ✅     │      ✅      │    ⚠️    │     ✅       │
│ built-in     │            │              │          │              │
├──────────────┼────────────┼──────────────┼──────────┼──────────────┤
│ NCCO / Flow  │  JSON/API  │  Studio GUI  │ Contact  │  Designer    │
│ builder      │            │  + API       │  Flows   │  GUI         │
├──────────────┼────────────┼──────────────┼──────────┼──────────────┤
│ Global       │     ✅     │      ✅      │    ✅    │     ✅       │
│ coverage     │            │              │          │              │
└──────────────┴────────────┴──────────────┴──────────┴──────────────┘

⚠️ = Partial support or requires additional configuration

Vonage shines for developers who want full control via APIs without being locked into a GUI-only workflow. You can mix GUI tooling (like Vonage's dashboard) with programmatic control — which is exactly what we'll do in this series.

🧱 What We'll Build in This Series

Here's the high-level architecture of the complete cloud call centre we'll construct over 30 days:

┌─────────────────────────────────────────────────────────────────┐
│           COMPLETE CLOUD CALL CENTRE — FINAL ARCHITECTURE       │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                   CUSTOMER CHANNELS                      │  │
│  │  📞 Voice   💬 Web Chat   📱 WhatsApp   📧 Email   💻 SMS │  │
│  └───────────────────────┬──────────────────────────────────┘  │
│                          │                                      │
│  ┌───────────────────────▼──────────────────────────────────┐  │
│  │                  VONAGE API LAYER                        │  │
│  │   Voice API · Messages API · Conversation API · SDK      │  │
│  └───────────────────────┬──────────────────────────────────┘  │
│                          │                                      │
│  ┌───────────────────────▼──────────────────────────────────┐  │
│  │                YOUR APPLICATION BACKEND                  │  │
│  │   Node.js / Python · Webhooks · Business Logic           │  │
│  └────┬────────────────┬────────────────┬───────────────────┘  │
│       │                │                │                       │
│  ┌────▼────┐      ┌────▼────┐      ┌───▼──────┐               │
│  │  AI &   │      │ Routing │      │Analytics │               │
│  │  IVR    │      │ Engine  │      │& Reports │               │
│  │ Layer   │      │         │      │          │               │
│  └────┬────┘      └────┬────┘      └───┬──────┘               │
│       │                │               │                        │
│  ┌────▼────────────────▼───────────────▼──────────────────┐   │
│  │                  AGENT DESKTOP                         │   │
│  │   Custom UI · CRM Integration · Real-time Insights     │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │               SECURITY & COMPLIANCE LAYER               │  │
│  │   Webhook Auth · GDPR · PCI-DSS · RBAC · Audit Logs     │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Each block above is a post (or group of posts) in this series.

🗺️ Your 30-Day Roadmap

Here's how the series is structured:

WEEK 1 — Foundations & Architecture
  Day 1  → What is a Cloud Call Centre? (YOU ARE HERE)
  Day 2  → Architecture deep dive
  Day 3  → Setup: Vonage account, CLI, first app
  Day 4  → Vonage Client SDK: your first voice app
  Day 5  → Call routing & business rules

WEEK 2 — Omnichannel
  Day 6  → Voice: PSTN to WebRTC
  Day 7  → SMS channel
  Day 8  → Web chat
  Day 9  → WhatsApp
  Day 10 → Email routing

WEEK 3 — AI & IVR
  Day 11 → IVR with NCCO
  Day 12 → Natural language IVR with Dialogflow
  Day 13 → Bot-to-human handoff
  Day 14 → Real-time transcription
  Day 15 → Sentiment analysis

WEEK 4 — Developer APIs & Integrations
  Day 16 → Conversation API deep dive
  Day 17 → Webhooks & event-driven architecture
  Day 18 → Salesforce CRM integration
  Day 19 → Custom agent desktop
  Day 20 → Click-to-call

WEEK 5 — Analytics & Reporting
  Day 21 → CDRs & Reporting API
  Day 22 → Real-time dashboard
  Day 23 → Call quality monitoring
  Day 24 → Automated CSAT surveys

WEEK 6 — Security & Compliance
  Day 25 → Webhook security & signature validation
  Day 26 → GDPR & call recording compliance
  Day 27 → PCI-DSS architecture
  Day 28 → Role-based access control

WEEK 7 — Production & DevOps
  Day 29 → CI/CD for Vonage apps
  Day 30 → Production-ready checklist

⚡ Prerequisites for This Series

Before Day 3 (where we set up the environment), make sure you have or can get:

Requirement	Why you need it	Free tier?
Vonage API account	All API calls require credentials	✅ Yes
Node.js 18+ or Python 3.10+	Backend webhook server	✅ Free
ngrok	Expose local server for Vonage webhooks	✅ Free tier
A phone number	Test inbound calls	✅ Trial number
Basic REST API knowledge	Webhooks, HTTP, JSON	—

💡 You do NOT need telephony experience. Everything you need to know about how phone calls work over the internet, we'll cover as we go.

🔑 Key Concepts to Remember

Before we move to Day 2, lock these terms into your mental model:

PSTN — Public Switched Telephone Network. The traditional phone system. Vonage bridges this to your cloud app.

WebRTC — Web Real-Time Communication. Allows voice and video directly in a browser. This is how browser-based agent desktops work — no phone hardware needed.

Webhook — An HTTP callback. Vonage calls your server's URL when something happens (a call arrives, a message is received, a recording is ready). Your server responds with instructions.

NCCO — Nexmo Call Control Object. A JSON array of instructions you return to Vonage to control call flow. Think of it as a script for the call.

CDR — Call Detail Record. The metadata log of every call: who called, when, how long, which agent handled it. Essential for analytics.

Omnichannel — Handling multiple communication channels (voice, chat, SMS, email) in a unified way, with shared context and routing.

🚀 What's Next

In Day 2, we'll do a full architecture deep dive — looking at how Vonage's components connect, what happens inside the Conversation API, and how to design a routing engine that scales.

By the end of Day 2 you'll be able to sketch out the architecture of any cloud call centre scenario from scratch.

💬 Discussion

A few questions to get the conversation going:

Are you coming from a traditional telephony background or purely software?
What's your target stack — Node.js, Python, something else?
Are you building for a startup, enterprise, or just learning?

Drop a comment — I read every one and it helps shape where we go deeper in the series.

📌 Save this post — it's your reference point for the entire series.

🔔 Follow to get notified when Day 2 drops tomorrow.

Series: Building Cloud Call Centres with Vonage APIs
Day 1 of 30 · Next → Day 2: Architecture Deep Dive

I Replaced My Entire Note-Taking System With 30 Lines of Python - Here's What Happened

Shashi Kiran — Tue, 10 Mar 2026 05:37:14 +0000

I'm a developer. I take notes constantly — ideas, bugs, snippets.

I tried Notion. Too bloated.
I tried Obsidian. Too much setup.
I tried Apple Notes. Lost everything twice.

So I did what any developer would do when a tool doesn't exist:

I built it on a Saturday afternoon with 30 lines of Python.

The Problem (That You Probably Have Too)

Every note app either:

Does too much (and you spend more time organizing than thinking)
Does too little (and you lose things anyway)

What I actually wanted was dead simple:

"Hey, save this thought. Hey, find that thing I wrote about Docker last week."

That's it. No folders. No tags. No kanban boards for my grocery list.

The Solution: A CLI Note Tool + AI Search

Here's the entire thing:

import sys
import json
import datetime
from pathlib import Path
from openai import OpenAI

NOTES_FILE = Path.home() / ".notes.json"
client = OpenAI()

def load_notes():
    if not NOTES_FILE.exists():
        return []
    return json.loads(NOTES_FILE.read_text())

def save_note(text):
    notes = load_notes()
    notes.append({"text": text, "date": str(datetime.date.today())})
    NOTES_FILE.write_text(json.dumps(notes, indent=2))
    print("✅ Note saved!")

def search_notes(query):
    notes = load_notes()
    if not notes:
        print("No notes yet.")
        return

    context = "\n".join([f"[{n['date']}] {n['text']}" for n in notes])
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "You are a helpful note search assistant. Given a list of notes, find and summarize the most relevant ones for the user's query."},
            {"role": "user", "content": f"Notes:\n{context}\n\nQuery: {query}"}
        ]
    )
    print(response.choices[0].message.content)

if __name__ == "__main__":
    if sys.argv[1] == "add":
        save_note(" ".join(sys.argv[2:]))
    elif sys.argv[1] == "search":
        search_notes(" ".join(sys.argv[2:]))

Usage:

python notes.py add "Use --no-cache flag when Docker build acts weird."
python notes.py search "docker build issue."

Output:

📝 Found a relevant note from 2026-02-14:
You noted that using --no-cache fixes weird Docker build behavior.

Why This Is Better Than Every Note App I've Tried

Feature	Notion	Obsidian	This script
Setup time	2 hours	45 mins	2 mins
Search quality	Keyword only	Keyword only	Semantic AI
Sync	Cloud	Manual	Just a JSON file
Cost	$10/mo	Free + plugins	~$0.001/search
Distracts me	Constantly	Sometimes	Never

What I'd Add Next

[ ] A list command to dump all notes
[ ] Auto-tagging with AI
[ ] A tiny web UI (maybe with Streamlit)
[ ] Voice input via Whisper API

The Real Lesson Here

The best tool isn't always the most powerful one.

Sometimes it's the one you built yourself that does exactly what you need, nothing more.

30 lines. One weekend. Zero regrets.

If you build on top of this, drop your version in the comments — I'd love to see what you add. 🚀

Build an AI Agent from Scratch — No Frameworks, Just Python

Shashi Kiran — Mon, 09 Mar 2026 16:33:32 +0000

Learn how LLM-powered agents actually work by building one yourself in under 100 lines of Python.

Introduction

Everyone's talking about AI agents. LangChain, AutoGen, CrewAI — the ecosystem is exploding. But if you've ever tried to debug one of these frameworks, you know the feeling: layers upon layers of abstraction, and you have no idea what's actually happening under the hood.

So let's skip the frameworks entirely.

In this tutorial, we'll build a fully functional AI agent from scratch using nothing but Python and the OpenAI API. By the end, you'll understand exactly how agents work — and you'll never feel lost in a framework again.

What Even Is an AI Agent?

A regular LLM call is stateless: you send a prompt, you get a response, done.

An agent is different. It can:

Think about what steps to take
Use tools (like searching the web, running code, reading files)
Loop — observe results and decide what to do next

The core loop looks like this:

Think → Act → Observe → Repeat

This is often called the ReAct pattern (Reasoning + Acting), and it's the foundation of almost every agent framework out there.

What We're Building

A simple agent that can answer questions using two tools:

calculator — evaluates math expressions
get_weather — returns (fake) weather data for a city

The agent will figure out which tool to call, call it, observe the result, and keep going until it has a final answer.

Prerequisites

Python 3.9+
An OpenAI API key (or swap in any LLM with tool/function calling)
Basic Python knowledge

Install the dependency:

pip install openai

Step 1: Define Your Tools

Tools are just Python functions. We'll describe them to the LLM using JSON schema so it knows how to call them.

import json
import math

# --- Tool implementations ---

def calculator(expression: str) -> str:
    """Safely evaluate a math expression."""
    try:
        result = eval(expression, {"__builtins__": {}}, {"sqrt": math.sqrt, "pow": pow})
        return str(result)
    except Exception as e:
        return f"Error: {e}"

def get_weather(city: str) -> str:
    """Return fake weather data for demo purposes."""
    fake_data = {
        "london": "Cloudy, 15°C",
        "new york": "Sunny, 22°C",
        "tokyo": "Rainy, 18°C",
    }
    return fake_data.get(city.lower(), "Weather data not available for this city.")

# --- Tool registry ---

TOOLS = {
    "calculator": calculator,
    "get_weather": get_weather,
}

# --- Tool descriptions for the LLM ---

TOOL_SCHEMAS = [
    {
        "type": "function",
        "function": {
            "name": "calculator",
            "description": "Evaluate a mathematical expression and return the result.",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "A valid Python math expression, e.g. '2 + 2' or 'sqrt(16)'",
                    }
                },
                "required": ["expression"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a given city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "The name of the city, e.g. 'London'",
                    }
                },
                "required": ["city"],
            },
        },
    },
]

Step 2: Build the Agent Loop

Here's the heart of the agent — a loop that keeps running until the LLM produces a final text answer (no more tool calls).

from openai import OpenAI

client = OpenAI()  # uses OPENAI_API_KEY from environment

def run_agent(user_query: str):
    print(f"\n🧠 User: {user_query}\n")

    messages = [
        {
            "role": "system",
            "content": (
                "You are a helpful assistant. Use tools when needed. "
                "Once you have enough information, provide a final answer."
            ),
        },
        {"role": "user", "content": user_query},
    ]

    # Agent loop
    while True:
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            tools=TOOL_SCHEMAS,
            tool_choice="auto",
        )

        message = response.choices[0].message

        # If no tool calls → we have a final answer
        if not message.tool_calls:
            print(f"✅ Agent: {message.content}")
            return message.content

        # Process each tool call
        messages.append(message)  # add assistant message with tool_calls

        for tool_call in message.tool_calls:
            tool_name = tool_call.function.name
            tool_args = json.loads(tool_call.function.arguments)

            print(f"🔧 Calling tool: {tool_name}({tool_args})")

            # Execute the tool
            tool_fn = TOOLS.get(tool_name)
            if tool_fn:
                result = tool_fn(**tool_args)
            else:
                result = f"Error: tool '{tool_name}' not found."

            print(f"📊 Tool result: {result}\n")

            # Feed the result back to the LLM
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": result,
            })

Step 3: Run It!

if __name__ == "__main__":
    run_agent("What is the square root of 144, and what's the weather like in Tokyo?")

Output:

🧠 User: What is the square root of 144, and what's the weather like in Tokyo?

🔧 Calling tool: calculator({'expression': 'sqrt(144)'})
📊 Tool result: 12.0

🔧 Calling tool: get_weather({'city': 'Tokyo'})
📊 Tool result: Rainy, 18°C

✅ Agent: The square root of 144 is **12**. As for Tokyo, it's currently **rainy with a temperature of 18°C**. 🌧️

That's it. A working agent in ~80 lines of Python.

How It Works — The Full Picture

Let's trace what happened:

User asks a question with two parts
LLM decides it needs two tools and returns tool_calls instead of a text answer
We execute each tool and append the results to the message history
LLM sees the results and synthesizes a final answer
Loop ends because there are no more tool calls

The key insight: the LLM never actually runs the tools. It just says "call this function with these arguments." Your code does the actual execution and feeds the result back. The LLM is the brain; your code is the hands.

Taking It Further

Now that you understand the core pattern, here's how to extend it:

Idea	How
Add more tools	Write a function + add its schema to `TOOL_SCHEMAS`
Web search	Use the Serper or Tavily API as a tool
Memory	Persist `messages` to a database between sessions
Multi-agent	One agent's output becomes another agent's tool
Streaming	Use `stream=True` to print tokens as they arrive

Why Build from Scratch First?

Frameworks like LangChain are powerful, but they hide the loop. When something breaks — and it will — you need to know what's actually happening.

Building from scratch gives you:

Full control over every message sent to the LLM
Easy debugging — no magic, no hidden prompts
Framework fluency — you'll understand LangChain/AutoGen much faster now

Conclusion

Agents aren't magic. They're just LLMs in a loop with access to tools. The ReAct pattern — Think, Act, Observe, Repeat — is simple once you see it in code.

You now have a working agent and, more importantly, a mental model of how every major agent framework operates under the hood.

What will you build with it? Drop your ideas in the comments 👇

🤖 Stop. Breathe. You Don't Need Every AI Tool.

Shashi Kiran — Thu, 05 Mar 2026 06:35:11 +0000

A brutally honest guide to navigating the AI chaos in 2026 — and actually getting work done.

There's a new AI tool every Tuesday.

Monday it's a new coding assistant. Wednesday it's a "revolutionary" writing model. By Friday, your Twitter feed is screaming that the old AI you just installed is already dead.

And somewhere in the middle of all this noise, you've got twelve browser tabs open, three free trials running, and you still haven't finished the feature you started last week.

Sound familiar?

You're not behind. You're just overwhelmed. And you're not alone.

The AI Tool Explosion (A Brief, Terrifying Timeline)

A year ago, there were maybe five AI tools worth knowing. Now there are hundreds. And they all promise the same thing: to make you 10x more productive.

Here's what nobody tells you: evaluating all of them is itself destroying your productivity.

Every tool you try costs you:

Time to sign up and onboard
Mental RAM to learn a new interface
Context switching that kills deep work
Decision fatigue that bleeds into actual decisions

The real productivity loss isn't picking the "wrong" tool. It's not picking at all and bouncing between everything.

The Real Categories (Cut Through the Noise)

Here's a no-nonsense map of what actually exists:

🧠 General-Purpose AI Assistants

What they do: Writing, reasoning, coding, research, Q&A — the Swiss Army knife.

The main players:

Claude (Anthropic) — Exceptional at nuanced reasoning, long documents, coding, and anything that requires thinking carefully. The one you want when accuracy and depth matter.
ChatGPT (OpenAI) — Widest plugin ecosystem, most tutorials, massive community. Great starting point.
Gemini (Google) — Tight Google Workspace integration. Best if you live in Google Docs/Sheets.

Pick one. Seriously. The differences at a day-to-day level are smaller than the internet wants you to believe.

💻 Coding Assistants

What they do: Autocomplete, explain, refactor, generate tests.

The main players:

GitHub Copilot — Deeply embedded in VS Code, JetBrains, etc. The safe enterprise choice.
Cursor — Full AI-native IDE. Feels like pair programming with a senior dev.
Claude / ChatGPT — For longer reasoning tasks: architecture decisions, debugging weird errors, understanding unfamiliar codebases.

Practical rule: Copilot/Cursor for flow-state coding. Claude/ChatGPT for "I have no idea what's happening here."

🎨 Image & Visual Generation

What they do: Generate images, illustrations, mockups from text.

The main players:

Midjourney — Best pure aesthetics. Artsy, cinematic, stunning.
DALL·E (via ChatGPT) — Convenient if you're already in ChatGPT. Good for quick visuals.
Stable Diffusion — Open source, local runs, infinite customization. Steep learning curve.
Ideogram / Flux — Worth watching for accurate text-in-images.

Practical rule: Midjourney for quality. DALL·E for convenience. Stable Diffusion if you need control and privacy.

🎙️ Voice & Audio

ElevenLabs — Realistic voice cloning and TTS. Industry standard.
Whisper (OpenAI) — Best-in-class transcription. Open source.
Suno / Udio — Generate full songs from text prompts. Surprisingly good.

📹 Video Generation

This space is evolving fast.

Sora (OpenAI) — High quality, limited access.
Runway — Creative, flexible, used by real filmmakers.
Kling / Hailuo — Strong Chinese alternatives gaining ground.

Honest advice: Wait 6 months before betting your workflow on any video tool. This category is still maturing.

🔍 AI Search & Research

Perplexity — The best AI-powered search. Cites sources. Kills the "let me Google that" habit.
NotebookLM (Google) — Feed it documents, ask questions about them. Incredible for research.
Claude Projects / ChatGPT Memory — For persistent, personalized workflows.

The Framework: How to Actually Choose

Stop asking "which is the best AI?" Start asking:

"What is the one thing I do most that takes too long — and which tool specifically solves that?"

Then:

Pick ONE tool for that job. Not three. One.
Use it for 30 days. Not 3.
Measure actual output. Did you ship faster? Write better? Learn more?
Then — and only then — consider adding a second tool.

The people getting real value from AI aren't the ones with the most tools. They're the ones who've gone deep on one or two.

A Realistic Stack for Most Developers

You don't need all of them. Here's a clean, opinionated stack:

Job	Tool
Daily assistant / thinking partner	Claude
In-editor coding	Cursor or Copilot
Quick search / research	Perplexity
Image generation (when needed)	Midjourney
Transcription	Whisper

That's it. Five tools. Each with a clear, non-overlapping job. No decision fatigue.

The Uncomfortable Truth

The AI companies want you overwhelmed. FOMO drives signups. Benchmark wars drive headlines. The discourse benefits everyone — except you, the person trying to get work done.

The best developer I know uses Claude and Cursor. Period. He's not missing out. He's shipping.

The worst trap in tech is spending all your time optimizing your tools instead of building with them.

Pick your stack. Go deep. Ship things.

The AI gold rush will keep going. Your deadline won't wait.

TL;DR

There are too many AI tools and that's intentional.
Most of them overlap massively.
Your real enemy is tool-switching, not tool-selection.
Pick one general assistant (Claude, ChatGPT, or Gemini). Actually use it.
Add a coding tool. Use it daily.
Ignore the rest until you've maxed out what you have.
The best AI workflow is the one you actually stick to.

What's your current stack? Drop it in the comments — especially if you've found something worth adding.

ContentCrew: A 7-Agent AI Pipeline That Researches, Writes, and Fact-Checks Articles Using Google ADK

Shashi Kiran — Mon, 02 Mar 2026 17:11:42 +0000

This post is my submission for DEV Education Track: Build Multi-Agent Systems with ADK.

What I Built

Content creation is time-consuming. Researching a topic, drafting an article, editing it, fact-checking claims, formatting for SEO, and then repurposing it for social media can take hours. I built ContentCrew — a multi-agent pipeline that automates this entire workflow end to end.

You give it a topic. Within 3–5 minutes it produces:

A fully researched, written, and edited blog post
A SEO-optimized article with YAML front-matter
A fact-check report verifying key claims with sources
A Twitter/X thread + LinkedIn post ready to publish
The article translated into any language you choose

The system is built entirely on Google ADK (Agent Development Kit) with Gemini 2.0 Flash, deployed with a Streamlit web UI on Google Cloud Shell.

Cloud Run Embed

Try ContentCrew live — no setup required:

gcloud builds submit --tag gcr.io/call-centre-513111/contentcrew
gcloud run deploy contentcrew \
--image gcr.io/call-centre-513111/contentcrew \
--platform managed \
--region asia-south1 \
--allow-unauthenticated \
--set-env-vars GOOGLE_CLOUD_PROJECT=call-centre-513111,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=true

Enter any topic and watch all 7 agents work in real time — researching, writing, editing, fact-checking, and generating social media posts.

Your Agents

ContentCrew uses 7 specialized agents, each with a single well-defined responsibility. They run in two stages — a main orchestrated pipeline and a set of standalone agents that run after.

Stage 1 — Orchestrated Pipeline

🔍 ResearchAgent
Receives the topic and performs 2–3 web searches using a custom web_search tool built on the DuckDuckGo API. Produces a structured research brief with key facts, trends, and source URLs. This feeds directly into the WriterAgent.

✍️ WriterAgent
Takes the research brief and drafts an 800–1200 word blog post. Structured with a hook introduction, 3–4 main sections with subheadings, and a conclusion with a call to action. Uses a word_count tool to verify length.

🧹 EditorAgent
Reviews the draft for clarity, flow, grammar, and consistency. Removes filler words, strengthens the hook and conclusion, and ensures consistent tone throughout.

📦 FormatterAgent
Adds YAML front-matter (title, description, keyword, tags, reading time), ensures correct Markdown heading hierarchy, and saves the final article to output/final_article.md.

🎯 ContentOrchestrator
Coordinates the four agents above in sequence, passing each agent's output to the next. Built with ADK's sub_agents pattern.

Stage 2 — Standalone Agents

✅ FactCheckAgent
Runs independently with the finished article as input. Identifies up to 6 factual claims, searches each one using web_search, and produces a structured fact-check report with verdicts: ✅ VERIFIED, ⚠️ UNVERIFIED, or ❌ DISPUTED. Saved separately to output/factcheck_report.md.

🐦 SocialMediaAgent
Takes the finished article and generates a 7-tweet Twitter/X thread and a LinkedIn post. Each tweet covers one key insight. The LinkedIn post ends with a question to drive engagement.

🌍 TranslateAgent
Translates the complete article into any target language (Hindi, Spanish, Telugu, French, German, Arabic, Japanese, Chinese) while preserving all Markdown formatting, YAML front-matter, and heading structure.

How They Work Together

User Input (Topic)
       │
       ▼
ContentOrchestrator
  ├── ResearchAgent   → Research Brief
  ├── WriterAgent     → Draft Article
  ├── EditorAgent     → Polished Article
  └── FormatterAgent  → final_article.md
       │
       ├── FactCheckAgent   → factcheck_report.md
       ├── SocialMediaAgent → social_media.md
       └── TranslateAgent   → translated_<lang>.md

The key architectural decision was to separate FactCheckAgent from the orchestrator. When it was a sub-agent inside the orchestrator, its output was absorbed into the orchestrator's context and never surfaced as a separate event. Running it as a standalone Runner with its own session solved this completely.

Key Learnings

Vertex AI does not allow mixing tool types in a single agent.
The biggest early blocker was discovering that Vertex AI throws a 400 INVALID_ARGUMENT: Multiple tools are supported only when they are all search tools error when you mix google_search (a built-in ADK tool) with custom Python callables in the same agent. The fix was to replace the built-in google_search with a custom web_search function built on DuckDuckGo's free API — making all tools plain Python callables.

Sub-agent outputs are absorbed by the orchestrator.
I expected each sub-agent's output to surface as separate events I could intercept. In practice, the orchestrator wraps all sub-agent activity — their outputs never appear with the sub-agent as event.author. The solution was to move agents that needed their output captured separately (FactCheck, Social Media, Translate) out of the orchestrator entirely and run them as independent Runner instances.

Cloud Shell requires specific Streamlit config to work.
Streamlit's WebSocket connections fail silently in Cloud Shell without the right settings. The fix was a .streamlit/config.toml with enableCORS = false, enableXsrfProtection = false, enableWebsocketCompression = false, and port = 8080. Without this, the UI renders as a blank page.

ADK emits function_call warning noise that can't be easily suppressed.
The warning non-text parts in the response: ['function_call'] appears whenever an agent makes a tool call. It's cosmetic and doesn't affect functionality, but it clutters output. The clean fix was to patch logging.Logger.warning at startup to filter the specific message.

LLMs ignore URL format instructions reliably.
The ImageAgent was instructed to use a specific image URL format but consistently generated Unsplash URLs from training memory instead. The lesson: never rely on an LLM to generate specific URL formats. Either generate the URLs in code based on keywords the LLM provides, or use a different approach entirely.