API Reference

1<script2  src="https://unpkg.com/@vanira/sdk@latest/dist/vanira-sdk.js"3  data-widget-id="YOUR_WIDGET_ID"4  data-pk-key="pk_live_YOUR_PUBLISHABLE_KEY"5  defer6></script>

1// Add once on your site (same page as the Vanira widget).2// Required when your agent uses the vanira_navigate preset.3window.addEventListener('vanira:navigate', (event) => {4  const path = event.detail.path; // e.g. "/pricing" or "/docs#section"5 6  // Option A — multi-page site or simple fallback:7  window.location.assign(path);8 9  // Option B — SPA router (pick one that matches your stack):10  // router.push(path);              // React Router: useNavigate()11  // navigate(path);                 // Vue Router12  // router.push(path);              // Next.js App Router13 14  event.detail.handled = true; // required — tells the SDK navigation succeeded15});

1npm install @vanira/sdk2# or3yarn add @vanira/sdk

1// Browser2const client = new VaniraClient({3  agentId: 'YOUR_AGENT_ID',4  apiKey: 'pk_live_<uuid>',5  onConnected: () => setStatus('connected'),6});7await client.connect();

1import { VaniraCallBox } from '@vanira/sdk';2import { useNavigate } from 'react-router-dom';3 4function AppShell() {5  const navigate = useNavigate();6 7  return (8    <>9      <YourRoutes />10      <VaniraCallBox11        agentId={import.meta.env.VITE_VANIRA_AGENT_ID}12        apiKey={import.meta.env.VITE_VANIRA_PK_KEY}13        onNavigate={(path) => navigate(path)}14        onCustomTool={(call, client) => {15          if (call.name === 'say_hi') {16            showGreetingPopup();17            if (call.execution_mode !== 'fire_and_forget') {18              client.sendToolResult(call.tool_call_id, { status: 'success' });19            }20          }21        }}22      />23    </>24  );25}

1<VaniraCallBox agentId="..." apiKey="...">2  {({ status, startCall, endCall }) =>3    status === 'connected'4      ? <button onClick={endCall}>Hang up</button>5      : <button onClick={startCall}>Talk to us</button>6  }7</VaniraCallBox>

1import { useRef } from 'react';2import {3  VaniraClient,4  PresetRenderer,5  type PresetRendererHandle,6} from '@vanira/sdk/headless';7 8const presetRef = useRef<PresetRendererHandle>(null);9let client: VaniraClient | null = null;10 11async function startCall() {12  client = new VaniraClient({13    agentId: 'YOUR_AGENT_ID',14    apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',15    onConnected: () => setStatus('connected'),16    onDisconnected: () => setStatus('idle'),17    onClientToolCall: (raw) => presetRef.current?.enqueueToolCall(raw),18  });19  await client.connect();20}

1<PresetRenderer ref={presetRef} client={client} onCustomTool={handleCustomTool} />

1// Style A — constructor callbacks + connect()2await client.connect();3 4// Style B — .on() listeners + start()5client.on('connected', () => setStatus('connected'));6client.on('tool_call', (tc) => presetRef.current?.enqueueToolCall(tc));7await client.start();

1import { useEffect, useState } from 'react';2import { VaniraClient, PresetRenderer } from '@vanira/sdk';3 4function App() {5  const [client] = useState(() => new VaniraClient({6    agentId: 'YOUR_AGENT_ID',7    apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY'8  }));9  const [activeToolCall, setActiveToolCall] = useState(null);10 11  useEffect(() => {12    client.on('tool_call', (toolCall) => {13      setActiveToolCall(toolCall);14    });15    16    client.start();17    return () => client.stop();18  }, [client]);19 20  return (21    <div>22      <MainDashboard />23 24      {/* Mount the PresetRenderer to automatically handle forms, calendars, etc. */}25      {activeToolCall && (26        <PresetRenderer27          client={client}28          toolCall={activeToolCall}29          onCustomTool={(toolCall) => {30            console.log('Handle your custom tool:', toolCall.name);31          }}32        />33      )}34    </div>35  );36}

1{2  "name": "Teja",3  "source": "website"4}

1<VaniraCallBox2  agentId="YOUR_AGENT_ID"3  apiKey="pk_live_YOUR_PUBLISHABLE_KEY"4  onCustomTool={(call, client) => {5    const { name, arguments: args, tool_call_id, execution_mode } = call;6 7    if (name === 'greet_user') {8      openGreetingModal(args.name); // args.name from frontend payload mapping9 10      if (execution_mode !== 'fire_and_forget' && tool_call_id) {11        client.sendToolResult(tool_call_id, {12          status: 'success',13          message: 'Greeting shown',14        });15      }16    }17  }}18/>

1{2  "name": "greet_user",3  "description": "Show a personalized greeting popup when the user says hello",4  "type": "client",5  "execution_mode": "blocking",6  "channels": ["voice_web"],7  "parameters": [8    {9      "name": "customer_name",10      "type": "string",11      "description": "The person's name from the conversation",12      "required": true13    }14  ],15  "client_fields": {16    "name": "{{customer_name}}",17    "source": "website"18  }19}

1try {2  await bookSlot(args.date);3  client.sendToolResult(tool_call_id, { status: 'success' });4} catch (e) {5  client.sendToolError(tool_call_id, e.message || 'Booking failed');6}

1const client = new VaniraClient({2  agentId: 'YOUR_AGENT_ID',3  apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',4 5  onSessionStarted: ({ prospectId, callId, serverUrl }) => {6    // Phase 1 — provisioned, still connecting to worker7    console.log('Provisioned:', { prospectId, callId, serverUrl });8    setStatus('connecting');9  },10 11  onConnected: () => {12    // Phase 2 — live (Talk to Agent connected state)13    setStatus('connected');14  },15 16  onDisconnected: () => setStatus('idle'),17 18  onError: (error) => {19    console.error('Connection error:', error);20    setStatus('error');21  },22 23  onTranscription: (text, isFinal) => {24    // isFinal = true means committed utterance.25    setTranscript(text);26  },27 28  onLocalStream: (stream) => {29    localAudioDebugRef.current.srcObject = stream;30  },31 32  onRemoteTrack: (track, stream) => {33    if (track.kind === 'audio') {34      audioElement.srcObject = stream;35      audioElement.play();36    }37  },38 39  onClientToolCall: (toolCall) => {40    // See "Client Tool Calls" section for full usage41    console.log('AI wants to:', toolCall.name, toolCall.arguments);42  }43});

1client.sendEvent('client_live_camera_started', { resolution: '720p' });2client.sendEvent('client_live_camera_stopped');

1import React, { useEffect, useState, useRef } from 'react';2import { VaniraClient } from '@vanira/sdk';3 4export function VoiceCallWidget() {5  const [status, setStatus] = useState<'idle' | 'connecting' | 'connected' | 'disconnected'>('idle');6  const [sessionInfo, setSessionInfo] = useState<{ callId: string; prospectId: string } | null>(null);7  const clientRef = useRef<VaniraClient | null>(null);8 9  const startCall = async () => {10    setStatus('connecting');11    12    clientRef.current = new VaniraClient({13      agentId: 'YOUR_AGENT_ID',14      apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY', // Browser-safe publishable key15      sessionBehavior: 'continue',           // Attempt to continue session on page load/refresh16      17      onSessionStarted: ({ callId, prospectId }) => {18        setSessionInfo({ callId, prospectId });19        console.log('Provisioned (Phase 1):', { callId, prospectId });20      },21      onConnected: () => {22        setStatus('connected');23      },24      onDisconnected: () => {25        setStatus('disconnected');26        setSessionInfo(null);27      },28      onError: (err) => {29        console.error('Call Error:', err);30        setStatus('idle');31      }32    });33 34    try {35      await clientRef.current.connect();36    } catch (e) {37      console.error('Failed to start call', e);38      setStatus('idle');39    }40  };41 42  const endCall = () => {43    if (clientRef.current) {44      clientRef.current.disconnect();45      clientRef.current = null;46    }47    setStatus('idle');48  };49 50  // Safe cleanup when component unmounts51  useEffect(() => {52    return () => {53      if (clientRef.current) {54        clientRef.current.disconnect();55      }56    };57  }, []);58 59  return (60    <div className="p-4 border rounded-lg bg-zinc-900 text-white">61      <p>Status: {status}</p>62      {sessionInfo && (63        <p className="text-xs text-zinc-400">Call ID: {sessionInfo.callId}</p>64      )}65      {status === 'connected' ? (66        <button onClick={endCall} className="bg-red-500 px-4 py-2 rounded">End Call</button>67      ) : (68        <button onClick={startCall} disabled={status === 'connecting'} className="bg-emerald-500 px-4 py-2 rounded">69          {status === 'connecting' ? 'Connecting...' : 'Start / Resume Call'}70        </button>71      )}72    </div>73  );74}

1// User navigated to a pricing page.2client.sendContextUpdate({3  active_page: '/dashboard/pricing',4  customer_tier: 'gold',5  last_viewed_item: 'Premium Plan'6});7 8// Map demo: user panned the map. Debounce this in production.9map.on('moveend', async () => {10  const center = map.getCenter();11  const placeName = await reverseGeocode(center.lat, center.lng);12 13  client.sendContextUpdate({14    active_map_location: placeName,15    user_action: 'panning_map'16  });17});18 19// Alias:20client.updateContext({21  active_page: '/checkout',22  cart_total: 149.9923});

1// VaniraClient: interrupt, then send the action.2client.triggerActionInterrupt();3client.sendActionTrigger('map_click', {4  location: 'Tokyo, Japan',5  prompt: 'User clicked on Tokyo. Tell them 2 interesting facts about Tokyo immediately.'6});7 8// Or use the combined alias:9client.triggerInterrupt('plan_selected', {10  plan: 'Enterprise',11  prompt: 'The user selected Enterprise. Explain the next onboarding step.'12});

1// Cut agent speech right before initiating a custom file upload flow2document.getElementById('upload-area').addEventListener('dragenter', () => {3  client.interruptAudioOnly();4});5 6// Or the lower-level interrupt:7client.triggerActionInterrupt();

1client.disconnect();2client = null;3 4// React cleanup5useEffect(() => {6  return () => {7    clientRef.current?.disconnect();8    clientRef.current = null;9  };10}, []);

1import { VaniraClient } from '@vanira/sdk';2 3let client: VaniraClient | null = null;4 5async function startCall() {6  client?.disconnect();7 8  client = new VaniraClient({9    agentId: 'YOUR_AGENT_ID',10    apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',11    onConnected: () => setStatus('connected'),12    onDisconnected: () => setStatus('idle'),13    onError: (error) => {14      console.error('Vanira call failed:', error);15      setStatus('error');16      client?.disconnect();17      client = null;18    },19  });20 21  setStatus('connecting');22  await client.connect();23}

1import { useEffect, useState } from 'react';2import { VaniraClient, PresetRenderer } from '@vanira/sdk';3 4function App() {5  const [client] = useState(() => new VaniraClient({ 6    agentId: 'YOUR_AGENT_ID',7    apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',8    sessionBehavior: 'continue'9  }));10 11  // 1. Initialize activeToolCall from sessionStorage if it exists12  const [activeToolCall, setActiveToolCall] = useState(() => {13    const saved = sessionStorage.getItem('vanira_active_preset');14    return saved ? JSON.parse(saved) : null;15  });16 17  useEffect(() => {18    client.on('tool_call', (toolCall) => {19      // 2. Cache the active tool call in sessionStorage20      sessionStorage.setItem('vanira_active_preset', JSON.stringify(toolCall));21      setActiveToolCall(toolCall);22    });23    24    client.start();25    return () => client.stop();26  }, [client]);27 28  const clearPreset = () => {29    // 3. Clear when your flow is complete, or when the user dismisses your restored UI30    sessionStorage.removeItem('vanira_active_preset');31    setActiveToolCall(null);32  };33 34  return (35    <div>36      <MainDashboard />37 38      {activeToolCall && (39        <button onClick={clearPreset}>Clear restored preset</button>40      )}41 42      {activeToolCall && (43        <PresetRenderer44          client={client}45          toolCall={activeToolCall}46        />47      )}48    </div>49  );50}

1import { VaniraClient } from '@vanira/sdk';2 3let client: VaniraClient | null = null;4 5async function startMapSession(agentId: string) {6  // agentId + apiKey: the SDK handles call creation and WebRTC setup.7  client = new VaniraClient({8    agentId,9    apiKey: 'pk_live_YOUR_PUBLISHABLE_KEY',10    onConnected:     () => setStatus('connected'),11    onDisconnected:  () => setStatus('idle'),12    onTranscription: (text, isFinal) => updateTranscript(text, isFinal),13 14    // AI to UI: agent wants to show a location on the map.15    onClientToolCall: (toolCall) => {16      if (toolCall.name === 'show_location_map') {17        geocode(toolCall.arguments.query).then(success => {18          if (toolCall.execution_mode === 'blocking') {19            client?.sendToolResult(toolCall.tool_call_id, { success });20          }21        });22      }23    }24  });25 26  await client.connect(); // pre-flight + WebRTC handled internally27 28  // 3. UI to AI (silent): sync map viewport to agent every second after pan.29  map.on('moveend', debounce(async () => {30    const place = await reverseGeocode(map.getCenter());31    client?.sendContextUpdate({ active_map_location: place, user_action: 'panning' });32  }, 1000));33 34  // 4. UI to AI (interrupt): map click forces immediate AI response.35  map.on('click', async (e) => {36    const place = await reverseGeocode(e.latlng);37    client?.triggerActionInterrupt();38    client?.sendActionTrigger('map_click', {39      location: place,40      prompt: `User clicked ${place}. Tell them 2 facts about it immediately.`41    });42  });43}

1import React, { useRef, useState } from 'react';2import { VaniraClient } from '@vanira/sdk';3 4interface UploadProps {5  client: VaniraClient | null;6}7 8export function VisionUploadButton({ client }: UploadProps) {9  const [isUploading, setIsUploading] = useState(false);10  const fileInputRef = useRef<HTMLInputElement>(null);11 12  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {13    const file = e.target.files?.[0];14    if (!file || !client) return;15 16    try {17      setIsUploading(true);18      19      // Upload the document and let the media pipeline notify the AI.20      const response = await client.uploadMedia(21        file,22        'kyc_verification', // Routing reason23        'Please review this document and tell me if my name matches.' // Message context24      );25      26      console.log('Media uploaded successfully:', response.url);27    } catch (error) {28      console.error('Failed to upload vision context:', error);29    } finally {30      setIsUploading(false);31      if (fileInputRef.current) fileInputRef.current.value = ''; // Reset input32    }33  };34 35  return (36    <div className="flex items-center gap-2">37      <input38        type="file"39        ref={fileInputRef}40        onChange={handleFileChange}41        accept="image/*,application/pdf"42        className="hidden"43      />44      <button45        disabled={isUploading || !client}46        onClick={() => fileInputRef.current?.click()}47        className="px-4 py-2 text-sm bg-white text-black font-semibold rounded-lg hover:bg-zinc-200 disabled:opacity-50 disabled:cursor-not-allowed"48      >49        {isUploading ? 'Uploading...' : 'Upload Image / PDF'}50      </button>51    </div>52  );53}

1{2  "interrupt": true,3  "result_text": "OCR Result: PAN Card verified. Name: Jane Doe. PAN: ABCDE1234F."4}

1const express = require('express');2const multer = require('multer');3const upload = multer({ limits: { fileSize: 50 * 1024 * 1024 } }); // 50MB limit4 5const app = express();6 7app.post('/api/vanira-media-webhook', upload.single('media'), async (req, res) => {8  try {9    const file = req.file; // The uploaded file buffer and metadata10    const { reason, message, session_id } = req.body;11 12    console.log(`Processing media for call ${session_id}. Reason: ${reason}`);13 14    let processedTextResult = '';15 16    if (reason === 'kyc_verification') {17      // 1. Call your KYC verification pipeline or OCR service18      // const kycResult = await verifyDocument(file.buffer);19      processedTextResult = 'Document verified successfully. Name: Jane Doe.';20    } else {21      processedTextResult = 'Generic document received. Please ask the user to clarify.';22    }23 24    // 2. Return the expected payload to Vanira25    return res.status(200).json({26      interrupt: true, // Cut off agent's speech to process this event instantly27      result_text: processedTextResult28    });29 30  } catch (error) {31    console.error('Webhook processing failure:', error);32    return res.status(500).json({33      interrupt: false,34      result_text: 'Failed to process document due to a server error.'35    });36  }37});38 39app.listen(3000, () => console.log('Media Webhook active on port 3000'));