claude-phone-local 2.0.0

package/voice-app/README-OUTBOUND.md

@@ -0,0 +1,316 @@
+# Outbound Calling API
+
+> **Using this from Claude Code?** Prefer the MCP server -- it wraps these
+> endpoints as native tools (`call_me`, `call_status`, `hangup`) so Claude can
+> phone you without you writing any HTTP calls. See
+> [../docs/MCP-SERVER.md](../docs/MCP-SERVER.md). This document is the raw HTTP
+> API underneath, still fully supported.
+
+API reference for initiating outbound calls from Claude Phone.
+
+## Overview
+
+The outbound calling API allows your server to call phone numbers and deliver messages. Use cases:
+
+- Server alerts ("Your disk is 95% full")
+- Automated notifications
+- Two-way conversations triggered by events
+
+## Endpoints
+
+### POST /api/outbound-call
+
+Initiate an outbound call.
+
+**Request:**
+
+```json
+{
+  "to": "+15551234567",
+  "message": "Hello from your server",
+  "mode": "announce",
+  "device": "Morpheus",
+  "callerId": "+15559876543",
+  "timeoutSeconds": 30,
+  "webhookUrl": "https://example.com/webhook"
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `to` | Yes | Phone number in E.164 format |
+| `message` | Yes | Text to speak (max 1000 chars) |
+| `mode` | No | `announce` (default) or `conversation` |
+| `device` | No | Device name for voice/personality |
+| `callerId` | No | Caller ID to display |
+| `timeoutSeconds` | No | Ring timeout 5-120 (default: 30) |
+| `webhookUrl` | No | URL for status callbacks |
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "callId": "abc123-uuid",
+  "status": "queued",
+  "message": "Call initiated"
+}
+```
+
+### GET /api/call/:callId
+
+Get status of a specific call.
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "callId": "abc123-uuid",
+  "to": "+15551234567",
+  "state": "completed",
+  "mode": "announce",
+  "createdAt": "2025-01-01T12:00:00.000Z",
+  "answeredAt": "2025-01-01T12:00:05.234Z",
+  "endedAt": "2025-01-01T12:00:15.678Z",
+  "duration": 10
+}
+```
+
+### GET /api/calls
+
+List all active calls.
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "count": 2,
+  "calls": [
+    { "callId": "...", "to": "...", "state": "playing" },
+    { "callId": "...", "to": "...", "state": "dialing" }
+  ]
+}
+```
+
+### POST /api/call/:callId/hangup
+
+Manually hang up an active call.
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "message": "Call hangup initiated",
+  "callId": "abc123-uuid"
+}
+```
+
+## Call States
+
+| State | Description |
+|-------|-------------|
+| `queued` | Call created, not yet dialing |
+| `dialing` | SIP INVITE sent, waiting for answer |
+| `playing` | Call answered, playing message |
+| `completed` | Call finished successfully |
+| `failed` | Call failed (busy, no answer, error) |
+
+## Call Modes
+
+### Announce Mode (Default)
+
+Plays the message and hangs up:
+
+```bash
+curl -X POST http://localhost:3000/api/outbound-call \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "+15551234567",
+    "message": "Alert: Your server storage is at 95 percent."
+  }'
+```
+
+### Conversation Mode
+
+Plays the message, then allows back-and-forth conversation:
+
+```bash
+curl -X POST http://localhost:3000/api/outbound-call \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "+15551234567",
+    "message": "Alert: Your server storage is at 95 percent. Would you like me to clean up old logs?",
+    "mode": "conversation",
+    "device": "Morpheus"
+  }'
+```
+
+## Webhooks
+
+If `webhookUrl` is provided, POST requests are sent on state changes:
+
+```json
+{
+  "callId": "abc123-uuid",
+  "state": "completed",
+  "to": "+15551234567",
+  "duration": 15,
+  "timestamp": "2025-01-01T12:00:15.678Z"
+}
+```
+
+## Error Responses
+
+```json
+{
+  "success": false,
+  "error": "Invalid phone number format"
+}
+```
+
+| Error | Cause |
+|-------|-------|
+| `Invalid phone number format` | `to` not in E.164 format |
+| `Message is required` | Missing `message` field |
+| `Message too long` | Message exceeds 1000 chars |
+| `Call not found` | Invalid `callId` |
+| `service_unavailable` | SIP/media server not ready |
+
+## Failure Reasons
+
+When a call fails, the `reason` field indicates why:
+
+| Reason | Description |
+|--------|-------------|
+| `busy` | Recipient busy (SIP 486) |
+| `no_answer` | No answer within timeout (SIP 480/408) |
+| `not_found` | Number not found (SIP 404) |
+| `rejected` | Call rejected (SIP 603) |
+| `service_unavailable` | Server error (SIP 503) |
+
+## Examples
+
+### Basic Alert
+
+```bash
+curl -X POST http://localhost:3000/api/outbound-call \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "+15551234567",
+    "message": "Your backup job completed successfully."
+  }'
+```
+
+### With Webhook
+
+```bash
+curl -X POST http://localhost:3000/api/outbound-call \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": "+15551234567",
+    "message": "Server alert: High CPU usage detected.",
+    "webhookUrl": "https://n8n.example.com/webhook/call-status"
+  }'
+```
+
+### Check Status
+
+```bash
+# Get call status
+curl http://localhost:3000/api/call/abc123-uuid
+
+# List all active calls
+curl http://localhost:3000/api/calls
+```
+
+## Integration Examples
+
+### Home Assistant
+
+```yaml
+rest_command:
+  call_alert:
+    url: "http://VOICE_SERVER:3000/api/outbound-call"
+    method: POST
+    content_type: "application/json"
+    payload: '{"to": "+15551234567", "message": "{{ message }}"}'
+```
+
+### n8n Workflow: Automated Alert System
+
+This example workflow queries a device for status, then calls you if there's a problem.
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────┐     ┌──────────────┐
+│   Trigger    │ ──▶ │ Query Device │ ──▶ │ If Alert │ ──▶ │  Call User   │
+│ (Schedule)   │     │ POST /query  │     │  Needed  │     │ POST /call   │
+└──────────────┘     └──────────────┘     └──────────┘     └──────────────┘
+```
+
+**Node 1: Trigger**
+- Use Schedule Trigger (e.g., every 5 minutes) or Manual Trigger for testing
+
+**Node 2: HTTP Request - Query Device**
+```
+Method: POST
+URL: http://YOUR_SERVER:3000/api/query
+Body (JSON):
+```
+```json
+{
+  "query": "Check the system health. Alert me if anything needs attention.",
+  "device": "Morpheus",
+  "format": "json",
+  "schema": {
+    "queryType": "alert_check",
+    "requiredFields": ["call_user", "reason"],
+    "fieldGuidance": {
+      "call_user": "Boolean - true if something needs attention",
+      "reason": "One sentence explaining the situation, under 30 words"
+    }
+  },
+  "timeout": 120
+}
+```
+
+**Node 3: If - Check Alert Condition**
+```
+Condition: {{ $json.structured.call_user }} equals true
+```
+
+**Node 4: HTTP Request - Make Call (True branch only)**
+```
+Method: POST
+URL: http://YOUR_SERVER:3000/api/outbound-call
+Body (JSON):
+```
+```json
+{
+  "to": "YOUR_EXTENSION",
+  "message": "Hey! {{ $json.structured.reason }}. Want details?",
+  "mode": "conversation",
+  "device": "Morpheus"
+}
+```
+
+**How it works:**
+1. Trigger fires (on schedule or manually)
+2. Queries your device with a structured schema request
+3. Device returns JSON with `call_user: true/false` and `reason`
+4. If `call_user` is true, initiates outbound call in conversation mode
+5. You answer and can ask follow-up questions
+
+### Shell Script
+
+```bash
+#!/bin/bash
+PHONE="+15551234567"
+MESSAGE="Disk space critical on server1"
+
+curl -s -X POST http://localhost:3000/api/outbound-call \
+  -H "Content-Type: application/json" \
+  -d "{\"to\": \"$PHONE\", \"message\": \"$MESSAGE\"}"
+```

package/voice-app/config/devices.json.example

@@ -0,0 +1,18 @@
+{
+  "9000": {
+    "name": "Assistant",
+    "extension": "9000",
+    "authId": "your-3cx-auth-id",
+    "password": "your-3cx-password",
+    "voiceId": "your-elevenlabs-voice-id",
+    "prompt": "You are a helpful AI assistant. Keep voice responses under 40 words."
+  },
+  "9002": {
+    "name": "ServerBot",
+    "extension": "9002",
+    "authId": "another-auth-id",
+    "password": "another-password",
+    "voiceId": "another-voice-id",
+    "prompt": "You are a server monitoring assistant. Report on system health and alerts. Keep voice responses under 40 words."
+  }
+}

package/voice-app/index.js

@@ -0,0 +1,273 @@
+/**
+ * Voice Interface Application
+ * Main entry point - v9 with Multi-Extension + Query API Support
+ */
+
+require("dotenv").config();
+var Srf = require("drachtio-srf");
+var Mrf = require("drachtio-fsmrf");
+
+// Import application modules
+var httpServerModule = require("./lib/http-server");
+var createHttpServer = httpServerModule.createHttpServer;
+var cleanupOldFiles = httpServerModule.cleanupOldFiles;
+var AudioForkServer = require("./lib/audio-fork").AudioForkServer;
+var sipHandler = require("./lib/sip-handler");
+var handleInvite = sipHandler.handleInvite;
+var extractCallerId = sipHandler.extractCallerId;
+var whisperClient = require("./lib/whisper-client");
+var claudeBridge = require("./lib/claude-bridge");
+var ttsService = require("./lib/tts-service");
+
+// Multi-extension support
+var deviceRegistry = require("./lib/device-registry");
+var MultiRegistrar = require("./lib/multi-registrar");
+
+// Connection retry utility
+var connectionRetry = require("./lib/connection-retry");
+var connectWithRetry = connectionRetry.connectWithRetry;
+
+// Import outbound calling routes
+var outboundModule = require("./lib/outbound-routes");
+var outboundRouter = outboundModule.router;
+var setupOutboundRoutes = outboundModule.setupRoutes;
+
+// Import query routes
+var queryModule = require("./lib/query-routes");
+var queryRouter = queryModule.router;
+var setupQueryRoutes = queryModule.setupRoutes;
+
+// Load device registry first
+// deviceRegistry is a singleton, already instantiated
+
+// Configuration
+var config = {
+  drachtio: {
+    host: process.env.DRACHTIO_HOST || "drachtio",
+    port: parseInt(process.env.DRACHTIO_PORT) || 9022,
+    secret: process.env.DRACHTIO_SECRET || "cymru"
+  },
+  freeswitch: {
+    host: process.env.FREESWITCH_HOST || "freeswitch",
+    port: parseInt(process.env.FREESWITCH_PORT) || 8021,
+    secret: process.env.FREESWITCH_SECRET || "JambonzR0ck$"
+  },
+  sip: {
+    extension: process.env.SIP_EXTENSION || "9000",
+    auth_id: process.env.SIP_AUTH_ID || "Au0XZPTpJY",
+    password: process.env.SIP_AUTH_PASSWORD || "DGHwMW6v25",
+    domain: process.env.SIP_DOMAIN || "your3cx.3cx.us",
+    registrar: process.env.SIP_REGISTRAR || "your3cx.3cx.us",
+    registrar_port: parseInt(process.env.SIP_REGISTRAR_PORT) || 5060,
+    expiry: parseInt(process.env.SIP_EXPIRY) || 3600
+  },
+  external_ip: process.env.EXTERNAL_IP || "10.70.7.81",
+  http_port: parseInt(process.env.HTTP_PORT) || 3000,
+  ws_port: parseInt(process.env.WS_PORT) || 3001,
+  audio_dir: process.env.AUDIO_DIR || "/tmp/voice-audio"
+};
+
+// Initialize drachtio SRF
+var srf = new Srf();
+var mediaServer = null;
+var httpServer = null;
+var audioForkServer = null;
+var registrar = null;
+var drachtioConnected = false;
+var freeswitchConnected = false;
+var isReady = false;
+
+// Log startup
+console.log("\n" + "=".repeat(64));
+console.log("          Voice Interface Application Starting                 ");
+console.log("       (with Multi-Extension + Query API Support)              ");
+console.log("=".repeat(64));
+console.log("\nConfiguration:");
+console.log("  - drachtio:    " + config.drachtio.host + ":" + config.drachtio.port);
+console.log("  - FreeSWITCH:  " + config.freeswitch.host + ":" + config.freeswitch.port);
+console.log("  - SIP Domain:  " + config.sip.domain);
+console.log("  - Registrar:   " + config.sip.registrar + ":" + config.sip.registrar_port);
+console.log("  - External IP: " + config.external_ip);
+console.log("  - HTTP Port:   " + config.http_port);
+console.log("  - WS Port:     " + config.ws_port);
+console.log("  - Audio Dir:   " + config.audio_dir);
+console.log("  - Mix Type:    " + (process.env.AUDIO_FORK_MIXTYPE || "L") + " (capture direction)");
+console.log("\n[DEVICES] Loaded " + Object.keys(deviceRegistry.getAllDevices()).length + " device extensions");
+console.log("\nWaiting for connections...\n");
+
+// Connect to drachtio
+srf.connect({
+  host: config.drachtio.host,
+  port: config.drachtio.port,
+  secret: config.drachtio.secret
+});
+
+srf.on("connect", function(err, hostport) {
+  console.log("[" + new Date().toISOString() + "] DRACHTIO Connected at " + hostport);
+  drachtioConnected = true;
+
+  var localAddress = config.external_ip;
+  if (hostport && hostport.length > 0) {
+    var match = hostport[0].match(/\/([^:]+)/);
+    if (match) localAddress = match[1];
+  }
+  console.log("[DRACHTIO] Local SIP address: " + localAddress);
+
+  // Start Multi-Registration for all devices
+  if (!registrar) {
+    registrar = new MultiRegistrar(srf, {
+      domain: config.sip.domain,
+      registrar: config.sip.registrar,
+      registrar_port: config.sip.registrar_port,
+      local_address: localAddress,
+      local_port: parseInt(process.env.DRACHTIO_SIP_PORT) || 5060,
+      expiry: config.sip.expiry
+    });
+
+    // Register all devices from config
+    registrar.registerAll(deviceRegistry.getRegistrationConfigs());
+  }
+
+  checkReadyState();
+});
+
+srf.on("error", function(err) {
+  console.error("[" + new Date().toISOString() + "] DRACHTIO error: " + err.message);
+  drachtioConnected = false;
+});
+
+// Initialize FreeSWITCH MRF with retry logic
+var mrf = new Mrf(srf);
+
+// Define FreeSWITCH connection function
+function connectToFreeswitch() {
+  return mrf.connect({
+    address: config.freeswitch.host,
+    port: config.freeswitch.port,
+    secret: config.freeswitch.secret
+  });
+}
+
+// Connect with exponential backoff retry
+// Retry schedule: 1s, 2s, 3s, 5s, 5s, 5s, 10s, 10s, 10s, 10s (max 10 retries)
+connectWithRetry(connectToFreeswitch, {
+  maxRetries: 10,
+  retryDelays: [1000, 2000, 3000, 5000, 5000, 5000, 10000, 10000, 10000, 10000],
+  name: 'FREESWITCH'
+})
+.then(function(ms) {
+  mediaServer = ms;
+  freeswitchConnected = true;
+  console.log("[" + new Date().toISOString() + "] FREESWITCH Ready for calls");
+  checkReadyState();
+})
+.catch(function(err) {
+  console.error("[" + new Date().toISOString() + "] FREESWITCH Connection failed permanently: " + err.message);
+  console.error("[" + new Date().toISOString() + "] Please check:");
+  console.error("  1. FreeSWITCH container is running: docker ps | grep freeswitch");
+  console.error("  2. ESL port 8021 is accessible");
+  console.error("  3. EXTERNAL_IP is set correctly in .env");
+  process.exit(1);
+});
+
+// Initialize servers
+function initializeServers() {
+  var fs = require("fs");
+  if (!fs.existsSync(config.audio_dir)) {
+    fs.mkdirSync(config.audio_dir, { recursive: true });
+  }
+
+  // HTTP server for TTS audio
+  httpServer = createHttpServer(config.audio_dir, config.http_port);
+  console.log("[" + new Date().toISOString() + "] HTTP Server started on port " + config.http_port);
+
+  // WebSocket server for audio fork
+  audioForkServer = new AudioForkServer({ port: config.ws_port });
+  audioForkServer.start();
+  audioForkServer.on("listening", function() {
+    console.log("[" + new Date().toISOString() + "] WEBSOCKET Audio fork server started on port " + config.ws_port);
+  });
+  audioForkServer.on("session", function(session) {
+    console.log("[AUDIO] New session for call " + session.callUuid);
+  });
+
+  // TTS service
+  ttsService.setAudioDir(config.audio_dir);
+  console.log("[" + new Date().toISOString() + "] TTS Service configured");
+
+  // ========== OUTBOUND CALLING ROUTES ==========
+  setupOutboundRoutes({
+    srf: srf,
+    mediaServer: mediaServer,
+    deviceRegistry: deviceRegistry,  // Required for device lookup
+    audioForkServer: audioForkServer,
+    whisperClient: whisperClient,
+    claudeBridge: claudeBridge,
+    ttsService: ttsService,
+    wsPort: config.ws_port
+  });
+
+  httpServer.app.use("/api", outboundRouter);
+  console.log("[" + new Date().toISOString() + "] OUTBOUND Calling API enabled");
+
+  // ========== QUERY API ROUTES ==========
+  setupQueryRoutes({
+    claudeBridge: claudeBridge
+  });
+
+  httpServer.app.use("/api", queryRouter);
+  console.log("[" + new Date().toISOString() + "] QUERY API enabled (/api/query, /api/devices)");
+
+  // Finalize HTTP server
+  httpServer.finalize();
+
+  // Cleanup old files periodically
+  setInterval(function() {
+    cleanupOldFiles(config.audio_dir, 5 * 60 * 1000);
+  }, 60 * 1000);
+}
+
+// Check ready state
+function checkReadyState() {
+  if (drachtioConnected && freeswitchConnected && !isReady) {
+    isReady = true;
+    console.log("\n[" + new Date().toISOString() + "] READY Voice interface is fully connected!");
+    console.log("=".repeat(64) + "\n");
+
+    initializeServers();
+
+    // Register SIP INVITE handler
+    srf.invite(function(req, res) {
+      handleInvite(req, res, {
+        audioForkServer: audioForkServer,
+        mediaServer: mediaServer,
+        deviceRegistry: deviceRegistry,
+        config: config,
+        whisperClient: whisperClient,
+        claudeBridge: claudeBridge,
+        ttsService: ttsService,
+        wsPort: config.ws_port,
+        externalIp: config.external_ip
+      }).catch(function(err) {
+        console.error("[" + new Date().toISOString() + "] CALL Error: " + err.message);
+      });
+    });
+
+    console.log("[" + new Date().toISOString() + "] SIP INVITE handler registered");
+    console.log("[" + new Date().toISOString() + "] Multi-extension voice interface ready!");
+  }
+}
+
+// Graceful shutdown
+function shutdown(signal) {
+  console.log("\n[" + new Date().toISOString() + "] Received " + signal + ", shutting down...");
+  if (registrar) registrar.stop();
+  if (httpServer) httpServer.close();
+  if (audioForkServer) audioForkServer.stop();
+  if (mediaServer) mediaServer.disconnect();
+  srf.disconnect();
+  setTimeout(function() { process.exit(0); }, 1000);
+}
+
+process.on("SIGTERM", function() { shutdown("SIGTERM"); });
+process.on("SIGINT", function() { shutdown("SIGINT"); });