@cemscale-voip/voip-sdk 1.40.0 → 1.41.0

package/README.md

@@ -905,6 +905,346 @@ await voip.updateDid('did-uuid-here', {
 | `reason` | string | Yes | Why: "conversation_complete", "caller_goodbye", "no_response", "voicemail_detected" |
 | `summary` | string | No | Brief summary of the call |
 
+
+
+---
+
+#### CRM Webhook Setup — Receiving AI Tool Calls
+
+When an AI agent invokes a tool during a live call (e.g. `send_sms`, `create_lead`), the VoIP platform sends a POST request to your CRM. Your CRM **must** have a webhook endpoint that receives these tool calls, processes them, and returns a response that Gemini speaks to the caller.
+
+**Architecture:**
+```
+Caller speaks -> Gemini AI -> invokes tool (e.g. send_sms)
+  -> VoIP Platform (Go) -> POST to VoIP API
+  -> VoIP API forwards -> POST to YOUR CRM webhook
+  -> Your CRM processes (sends SMS, creates lead, etc.)
+  -> Your CRM responds with JSON
+  -> Gemini reads response to caller
+```
+
+**CRITICAL: Your webhook endpoint must NOT have global auth middleware.**
+
+The VoIP platform authenticates via `Authorization: Bearer <api_key>` where `api_key` is a VoIP SDK API key (`csk_live_...`). Your webhook handler must validate this token itself — do NOT put it behind your CRM's global auth middleware (e.g. session auth, JWT, capability checks). If your CRM's router wraps routes with automatic auth, register this endpoint WITHOUT that wrapper.
+
+**Environment variable your CRM needs:**
+
+```env
+# The VoIP SDK API key used to authenticate tool call webhooks.
+# This key is created in the VoIP platform and shared with your CRM.
+# The VoIP platform sends it as: Authorization: Bearer <this_key>
+VOIP_TOOLS_WEBHOOK_KEY=csk_live_da3d1ee6d3b51696922206dc139beab84239a7935049b5a5
+```
+
+**Complete webhook handler your CRM needs (Express/Fastify/etc.):**
+
+```typescript
+import crypto from 'crypto';
+
+// ──────────────────────────────────────────────────────────
+// IMPORTANT: Register this route WITHOUT global auth middleware.
+// This endpoint has its own auth via validateToolsWebhookAuth().
+// If your router uses a `wrap()` or `requireAuth()` middleware,
+// do NOT apply it to this route.
+// ──────────────────────────────────────────────────────────
+
+/**
+ * Validate that the request comes from the VoIP platform.
+ * Checks Authorization: Bearer <api_key> against VOIP_TOOLS_WEBHOOK_KEY env var.
+ */
+function validateToolsWebhookAuth(req: { headers: Record<string, any> }): boolean {
+  const expectedKey = process.env.VOIP_TOOLS_WEBHOOK_KEY;
+  if (!expectedKey) return false;
+
+  // Method 1: Authorization Bearer token
+  const authHeader = req.headers.authorization || req.headers.Authorization;
+  if (authHeader) {
+    const token = typeof authHeader === 'string' && authHeader.startsWith('Bearer ')
+      ? authHeader.slice(7)
+      : authHeader;
+    if (typeof token === 'string' && token.length === expectedKey.length) {
+      try {
+        return crypto.timingSafeEqual(Buffer.from(token), Buffer.from(expectedKey));
+      } catch { return false; }
+    }
+  }
+
+  // Method 2: X-API-Key header
+  const apiKeyHeader = req.headers['x-api-key'];
+  if (typeof apiKeyHeader === 'string' && apiKeyHeader.length === expectedKey.length) {
+    try {
+      return crypto.timingSafeEqual(Buffer.from(apiKeyHeader), Buffer.from(expectedKey));
+    } catch { return false; }
+  }
+
+  return false;
+}
+
+// Register WITHOUT global auth middleware:
+// WRONG: router.post('/api/webhooks/ai-tools', requireAuth, handler)
+// RIGHT: router.post('/api/webhooks/ai-tools', handler)
+// If using a `wrap()` function that enforces auth, do NOT use it here.
+
+app.post('/api/webhooks/ai-tools', async (req, res) => {
+  // 1. Validate auth
+  if (!validateToolsWebhookAuth(req)) {
+    return res.status(401).json({ status: 'error', message: 'Unauthorized' });
+  }
+
+  // 2. Parse the tool call
+  const { function: toolName, args, call_id, tenant_id } = req.body;
+
+  if (!toolName || !args) {
+    return res.status(400).json({ status: 'error', message: 'Missing function or args' });
+  }
+
+  console.log(`[AI Tool] ${toolName} called during call ${call_id} (tenant: ${tenant_id})`);
+
+  try {
+    switch (toolName) {
+
+      // ─── SEND SMS ──────────────────────────────────────────────
+      // Gemini collected: to_phone (required), message (required),
+      //   purpose (optional), caller_name (optional)
+      //
+      // When to use: The caller asks "can you send me that by text?"
+      // or the AI decides to send a confirmation after booking, etc.
+      case 'send_sms': {
+        const toPhone = args.to_phone;
+        const messageText = args.message;
+
+        if (!toPhone || !messageText) {
+          return res.json({
+            status: 'error',
+            message: 'I need the phone number and message to send. Could you provide those?',
+          });
+        }
+
+        // ── Send the SMS using YOUR SMS provider ──
+        // Replace this with your actual SMS sending code.
+        // Examples: Twilio, Telnyx, Vonage, AWS SNS, etc.
+        //
+        // Twilio example:
+        //   const twilio = require('twilio')(TWILIO_SID, TWILIO_AUTH);
+        //   const sms = await twilio.messages.create({
+        //     to: toPhone,
+        //     from: YOUR_TWILIO_NUMBER,
+        //     body: messageText,
+        //   });
+        //
+        // Telnyx example:
+        //   const telnyx = require('telnyx')(TELNYX_API_KEY);
+        //   const sms = await telnyx.messages.create({
+        //     to: toPhone,
+        //     from: YOUR_TELNYX_NUMBER,
+        //     text: messageText,
+        //   });
+
+        // YOUR SMS SENDING CODE HERE:
+        const smsResult = await sendSms({
+          to: toPhone,
+          message: messageText,
+        });
+
+        // Log the SMS in your database
+        // await db.smsLogs.create({ toPhone, message: messageText,
+        //   purpose: args.purpose, callerName: args.caller_name,
+        //   callId: call_id, tenantId: tenant_id, status: smsResult.success ? 'sent' : 'failed' });
+
+        if (!smsResult.success) {
+          return res.json({
+            status: 'failed',
+            message: 'I was unable to send the text message right now. ' +
+                     'Let me take note and we will send it to you shortly.',
+          });
+        }
+
+        return res.json({
+          status: 'sent',
+          message: 'The text message has been sent to ' + toPhone + '. ' +
+                   'You should receive it in a moment.',
+        });
+      }
+
+      // ─── CREATE LEAD ──────────────────────────────────────────
+      case 'create_lead': {
+        // args: first_name (required), last_name, phone (required),
+        //   email, company, interest, notes, source
+        const lead = await createLeadInCrm({
+          firstName: args.first_name,
+          lastName: args.last_name,
+          phone: args.phone,
+          email: args.email,
+          company: args.company,
+          interest: args.interest,
+          notes: args.notes,
+          callId: call_id,
+          tenantId: tenant_id,
+        });
+
+        return res.json({
+          status: 'created',
+          lead_id: lead.id,
+          message: `I've created a record for ${args.first_name}. A team member will follow up shortly.`,
+        });
+      }
+
+      // ─── LEAVE MESSAGE ────────────────────────────────────────
+      case 'leave_message': {
+        // args: caller_name (required), caller_phone (required),
+        //   message (required), for_person, urgent, callback_preferred_time
+        const msg = await saveMessageInCrm({
+          callerName: args.caller_name,
+          callerPhone: args.caller_phone,
+          message: args.message,
+          forPerson: args.for_person,
+          urgent: args.urgent,
+          callbackTime: args.callback_preferred_time,
+          callId: call_id,
+          tenantId: tenant_id,
+        });
+
+        return res.json({
+          status: 'saved',
+          message: args.urgent
+            ? `I've flagged this as urgent. The team will get back to ${args.caller_name} right away.`
+            : `Message recorded. Someone from the team will call ${args.caller_name} back soon.`,
+        });
+      }
+
+      // ─── SCHEDULE APPOINTMENT ─────────────────────────────────
+      case 'schedule_appointment': {
+        // args: caller_name (required), phone (required), date (required),
+        //   time, duration, purpose (required), notes
+        const appt = await scheduleAppointmentInCrm({
+          callerName: args.caller_name,
+          phone: args.phone,
+          date: args.date,
+          time: args.time,
+          duration: args.duration,
+          purpose: args.purpose,
+          notes: args.notes,
+          callId: call_id,
+          tenantId: tenant_id,
+        });
+
+        return res.json({
+          status: 'scheduled',
+          message: `Appointment confirmed for ${args.date}${args.time ? ' at ' + args.time : ''}. ` +
+                   `${args.caller_name} will receive a confirmation shortly.`,
+        });
+      }
+
+      // ─── CHECK POLICY STATUS ──────────────────────────────────
+      case 'check_policy_status': {
+        // args: policy_number (required), phone, last_name, date_of_birth, lookup_type
+        const policy = await lookupPolicyInCrm({ policyNumber: args.policy_number });
+
+        if (!policy) {
+          return res.json({
+            status: 'not_found',
+            message: `I couldn't find a policy with number ${args.policy_number}. Could you double-check that number?`,
+          });
+        }
+
+        return res.json({
+          status: 'found',
+          message: `Policy ${args.policy_number} is currently ${policy.status}.`,
+        });
+      }
+
+      // ─── UNKNOWN TOOL ─────────────────────────────────────────
+      default: {
+        console.warn(`[AI Tool] Unknown tool: ${toolName}`);
+        return res.json({
+          status: 'noted',
+          message: "I've noted your request. A team member will follow up.",
+        });
+      }
+    }
+  } catch (error: any) {
+    console.error(`[AI Tool] Error handling ${toolName}:`, error);
+    return res.status(500).json({
+      status: 'error',
+      message: "I'm having trouble processing that right now. Let me take a note and have someone follow up.",
+    });
+  }
+});
+```
+
+**Webhook request format (what your CRM receives):**
+
+Every tool call arrives as a POST with this JSON body:
+
+```json
+{
+  "function": "send_sms",
+  "args": {
+    "to_phone": "+17865550198",
+    "message": "Your appointment is confirmed for Friday at 2:00 PM. Address: 123 Main St.",
+    "purpose": "appointment_confirmation",
+    "caller_name": "Ana Martinez"
+  },
+  "call_id": "ff6a1693-b2f8-123f-b8b1-0a7dee2809a7",
+  "tenant_id": "6a097cb2-504f-43be-819a-b76209976818"
+}
+```
+
+**Headers your CRM receives:**
+
+| Header | Value | Description |
+|--------|-------|-------------|
+| `Content-Type` | `application/json` | Always JSON |
+| `Authorization` | `Bearer csk_live_...` | VoIP SDK API key for auth |
+| `X-Webhook-Source` | `voiceai-platform` | Identifies the source |
+
+**Webhook response format (what your CRM must return):**
+
+Your response MUST be JSON. The `message` field is what Gemini speaks to the caller:
+
+```json
+{
+  "status": "sent",
+  "message": "The text message has been sent to your phone. You should receive it in a moment."
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `status` | string | Yes | Result: `"sent"`, `"created"`, `"saved"`, `"scheduled"`, `"found"`, `"not_found"`, `"error"`, `"failed"` |
+| `message` | string | Yes | **CRITICAL: This is what the AI says to the caller.** Write naturally, 1-2 sentences max. |
+
+**Response rules:**
+- The `message` field is spoken by the AI to the caller. Write it as natural speech.
+- Keep `message` to 1-2 sentences maximum.
+- If something fails, STILL return a `message` with a graceful fallback.
+- Your webhook has a **9 second timeout**. If it doesn't respond, Gemini hears: `"I'm having trouble processing that right now."`
+- HTTP status should be `200` for success, `500` for errors. The AI always gets the `message` field either way.
+
+**Testing your webhook with curl:**
+
+```bash
+# Test send_sms tool call
+curl -X POST https://your-crm.com/api/webhooks/ai-tools \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_VOIP_TOOLS_WEBHOOK_KEY" \
+  -d '{
+    "function": "send_sms",
+    "args": {
+      "to_phone": "+17865551234",
+      "message": "Your appointment is confirmed for Friday at 2pm.",
+      "purpose": "appointment_confirmation",
+      "caller_name": "Juan Garcia"
+    },
+    "call_id": "test-123",
+    "tenant_id": "your-tenant-id"
+  }'
+
+# Expected response:
+# {"status":"sent","message":"The text message has been sent to +17865551234."}
+```
+
+
 ### CDR Export
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cemscale-voip/voip-sdk",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "VoIP SDK for CemScale multi-tenant platform — API client, WebRTC, React hooks",
   "type": "module",
   "main": "dist/index.js",