@cemscale-voip/voip-sdk 1.48.0 → 1.49.0

package/README.md

@@ -280,1018 +280,452 @@ await voip.blockNumber({ number: '+15559999999', reason: 'Spam', direction: 'inb
 const { blocked } = await voip.checkBlocked('+15559999999'); // true
 ```
 
-### AI Agents (Voice AI)
-
-Create and manage AI phone agents powered by Gemini. Agents answer calls, speak to callers in real-time, and can transfer to humans.
-
-**No extra configuration needed.** AI Agents work through the same `voip` client — no separate `BRIDGE_URL` or `BRIDGE_API_KEY` required.
-
-```typescript
-// List all AI agents
-const { agents } = await voip.listAiAgents();
-console.log(agents);
-// [{ agent_id: 'acme-sales', display_name: 'Sofia', voice: 'Kore', ... }]
-
-// Create a new AI agent
-const { agent } = await voip.createAiAgent({
-  agent_id: 'acme-sales',           // unique slug (used as route target)
-  display_name: 'Sofia',             // name shown in dashboard/logs
-  company: 'Acme Corp',              // company context for the AI
-  role: 'Sales Representative',      // role context
-  language: 'en',                    // 'en', 'es', 'fr', etc.
-  voice: 'Kore',                     // Gemini voice: Kore, Aoede, Charon, Fenrir, Puck
-  speak_first: true,                 // agent greets the caller first
-  thinking_level: 'minimal',         // minimal, low, medium, high
-  temperature: 0.7,                  // 0.0 (precise) to 1.0 (creative)
-  system_prompt: `You are Sofia, a professional sales representative for Acme Corp.
-You speak English and Spanish fluently. Respond in whichever language the caller uses.
-Be conversational, warm, and helpful. Keep responses SHORT (1-2 sentences).
-If the caller asks to speak with a human, transfer them.
-Start with: "Thank you for calling Acme Corp, how can I help you today?"`,
-});
-
-// Update an existing agent
-await voip.updateAiAgent('acme-sales', {
-  display_name: 'Sofia v2',
-  system_prompt: 'Updated instructions...',
-  voice: 'Aoede',
-  temperature: 0.5,
-});
-
-// Get a single agent
-const { agent: detail } = await voip.getAiAgent('acme-sales');
-console.log(detail.system_prompt);
-
-// Delete an agent
-await voip.deleteAiAgent('acme-sales');
 
-// Health check (verify AI Bridge is connected)
-const health = await voip.aiAgentsHealth();
-console.log(health.status); // 'connected'
-```
+### AI Agents (Voice AI)
 
+AI agents are virtual receptionists powered by Google Gemini 3.1 Live API. They answer phone calls, hold natural conversations in English/Spanish, and perform real actions during the call (create leads, send SMS, book appointments, transfer to humans).
 
+#### SDK Methods
 
-#### All Editable Agent Fields
+| Method | Description |
+|--------|-------------|
+| `createAiAgent(params)` | Create a new AI agent |
+| `updateAiAgent(agentId, params)` | Update any field on an agent |
+| `deleteAiAgent(agentId)` | Delete an agent |
+| `getAiAgent(agentId)` | Get agent details (includes system_prompt) |
+| `listAiAgents()` | List all agents |
+| `listAiVoices()` | List available voices (30 Chirp 3 HD voices) |
+| `previewAiVoice(voice, text)` | Preview a voice with sample text |
+| `moveAiAgent(agentId, newTenantId)` | Move agent to another tenant |
+| `aiAgentsHealth()` | Check AI Bridge connectivity |
 
-Every field below can be updated via `updateAiAgent()`. Only include the fields you want to change — omitted fields keep their current values.
+#### Create an Agent
 
 ```typescript
-await voip.updateAiAgent('my-agent', {
-  // ─── Identity ─────────────────────────────────
-  display_name: 'Sofia',           // Agent's spoken name
-  company: 'Acme Corp',           // Company the agent represents
-  role: 'Sales Representative',   // Agent's role/title
-  language: 'es',                 // BCP-47 language code
-
-  // ─── Voice ────────────────────────────────────
-  voice: 'Sulafat',               // Chirp 3 HD voice (use listAiVoices())
-
-  // ─── Behavior ─────────────────────────────────
-  speak_first: true,              // Agent speaks first on connect
-  max_duration_s: 600,            // Max call length (seconds)
-  idle_timeout_s: 30,             // Silence timeout (seconds)
-  enable_transcription: false,    // Real-time transcription
-
-  // ─── AI Model ─────────────────────────────────
-  temperature: 0.5,               // 0-2, lower = more deterministic
-  thinking_level: 'minimal',      // 'minimal' | 'medium' | 'high'
-  system_prompt: '...',           // Full system prompt text
-
-  // ─── Tools ────────────────────────────────────
-  tools: [                        // Available functions during calls
-    'transfer_to_human',          // Transfer to human (built-in)
-    'end_call',                   // End call (built-in)
-    'create_lead',                // Create CRM lead (webhook)
-    'leave_message',              // Save message (webhook)
-    'schedule_appointment',       // Book appointment (webhook)
-    'send_sms',                   // Send SMS (webhook)
-    'check_policy_status',        // Look up policy (webhook)
+const { agent } = await voip.createAiAgent({
+  agent_id: 'my-receptionist',       // unique slug, cannot change after creation
+  display_name: 'Sofia',             // name the AI uses
+  company: 'Acme Corp',              // company context
+  role: 'Receptionist',              // role context
+  language: 'en',                    // 'en', 'es', etc.
+  voice: 'Sulafat',                  // use listAiVoices() for options
+  speak_first: true,                 // AI greets caller first
+  temperature: 0.5,                  // 0-2, lower = more consistent
+  thinking_level: 'minimal',         // 'minimal' | 'medium' | 'high'
+  system_prompt: 'You are Sofia...',  // full AI instructions
+  tools: [
+    'transfer_to_human',             // built-in: transfer call
+    'end_call',                      // built-in: hang up
+    'create_lead',                   // webhook: create CRM lead
+    'leave_message',                 // webhook: save message
+    'schedule_appointment',          // webhook: book appointment
+    'send_sms',                      // webhook: send text message
+    'check_policy_status',           // webhook: look up policy
   ],
   tools_webhook_url: 'https://your-crm.com/api/webhooks/ai-tools',
-
-  // ─── Messages ─────────────────────────────────
-  greeting: 'Hello! How can I help?',  // Override speak_first greeting
-  farewell: 'Thanks for calling!',     // Override farewell message
+  max_duration_s: 600,               // max call length (seconds)
+  idle_timeout_s: 30,                // silence timeout (seconds)
 });
 ```
 
-**Clearing fields:** Send `null` to clear string fields (`system_prompt: null`, `tools_webhook_url: null`). Send `[]` to clear tools. Number and boolean fields cannot be nulled — send the default value instead.
-
-#### Assigning an AI Agent to a Phone Number
+#### Update an Agent
 
-After creating an agent, link it to a DID so inbound calls are answered by the AI:
+Every field is editable after creation (except `agent_id`). Only send the fields you want to change:
 
 ```typescript
-// Assign agent to DID — calls to this number now go to the AI
-await voip.updateDid('did-uuid', {
-  inboundRoute: 'ai_agent',
-  routeTarget: 'acme-sales',         // must match agent_id
-  aiTransferType: 'queue',            // where AI transfers when caller asks for human
-  aiTransferTarget: 'support-queue-uuid',
+// Change the voice and name
+await voip.updateAiAgent('my-receptionist', {
+  display_name: 'Isabella',
+  voice: 'Aoede',
 });
 
-// Transfer types: 'extension', 'queue', 'ringgroup', 'ivr', 'external', 'voicemail'
-// Transfer target: the UUID/number of the destination
-```
-
-#### Complete Example: Full Agent Setup
-
-```typescript
-import { VoIPClient } from '@cemscale-voip/voip-sdk';
-
-const voip = new VoIPClient({
-  apiUrl: process.env.VOIP_API_URL,   // https://voip-api.cemscale.com
-  apiKey: process.env.VOIP_API_KEY,   // your API key
+// Change the system prompt
+await voip.updateAiAgent('my-receptionist', {
+  system_prompt: 'You are Isabella, a bilingual receptionist...',
 });
 
-// 1. Create the agent
-const { agent } = await voip.createAiAgent({
-  agent_id: 'support-bot',
-  display_name: 'Alex',
-  company: 'My Company',
-  language: 'en',
-  voice: 'Kore',
-  speak_first: true,
-  thinking_level: 'minimal',
-  system_prompt: 'You are Alex, a support agent for My Company. Help callers with their issues. Transfer to a human only if the caller explicitly asks.',
+// Change tools
+await voip.updateAiAgent('my-receptionist', {
+  tools: ['transfer_to_human', 'end_call', 'send_sms'],
 });
 
-// 2. Link agent to a phone number
-await voip.updateDid('did-uuid-here', {
-  inboundRoute: 'ai_agent',
-  routeTarget: 'support-bot',
-  aiTransferType: 'extension',
-  aiTransferTarget: '1001',
+// Change behavior
+await voip.updateAiAgent('my-receptionist', {
+  temperature: 0.3,
+  speak_first: false,
+  max_duration_s: 300,
+  idle_timeout_s: 15,
 });
 
-// Now when someone calls that number, Alex (the AI) answers.
-// If the caller says "let me talk to a person", Alex transfers to extension 1001.
-```
-
-#### Available Voices
-
-| Voice | Style |
-|-------|-------|
-| `Kore` | Professional, warm (default) |
-| `Aoede` | Friendly, energetic |
-| `Charon` | Deep, authoritative |
-| `Fenrir` | Calm, measured |
-| `Puck` | Upbeat, playful |
-
-#### Agent Fields Reference
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `agent_id` | string | Yes | — | Unique slug identifier (e.g. `acme-sales`) |
-| `display_name` | string | Yes | — | Display name in dashboard and logs |
-| `company` | string | No | `display_name` | Company name for AI context |
-| `role` | string | No | `AI Assistant` | Role context for the AI |
-| `language` | string | No | `en` | Language code: `en`, `es`, `fr`, etc. |
-| `voice` | string | No | `Kore` | Gemini voice name |
-| `system_prompt` | string | No | `''` | Instructions for the AI agent |
-| `speak_first` | boolean | No | `true` | Agent greets caller first |
-| `thinking_level` | string | No | `minimal` | Reasoning depth: `minimal`, `low`, `medium`, `high` |
-| `temperature` | number | No | `0.7` | Creativity: 0.0 (precise) to 1.0 (creative) |
-| `tools` | string[] | No | `[]` | List of tools the agent can use (see below) |
-| `tools_webhook_url` | string | No | `''` | URL where tool invocations are sent via POST |
-
-#### AI Agent Tools (Function Calling)
-
-During a phone call, the AI agent can invoke tools — actions that do something in the real world. When Gemini decides to call a tool, the platform either handles it internally (transfer, hangup) or sends a POST request to your `tools_webhook_url` and waits for your response. Gemini then uses your response to continue the conversation naturally.
-
-**There are 7 standard tools available:**
-
-| Tool Name | Type | Description | Webhook? |
-|-----------|------|-------------|----------|
-| `transfer_to_human` | Built-in | Transfers the live call to a human agent at the configured extension via PBX | No — handled internally by the platform |
-| `end_call` | Built-in | Ends the phone call after the AI says goodbye. Triggers after 2 seconds to let final audio play | No — handled internally by the platform |
-| `create_lead` | Webhook | Creates a new lead/prospect. Gemini collects first_name, last_name, phone, email, company, interest, notes from the caller | Yes — POST to your `tools_webhook_url` |
-| `leave_message` | Webhook | Records a message. Gemini collects caller_name, caller_phone, message content, urgency, and who it's for | Yes — POST to your `tools_webhook_url` |
-| `schedule_appointment` | Webhook | Books an appointment. Gemini collects caller_name, phone, preferred date, time, duration, purpose | Yes — POST to your `tools_webhook_url` |
-| `check_policy_status` | Webhook | Looks up a policy/account status. Gemini collects policy_number, phone, last_name, date_of_birth, lookup_type | Yes — POST to your `tools_webhook_url` |
-| `send_sms` | Webhook | Sends an SMS text message to the caller during the live call. Gemini collects to_phone, message content, purpose, caller_name | Yes — POST to your `tools_webhook_url` |
-
-**Complete flow — what happens when a tool is invoked:**
-
-```
-EXAMPLE: Caller wants to leave a message
-
-1. Caller says: "I'd like to leave a message for the sales team"
-2. Gemini (AI) says: "Sure, I can take that for you. What's your name?"
-3. Caller says: "Juan Garcia"
-4. Gemini says: "Got it, Juan. And what's the best number to reach you?"
-5. Caller says: "305-123-4567"
-6. Gemini says: "Perfect. What's the message you'd like me to pass along?"
-7. Caller says: "I'm interested in the premium plan, please have someone call me back"
-8. Gemini says: "Let me confirm — your message for the sales team is that you're
-   interested in the premium plan and you'd like a callback at 305-123-4567. Is that right?"
-9. Caller says: "Yes, that's correct"
-
-10. >>> Gemini invokes the tool: leave_message({
-      caller_name: "Juan Garcia",
-      caller_phone: "+13051234567",
-      for_person: "sales team",
-      message: "Interested in the premium plan, requesting callback",
-      urgent: false,
-      callback_preferred_time: "anytime"
-    })
-
-11. >>> Platform sends POST to YOUR tools_webhook_url:
-    POST https://your-crm.com/api/ai-tools-webhook
-    Content-Type: application/json
-
-    {
-      "function": "leave_message",
-      "args": {
-        "caller_name": "Juan Garcia",
-        "caller_phone": "+13051234567",
-        "for_person": "sales team",
-        "message": "Interested in the premium plan, requesting callback",
-        "urgent": false,
-        "callback_preferred_time": "anytime"
-      },
-      "call_id": "ff6a1693-b2f8-123f-b8b1-0a7dee2809a7",
-      "tenant_id": "6a097cb2-504f-43be-819a-b76209976818"
-    }
-
-12. >>> YOUR app processes it, saves to database, and responds:
-    {
-      "status": "saved",
-      "message": "Message recorded successfully. The sales team will call Juan back today."
-    }
-
-13. >>> Gemini reads your response and tells the caller:
-    "All set, Juan. I've passed your message to the sales team.
-     They'll give you a call back today. Is there anything else?"
-
-14. Caller says: "No, that's all. Thanks!"
-
-15. >>> Gemini invokes: end_call({ reason: "conversation_complete", summary: "Took message for sales team from Juan Garcia" })
-
-16. >>> Platform waits 2 seconds for final audio, then hangs up the call.
-```
-
-
-**Example 2: SMS confirmation during a call**
-
-```
-EXAMPLE: Caller schedules an appointment and wants a text confirmation
-
-1. Caller says: "Can I schedule a consultation for Friday?"
-2. Gemini (AI): "Of course! What time works best for you?"
-3. Caller: "Around 2pm would be great"
-4. Gemini: "Perfect. I have you down for Friday at 2pm. Can I get your name?"
-5. Caller: "It's Ana Martinez"
-6. Gemini: "Thank you Ana. And your phone number?"
-7. Caller: "786-555-0198"
-
-8. >>> Gemini invokes: schedule_appointment({...})
-9. >>> Your app responds: { status: "scheduled", message: "Confirmed for Friday at 2pm." }
-
-10. Gemini: "You're all set for Friday at 2pm, Ana. Would you like me
-    to send you a text confirmation with the details?"
-11. Caller: "Yes please, send it to this number"
-
-12. >>> Gemini invokes: send_sms({
-      to_phone: "+17865550198",
-      message: "Hi Ana! Your consultation is confirmed for Friday at 2:00 PM at our office. Address: 123 Main St. Reply HELP for questions.",
-      purpose: "appointment_confirmation",
-      caller_name: "Ana Martinez"
-    })
-
-13. >>> Platform sends POST to YOUR tools_webhook_url:
-    POST https://your-crm.com/api/ai-tools-webhook
-    Content-Type: application/json
-
-    {
-      "function": "send_sms",
-      "args": {
-        "to_phone": "+17865550198",
-        "message": "Hi Ana! Your consultation is confirmed for Friday at 2:00 PM...",
-        "purpose": "appointment_confirmation",
-        "caller_name": "Ana Martinez"
-      },
-      "call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-      "tenant_id": "6a097cb2-504f-43be-819a-b76209976818"
-    }
-
-14. >>> YOUR app sends the SMS via Twilio/Telnyx/etc and responds:
-    { "status": "sent", "message": "The text has been sent to your phone." }
-
-15. >>> Gemini tells the caller:
-    "Done! I just sent you a text with your appointment details.
-     Is there anything else I can help you with?"
-
-16. Caller: "No that's it, thank you!"
-
-17. >>> Gemini invokes: end_call({ reason: "conversation_complete", summary: "Scheduled Friday 2pm consultation for Ana Martinez, sent SMS confirmation" })
-```
-
-**Step 1 — Create the agent with tools enabled:**
-
-```typescript
-const { agent } = await voip.createAiAgent({
-  agent_id: 'acme-receptionist',
-  display_name: 'Sofia',
-  company: 'Acme Corp',
-  language: 'en',
+// Change everything at once
+await voip.updateAiAgent('my-receptionist', {
+  display_name: 'Daniela',
+  company: 'New Company',
+  role: 'Sales Agent',
+  language: 'es',
   voice: 'Sulafat',
   speak_first: true,
-  thinking_level: 'minimal',
   temperature: 0.5,
-
-  // Enable the tools you want this agent to use
-  tools: [
-    'transfer_to_human',   // Transfer to human when caller asks
-    'end_call',            // Hang up when conversation is done
-    'create_lead',         // Create leads in your CRM
-    'leave_message',       // Take messages from callers
-    'schedule_appointment', // Book appointments
-    'send_sms',              // Send SMS confirmations during calls
-  ],
-
-  // YOUR endpoint that receives tool calls — you MUST build this
-  tools_webhook_url: 'https://your-app.com/api/ai-tools-webhook',
-
-  system_prompt: `You are Sofia, a professional receptionist for Acme Corp.
-You are warm, natural, and efficient. Keep responses to 1-2 sentences.
-You can help callers with:
-- Leaving a message for the team
-- Scheduling an appointment
-- Answering general questions about Acme Corp
-- Creating a lead when a new prospect calls
-If the caller asks to speak with a person, transfer them.
-When the conversation is complete, end the call politely.`,
+  thinking_level: 'minimal',
+  max_duration_s: 600,
+  idle_timeout_s: 30,
+  system_prompt: 'You are Daniela...',
+  tools: ['transfer_to_human', 'end_call', 'create_lead', 'send_sms'],
+  tools_webhook_url: 'https://your-crm.com/api/webhooks/ai-tools',
+  greeting: 'Hola, gracias por llamar',
+  farewell: 'Que tengas buen dia',
 });
 ```
 
-**Step 2 — Build the webhook endpoint in your app:**
-
-Your app needs ONE endpoint that receives ALL tool calls. The `function` field tells you which tool was invoked. The `args` field contains the data Gemini collected from the caller. The `call_id` and `tenant_id` let you track which call and tenant triggered the action.
+**Clearing fields:** Send `null` to clear string fields (`tools_webhook_url: null`). Send `[]` to clear tools.
+
+#### All Agent Fields Reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `agent_id` | string | required | Unique slug (cannot change after creation) |
+| `display_name` | string | required | Name the AI uses on calls |
+| `company` | string | display_name | Company name for AI context |
+| `role` | string | `"AI Assistant"` | Role/title for AI context |
+| `language` | string | `"en"` | Language code: `en`, `es`, `fr`, etc. |
+| `voice` | string | `"Kore"` | Chirp 3 HD voice name |
+| `system_prompt` | string | `""` | Full instructions for the AI |
+| `speak_first` | boolean | `true` | Whether AI greets caller first |
+| `temperature` | number | `0.7` | Creativity: 0.0 precise, 1.0 creative |
+| `thinking_level` | string | `"minimal"` | `"minimal"`, `"medium"`, `"high"` |
+| `tools` | string[] | `[]` | Tools the agent can invoke |
+| `tools_webhook_url` | string/null | `null` | URL for webhook tool calls |
+| `greeting` | string/null | `null` | Override greeting phrase |
+| `farewell` | string/null | `null` | Override farewell phrase |
+| `max_duration_s` | number | `600` | Max call duration (seconds) |
+| `idle_timeout_s` | number | `30` | Silence timeout (seconds) |
+| `enable_transcription` | boolean | `false` | Enable real-time transcription |
+
+#### Assign Agent to a Phone Number
+
+After creating an agent, link it to a DID so inbound calls go to the AI:
 
 ```typescript
-// In your app (Express, Fastify, Next.js API route, etc.)
-
-app.post('/api/ai-tools-webhook', async (req, res) => {
-  const { function: toolName, args, call_id, tenant_id } = req.body;
-
-  console.log(`[AI Tool] ${toolName} called during call ${call_id}`);
-  console.log(`[AI Tool] Args:`, args);
-
-  try {
-    switch (toolName) {
-
-      // ─── CREATE LEAD ──────────────────────────────────────────
-      // Gemini collected: first_name, last_name (optional), phone,
-      //   email (optional), company (optional), notes (optional),
-      //   interest (optional), source (optional)
-      case 'create_lead': {
-        const lead = await db.leads.create({
-          data: {
-            firstName:  args.first_name,
-            lastName:   args.last_name || '',
-            phone:      args.phone,
-            email:      args.email || null,
-            company:    args.company || null,
-            notes:      args.notes || null,
-            interest:   args.interest || null,
-            source:     'ai_phone_call',
-            callId:     call_id,
-            tenantId:   tenant_id,
-            createdAt:  new Date(),
-          },
-        });
-
-        // The "message" field is what Gemini reads back to the caller
-        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 ────────────────────────────────────────
-      // Gemini collected: caller_name, caller_phone, for_person (optional),
-      //   message, urgent (boolean, optional),
-      //   callback_preferred_time (optional)
-      case 'leave_message': {
-        const msg = await db.messages.create({
-          data: {
-            callerName:    args.caller_name,
-            callerPhone:   args.caller_phone,
-            forPerson:     args.for_person || null,
-            content:       args.message,
-            urgent:        args.urgent || false,
-            callbackTime:  args.callback_preferred_time || 'anytime',
-            callId:        call_id,
-            tenantId:      tenant_id,
-            createdAt:     new Date(),
-          },
-        });
-
-        // Optional: send a real-time notification to your team
-        await notifyTeam({
-          type: args.urgent ? 'URGENT_MESSAGE' : 'NEW_MESSAGE',
-          from: args.caller_name,
-          phone: args.caller_phone,
-          message: args.message,
-        });
-
-        return res.json({
-          status: 'saved',
-          message_id: msg.id,
-          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 ─────────────────────────────────
-      // Gemini collected: caller_name, phone, date, time (optional),
-      //   duration (optional, default "30 minutes"),
-      //   purpose, notes (optional)
-      case 'schedule_appointment': {
-        // Check availability in your calendar system
-        const isAvailable = await calendar.checkAvailability(
-          args.date,
-          args.time,
-        );
-
-        if (!isAvailable) {
-          // Tell Gemini the slot is not available — it will offer alternatives
-          return res.json({
-            status: 'unavailable',
-            message: `That time slot is not available. ` +
-                     `We have openings in the morning between 9 and 12, ` +
-                     `or in the afternoon between 2 and 4. ` +
-                     `Would any of those work?`,
-          });
-        }
-
-        const appointment = await calendar.create({
-          name:     args.caller_name,
-          phone:    args.phone,
-          date:     args.date,
-          time:     args.time || '10:00 AM',
-          duration: args.duration || '30 minutes',
-          purpose:  args.purpose,
-          notes:    args.notes || null,
-          callId:   call_id,
-          tenantId: tenant_id,
-        });
-
-        return res.json({
-          status: 'scheduled',
-          appointment_id: appointment.id,
-          message: `Appointment confirmed for ${args.date} at ${args.time}. ` +
-                   `${args.caller_name} will receive a confirmation shortly.`,
-        });
-      }
-
-      // ─── CHECK POLICY STATUS ──────────────────────────────────
-      // Gemini collected: policy_number, phone (optional),
-      //   last_name (optional), date_of_birth (optional),
-      //   lookup_type (optional: status/coverage/renewal/payment/claims)
-      case 'check_policy_status': {
-        const policy = await db.policies.findFirst({
-          where: { 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?`,
-          });
-        }
+await voip.updateDid('did-uuid', {
+  inboundRoute: 'ai_agent',
+  routeTarget: 'my-receptionist',    // must match agent_id
+  aiTransferType: 'extension',       // where transfer_to_human sends calls
+  aiTransferTarget: '1001',          // extension/queue to transfer to
+});
+// Transfer types: 'extension', 'queue', 'ringgroup', 'ivr', 'external', 'voicemail'
+```
 
-        return res.json({
-          status: 'found',
-          policy_number: policy.policyNumber,
-          policy_status: policy.status,        // e.g. "active", "expired", "pending"
-          renewal_date: policy.renewalDate,
-          balance_due: policy.balanceDue,
-          message: `Policy ${args.policy_number} is currently ${policy.status}. ` +
-                   `${policy.renewalDate ? 'Renewal date is ' + policy.renewalDate + '.' : ''} ` +
-                   `${policy.balanceDue ? 'Balance due: $' + policy.balanceDue + '.' : 'No balance due.'}`,
-        });
-      }
+#### Move Agent Between Tenants
 
+```typescript
+const result = await voip.moveAiAgent('my-receptionist', 'new-tenant-uuid');
+console.log(result.previous_tenant_id, '->', result.new_tenant_id);
+```
 
-      // --- SEND SMS -------------------------------------------------
-      // Gemini collected: to_phone, message, purpose (optional),
-      //   caller_name (optional)
-      case 'send_sms': {
-        // Send the SMS via your SMS provider (Twilio, Telnyx, etc.)
-        const smsResult = await smsProvider.send({
-          to:   args.to_phone,
-          body: args.message,
-          // Use your tenant's DID or a dedicated SMS number as the sender
-          from: tenant.smsNumber || tenant.mainDid,
-        });
+---
 
-        // Log it in your CRM
-        await db.smsLogs.create({
-          data: {
-            toPhone:    args.to_phone,
-            message:    args.message,
-            purpose:    args.purpose || 'general',
-            callerName: args.caller_name || null,
-            callId:     call_id,
-            tenantId:   tenant_id,
-            status:     smsResult.success ? 'sent' : 'failed',
-            createdAt:  new Date(),
-          },
-        });
+### AI Tools & Webhook Integration
 
-        if (!smsResult.success) {
-          return res.json({
-            status: 'failed',
-            message: "I was unable to send the text message right now. " +
-                     "Let me take note of your number and we will send it to you shortly.",
-          });
-        }
+When the AI agent invokes a webhook tool during a live call, the platform sends a POST to your `tools_webhook_url`. Your CRM processes the action and responds with JSON. The `message` field in your response is what the AI speaks to the caller.
 
-        return res.json({
-          status: 'sent',
-          sms_id: smsResult.id,
-          message: "The text message has been sent to " + args.to_phone + ". " +
-                   "Please check your messages in a moment.",
-        });
-      }
+#### Architecture
 
-      // ─── UNKNOWN TOOL ─────────────────────────────────────────
-      default: {
-        console.warn(`[AI Tool] Unknown tool: ${toolName}`);
-        return res.json({
-          status: 'unknown',
-          message: `I've noted your request. A team member will follow up.`,
-        });
-      }
-    }
-  } catch (error) {
-    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 with you.`,
-    });
-  }
-});
+```
+Caller speaks -> Gemini AI -> invokes tool (e.g. send_sms)
+  -> VoIP Platform -> POST to VoIP API -> POST to YOUR webhook
+  -> Your CRM processes (sends SMS, creates lead, etc.)
+  -> Your CRM responds: { status: "sent", message: "Text sent" }
+  -> Gemini speaks to caller: "I just sent you the text"
 ```
 
-**Step 3 — Link the agent to a phone number (DID):**
+#### The 7 Standard Tools
 
-```typescript
-// Assign the agent to answer a specific phone number
-await voip.updateDid('did-uuid-here', {
-  inboundRoute: 'ai_agent',
-  routeTarget: 'acme-receptionist',  // must match agent_id
-  aiTransferType: 'extension',       // where transfer_to_human sends the call
-  aiTransferTarget: '1001',          // extension number to transfer to
-});
-```
+| Tool | Type | What it does |
+|------|------|-------------|
+| `transfer_to_human` | Built-in | Transfers call to the extension/queue configured on the DID |
+| `end_call` | Built-in | Hangs up after 2s delay so AI can say goodbye |
+| `create_lead` | Webhook | Creates a lead/prospect in your CRM |
+| `leave_message` | Webhook | Saves a message from the caller |
+| `schedule_appointment` | Webhook | Books an appointment |
+| `send_sms` | Webhook | Sends an SMS text message during the live call |
+| `check_policy_status` | Webhook | Looks up a policy/account status |
+
+#### Webhook Request (what your CRM receives)
 
-**Webhook request your app receives (POST):**
+Every webhook tool call arrives as a POST with this format:
 
 ```json
 {
-  "function": "create_lead",
+  "function": "send_sms",
   "args": {
-    "first_name": "Maria",
-    "last_name": "Rodriguez",
-    "phone": "+17865551234",
-    "email": "maria@gmail.com",
-    "company": "Rodriguez LLC",
-    "interest": "Premium shipping plan",
-    "notes": "Called asking about bulk shipping rates for e-commerce business"
+    "to_phone": "+17865551234",
+    "message": "Your appointment is confirmed for Friday at 2pm",
+    "purpose": "appointment_confirmation",
+    "caller_name": "Ana Martinez"
   },
   "call_id": "ff6a1693-b2f8-123f-b8b1-0a7dee2809a7",
   "tenant_id": "6a097cb2-504f-43be-819a-b76209976818"
 }
 ```
 
-**Webhook response your app must return (JSON):**
+**Headers:**
+
+| Header | Value |
+|--------|-------|
+| `Content-Type` | `application/json` |
+| `Authorization` | `Bearer csk_live_...` (your VOIP_TOOLS_WEBHOOK_KEY) |
+| `X-Webhook-Source` | `voiceai-platform` |
+
+#### Webhook Response (what your CRM must return)
 
 ```json
 {
-  "status": "created",
-  "message": "Lead created for Maria Rodriguez. A sales rep will follow up within the hour."
+  "status": "sent",
+  "message": "The text message has been sent to your phone."
 }
 ```
 
-**Important rules for the webhook response:**
-- The `message` field is what Gemini speaks to the caller. Write it naturally, as if a person is saying it on the phone.
-- Keep the `message` short — 1-2 sentences maximum.
-- If something fails, still return a `message` with a graceful fallback so Gemini can tell the caller.
-- Your webhook has a **10 second timeout**. If it doesn't respond in time, Gemini gets: `"Action has been recorded. A team member will follow up."`
-- If no `tools_webhook_url` is configured on the agent, webhook tools still "work" but always return the generic fallback message.
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | string | Result: `"sent"`, `"created"`, `"saved"`, `"scheduled"`, `"found"`, `"not_found"`, `"error"`, `"failed"` |
+| `message` | string | **What the AI speaks to the caller.** Write naturally, 1-2 sentences max. |
+
+**Rules:**
+- `message` is spoken aloud to the caller. Write it as natural speech.
+- Keep to 1-2 sentences max.
+- If something fails, still return a `message` with a graceful fallback.
+- Your webhook has a **9 second timeout**.
+- Return HTTP 200 for success, 500 for errors.
 
-**Tool arguments reference:**
+#### Tool Arguments Reference
 
-`create_lead` args:
+**`create_lead`**
 | Arg | Type | Required | Description |
 |-----|------|----------|-------------|
 | `first_name` | string | Yes | Caller's first name |
-| `last_name` | string | No | Caller's last name |
+| `last_name` | string | No | Last name |
 | `phone` | string | Yes | Phone number |
 | `email` | string | No | Email if provided |
 | `company` | string | No | Company name |
-| `interest` | string | No | What they're interested in |
-| `notes` | string | No | Additional notes |
-| `source` | string | No | Lead source (default: "phone_call") |
+| `interest` | string | No | What they want |
+| `notes` | string | No | Additional context |
 
-`leave_message` args:
+**`leave_message`**
 | Arg | Type | Required | Description |
 |-----|------|----------|-------------|
 | `caller_name` | string | Yes | Who is leaving the message |
 | `caller_phone` | string | Yes | Callback number |
 | `for_person` | string | No | Who the message is for |
 | `message` | string | Yes | Message content |
-| `urgent` | boolean | No | Whether caller said it's urgent |
-| `callback_preferred_time` | string | No | When they prefer a callback |
+| `urgent` | boolean | No | Marked as urgent |
+| `callback_preferred_time` | string | No | When to call back |
 
-`schedule_appointment` args:
+**`schedule_appointment`**
 | Arg | Type | Required | Description |
 |-----|------|----------|-------------|
-| `caller_name` | string | Yes | Who the appointment is for |
-| `phone` | string | Yes | Contact phone |
-| `date` | string | Yes | Preferred date ("tomorrow", "Thursday", "2026-04-18") |
-| `time` | string | No | Preferred time ("2pm", "morning", "10:30 AM") |
-| `duration` | string | No | Duration ("30 minutes", "1 hour") |
+| `caller_name` | string | Yes | Name |
+| `phone` | string | Yes | Phone |
+| `date` | string | Yes | Date ("Friday", "2026-04-18") |
+| `time` | string | No | Time ("2pm", "morning") |
+| `duration` | string | No | Duration ("30 minutes") |
 | `purpose` | string | Yes | Reason for appointment |
 | `notes` | string | No | Additional notes |
 
-`check_policy_status` args:
+**`send_sms`**
 | Arg | Type | Required | Description |
 |-----|------|----------|-------------|
-| `policy_number` | string | Yes | Policy or account number |
-| `phone` | string | No | Phone for verification |
-| `last_name` | string | No | Last name for verification |
-| `date_of_birth` | string | No | DOB for verification |
-| `lookup_type` | string | No | What to look up: "status", "coverage", "renewal", "payment", "claims" |
+| `to_phone` | string | Yes | Phone with country code ("+17865551234") |
+| `message` | string | Yes | Text message content |
+| `purpose` | string | No | Category: "appointment_confirmation", "address_info", etc. |
+| `caller_name` | string | No | For personalization |
 
-`send_sms` args:
+**`check_policy_status`**
 | Arg | Type | Required | Description |
 |-----|------|----------|-------------|
-| `to_phone` | string | Yes | Phone number to send SMS to, with country code (e.g. "+17865551234") |
-| `message` | string | Yes | Text message content. Max 160 chars recommended for single SMS |
-| `purpose` | string | No | Why the SMS is being sent: "appointment_confirmation", "address_info", "reference_number", "follow_up_link", "general" |
-| `caller_name` | string | No | Caller name for personalization and logging |
+| `policy_number` | string | Yes | Policy/account number |
+| `phone` | string | No | Verification |
+| `last_name` | string | No | Verification |
 
-`transfer_to_human` args (no webhook — handled internally):
+**`transfer_to_human`** (built-in, no webhook)
 | Arg | Type | Required | Description |
 |-----|------|----------|-------------|
-| `reason` | string | Yes | Why the caller wants to transfer |
-| `department` | string | No | Specific department if mentioned |
+| `reason` | string | Yes | Why caller wants transfer |
+| `department` | string | No | Specific department |
 
-`end_call` args (no webhook — handled internally):
+**`end_call`** (built-in, no webhook)
 | Arg | Type | Required | Description |
 |-----|------|----------|-------------|
-| `reason` | string | Yes | Why: "conversation_complete", "caller_goodbye", "no_response", "voicemail_detected" |
-| `summary` | string | No | Brief summary of the call |
+| `reason` | string | Yes | Why: "conversation_complete", "caller_goodbye", "no_response" |
+| `summary` | string | No | Brief call summary |
 
+#### CRM Webhook Setup
 
+**IMPORTANT:** Your webhook endpoint must NOT have your CRM's global auth middleware. It uses its own auth via the `Authorization: Bearer` header.
 
----
-
-#### 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:**
-
+**Step 1 — Add environment variable:**
 ```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.):**
+**Step 2 — Create the endpoint (register WITHOUT global auth middleware):**
 
 ```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;
+// Auth validation — checks Bearer token
+function validateAuth(req: any): boolean {
+  const expected = process.env.VOIP_TOOLS_WEBHOOK_KEY;
+  if (!expected) return false;
+  const auth = req.headers.authorization || '';
+  const token = auth.startsWith('Bearer ') ? auth.slice(7) : '';
+  if (token.length !== expected.length) return false;
+  try {
+    return crypto.timingSafeEqual(Buffer.from(token), Buffer.from(expected));
+  } catch { 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.
-
+// IMPORTANT: Register WITHOUT global auth middleware (no wrap(), no requireAuth)
 app.post('/api/webhooks/ai-tools', async (req, res) => {
-  // 1. Validate auth
-  if (!validateToolsWebhookAuth(req)) {
+  if (!validateAuth(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})`);
+  switch (toolName) {
 
-  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({
+    case 'create_lead': {
+      const lead = await db.leads.create({
+        data: {
           firstName: args.first_name,
-          lastName: args.last_name,
+          lastName: args.last_name || '',
           phone: args.phone,
-          email: args.email,
-          company: args.company,
-          interest: args.interest,
-          notes: args.notes,
+          email: args.email || null,
+          company: args.company || null,
+          interest: args.interest || null,
+          notes: args.notes || null,
+          source: 'ai_phone_call',
           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.`,
-        });
-      }
+        },
+      });
+      return res.json({
+        status: 'created',
+        message: `Record created for ${args.first_name}. A team member will follow up.`,
+      });
+    }
 
-      // ─── LEAVE MESSAGE ────────────────────────────────────────
-      case 'leave_message': {
-        // args: caller_name (required), caller_phone (required),
-        //   message (required), for_person, urgent, callback_preferred_time
-        const msg = await saveMessageInCrm({
+    case 'leave_message': {
+      await db.messages.create({
+        data: {
           callerName: args.caller_name,
           callerPhone: args.caller_phone,
-          message: args.message,
-          forPerson: args.for_person,
-          urgent: args.urgent,
-          callbackTime: args.callback_preferred_time,
+          forPerson: args.for_person || null,
+          content: args.message,
+          urgent: args.urgent || false,
+          callbackTime: args.callback_preferred_time || 'anytime',
           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.`,
-        });
-      }
+        },
+      });
+      return res.json({
+        status: 'saved',
+        message: args.urgent
+          ? `Flagged as urgent. Team will call ${args.caller_name} back right away.`
+          : `Message saved. Someone 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({
+    case 'schedule_appointment': {
+      await db.appointments.create({
+        data: {
           callerName: args.caller_name,
           phone: args.phone,
           date: args.date,
-          time: args.time,
-          duration: args.duration,
+          time: args.time || null,
+          duration: args.duration || '30 minutes',
           purpose: args.purpose,
-          notes: args.notes,
+          notes: args.notes || null,
           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 });
+        },
+      });
+      return res.json({
+        status: 'scheduled',
+        message: `Appointment confirmed for ${args.date}${args.time ? ' at ' + args.time : ''}.`,
+      });
+    }
 
-        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?`,
-          });
-        }
+    case 'send_sms': {
+      // Use YOUR SMS provider (Twilio, Telnyx, etc.)
+      const result = await smsProvider.send({
+        to: args.to_phone,
+        body: args.message,
+        from: process.env.SMS_FROM_NUMBER,
+      });
 
+      if (!result.success) {
         return res.json({
-          status: 'found',
-          message: `Policy ${args.policy_number} is currently ${policy.status}.`,
+          status: 'failed',
+          message: 'Unable to send the text right now. Let me note your number and we will send it shortly.',
         });
       }
+      return res.json({
+        status: 'sent',
+        message: 'Text message sent to ' + args.to_phone + '. Check your messages in a moment.',
+      });
+    }
 
-      // ─── UNKNOWN TOOL ─────────────────────────────────────────
-      default: {
-        console.warn(`[AI Tool] Unknown tool: ${toolName}`);
+    case 'check_policy_status': {
+      const policy = await db.policies.findFirst({
+        where: { policyNumber: args.policy_number },
+      });
+      if (!policy) {
         return res.json({
-          status: 'noted',
-          message: "I've noted your request. A team member will follow up.",
+          status: 'not_found',
+          message: `No policy found with number ${args.policy_number}. Can you double-check?`,
         });
       }
+      return res.json({
+        status: 'found',
+        message: `Policy ${args.policy_number} is ${policy.status}.`,
+      });
     }
-  } 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.",
-    });
+
+    default:
+      return res.json({
+        status: 'noted',
+        message: 'Noted. A team member will 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:**
-
+**Step 3 — Test 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"
-    },
+    "args": { "to_phone": "+17865551234", "message": "Test SMS" },
     "call_id": "test-123",
-    "tenant_id": "your-tenant-id"
+    "tenant_id": "test"
   }'
-
-# Expected response:
-# {"status":"sent","message":"The text message has been sent to +17865551234."}
+# Expected: {"status":"sent","message":"Text message sent to +17865551234..."}
 ```
 
+#### Example Flow: SMS During a Call
+
+```
+1. Caller: "Can you send me the address by text?"
+2. AI: "Sure! Let me confirm your number — is it 786-555-1234?"
+3. Caller: "Yes"
+4. AI invokes: send_sms({ to_phone: "+17865551234", message: "Our address: 123 Main St, Miami FL 33101" })
+5. Platform POSTs to your webhook
+6. Your CRM sends the SMS via Twilio and responds: { status: "sent", message: "Text sent" }
+7. AI: "Done! I just sent you a text with our address. Anything else?"
+```
 
 ### CDR Export
 

package/package.json

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