@cemscale-voip/voip-sdk 1.34.0 → 1.35.0

package/README.md

@@ -280,6 +280,132 @@ 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'
+```
+
+#### Assigning an AI Agent to a Phone Number
+
+After creating an agent, link it to a DID so inbound calls are answered by the AI:
+
+```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',
+});
+
+// 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
+});
+
+// 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.',
+});
+
+// 2. Link agent to a phone number
+await voip.updateDid('did-uuid-here', {
+  inboundRoute: 'ai_agent',
+  routeTarget: 'support-bot',
+  aiTransferType: 'extension',
+  aiTransferTarget: '1001',
+});
+
+// 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) |
+
 ### CDR Export
 
 ```typescript
@@ -573,6 +699,16 @@ phone.on('error', (err) => console.error('Phone error:', err));
 | `updateDid(id, params)` | Update routing |
 | `deleteDid(id)` | Remove |
 
+### AI Agents
+| Method | Description |
+|--------|-------------|
+| `listAiAgents(tenantId?)` | List all AI agents |
+| `getAiAgent(agentId)` | Get agent details (includes `system_prompt`) |
+| `createAiAgent(params)` | Create new AI agent |
+| `updateAiAgent(agentId, params)` | Update agent config |
+| `deleteAiAgent(agentId)` | Delete agent |
+| `aiAgentsHealth()` | Check AI Bridge connectivity |
+
 ### Tenants (superadmin)
 | Method | Description |
 |--------|-------------|

package/package.json

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