Flutter SDK

dependencies:
  vaani_flutter_sdk:
    git:
      url: https://github.com/VaaniResearchLab/vaani-flutter-sdk.git
      ref: main

dependencies:
  vaani_flutter_sdk:
    path: ../vaani-flutter-sdk

<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) uses the microphone to talk to the voice assistant.</string>
<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
</array>

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />

import 'package:vaani_flutter_sdk/vaani_flutter_sdk.dart';

final client = VaaniClient(apiKey: 'vaani_...');

final client = VaaniClient(apiKey: 'vaani_...');
try {
  final health = await client.health();
  print(health.status);  // "healthy"
} finally {
  client.close();
}

import 'package:vaani_flutter_sdk/vaani_flutter_sdk.dart';

final session = VaaniVoiceSession.withApiKey(
  apiKey: 'vaani_...',
  agentId: 'd62cc9bd-2f51-4581-9f38-6c3b7d58a988',
  dispatchOptions: const WebRtcDispatchOptions(
    primaryLanguage: 'en',
    welcomeMessage: 'Hi! How can I help you today?',
  ),
);

// idle -> dispatching -> connecting -> waitingForAgent -> active
session.addListener(() => print(session.state));

// Subscribe before start() so you don't miss the greeting
session.transcripts.listen(
  (t) => print('${t.fromAgent ? "agent" : "me"}: ${t.text}'),
);

await session.start();    // dispatch + join room + enable mic
print(session.roomName);  // room the agent was dispatched into, e.g. "webrtc-1794481532-5effcd48"

await session.setMicrophoneEnabled(false);  // mute
await session.end();                        // leave the room
await session.dispose();                    // always call

ListenableBuilder(
  listenable: session,
  builder: (context, _) => switch (session.state) {
    VaaniVoiceSessionState.idle => const Text('Tap to talk'),
    VaaniVoiceSessionState.dispatching ||
    VaaniVoiceSessionState.connecting => const Text('Connecting…'),
    VaaniVoiceSessionState.waitingForAgent => const Text('Waiting for the assistant…'),
    VaaniVoiceSessionState.active =>
      Text(session.isAgentSpeaking ? 'Agent is speaking' : 'Listening'),
    VaaniVoiceSessionState.reconnecting => const Text('Reconnecting…'),
    VaaniVoiceSessionState.ended => const Text('Call ended'),
    VaaniVoiceSessionState.failed => Text('Error: ${session.error}'),
  },
);

// Development: API key in the app
VaaniVoiceSession.withApiKey(apiKey: key, agentId: agentId);

// Production: credentials from your backend (or any provider)
VaaniVoiceSession(credentialsProvider: myProvider);

await session.start();                 // throws on dispatch or connection failure
await session.end();                   // leave the room and release the dispatch
await session.end(explicitEnd: false); // session flow: keep the reconnection grace period
await session.dispose();               // always call; ends the call if it is still running

await session.setMicrophoneEnabled(false); // mute
await session.setMicrophoneEnabled(true);  // unmute (re-applies audioOptions)

final lines = <String, VaaniTranscript>{};

session.transcripts.listen((t) {
  lines[t.segmentId] = t;  // interim updates replace earlier text for the same segment
  setState(() {});
});

VaaniVoiceSession.withApiKey(
  apiKey: key,
  agentId: agentId,
  dispatchOptions: const WebRtcDispatchOptions(
    primaryLanguage: 'en',
    secondaryLanguage: 'hi',
    voiceGender: VaaniVoiceGender.female,
    welcomeMessage: 'Hi! How can I help?',
    welcomeInterruptible: true,
    voiceSpeed: 1.1,
    bgNoiseEnabled: false,
    metadata: {'user_id': 'u_123'},
    modifyAgent: ModifyAgentConfig(
      persona: {'identity': {'system_prompt': 'Keep answers under two sentences.'}},
    ),
  ),
);

final session = VaaniVoiceSession.withApiKey(
  apiKey: key,
  agentId: agentId,
  useSessionFlow: true,
  gracePeriod: const Duration(minutes: 1),   // reconnection window, 0–3600 s
  sessionTtl: const Duration(minutes: 30),   // lifetime, 60–86400 s
  initialMessage: 'User is asking about order #1234',
  sessionMetadata: {'user_id': 'user_123', 'ticket_id': 'T-1234'},
);

final client = VaaniClient(apiKey: key);
final session = VaaniVoiceSession(
  credentialsProvider: SessionCredentialsProvider(
    client: client,
    agentId: agentId,
    uiType: VaaniUiType.widget,
    gracePeriod: const Duration(minutes: 1),
  ),
);
// You own this client: call client.close() after session.dispose().

session.sessionEvents.listen((e) {
  if (e.isAgentReady) print('Agent has joined the room');
  if (e.isAgentTimeout) print('Agent failed to join: ${e.raw['reason']}');
  if (e.isSessionEnded) print('Session ended: ${e.raw['reason']}');
  print(e.type);  // event name
  print(e.raw);   // full payload
});

import os
from fastapi import FastAPI, Depends
from vaani_sdk import AsyncVaaniClient

app = FastAPI()
vaani = AsyncVaaniClient(api_key=os.environ["VAANI_API_KEY"])

@app.post("/voice/start")
async def start_voice(user=Depends(current_user)):   # your auth
    r = await vaani.trigger_call(
        agent_id=os.environ["VAANI_AGENT_ID"],
        medium="webrtc",
        primary_language="en",
        metadata={"user_id": user.id},
    )
    return {"connection_url": r.connection_url, "token": r.token, "room_name": r.room_name}

final session = VaaniVoiceSession(
  credentialsProvider: VaaniCredentialsProvider.custom(() async {
    final res = await myApi.post('/voice/start'); // your server calls Vaani
    return VaaniRoomCredentials(
      serverUrl: res['connection_url'],
      participantToken: res['token'],
      roomName: res['room_name'],
    );
  }),
);

class MyBackendProvider extends VaaniCredentialsProvider {
  @override
  Future<VaaniRoomCredentials> fetchCredentials() async {
    final res = await myApi.post('/voice/start');
    return VaaniRoomCredentials(
      serverUrl: res['lk_url'],
      participantToken: res['lk_token'],
      roomName: res['room_name'],
      sessionToken: res['session_token'],
    );
  }

  @override
  Future<void> release(VaaniRoomCredentials c, {required bool explicitEnd}) =>
      myApi.post('/voice/end', {'session_token': c.sessionToken, 'explicit_end': explicitEnd});
}

VaaniVoiceSession.withApiKey(
  apiKey: key,
  agentId: agentId,
  audioOptions: const VaaniAudioOptions(
    // Some Android phones have a weak built-in echo canceller. If the agent
    // hears itself on speakerphone, force WebRTC's software one:
    echoCancellationMode: VaaniAudioProcessing.software,
  ),
);

final client = VaaniClient(apiKey: 'vaani_...');

// Room credentials, ready to join
final creds = await client.dispatchWebRtc(
  agentId: id,
  options: const WebRtcDispatchOptions(primaryLanguage: 'en'),
);
print(creds.roomName);

// Or the full API response
final r = await client.triggerWebRtcCall(agentId: id);
print(r.token);            // participant JWT
print(r.connectionUrl);    // wss://...
print(r.liveCaptionsUrl);  // signed live-captions URL
print(r.raw);              // full response body

final call = await client.triggerTelephonyCall(
  agentId: '8cf3373e-eb6f-4b4c-9f3c-324a56a91147',
  options: const TelephonyCallOptions(
    contactNumber: '+919876543210',
    name: 'Rahul Sharma',
    metadata: {'customer_name': 'Rahul Sharma', 'property_name': 'Prateek Laurel'},
  ),
);
print(call.callId);           // "outbound-1776774443-863aa698"
print(call.liveCaptionsUrl);  // signed Server-Sent Events URL

// Create
final s = await client.sessions.create(
  agentId: id,
  uiType: VaaniUiType.widget,
  gracePeriod: const Duration(minutes: 1),
  sessionTtl: const Duration(minutes: 30),
  initialMessage: 'User is asking about order #1234',
  metadata: {'user_id': 'user_123'},
);
print(s.sessionToken);  // session JWT
print(s.sessionUrl);    // shareable URL for Vaani's hosted UI
print(s.expiresAt);

// Exchange the token for room credentials (dispatches the agent)
final conn = await client.sessions.connect(s.sessionToken);
print(conn.lkUrl);     // "wss://<your-host>"
print(conn.lkToken);   // participant JWT
print(conn.roomName);

// Check status
final status = await client.sessions.get(s.sessionToken);
print(status.status);  // "created" | "agent_ready" | "active" | "reconnecting"
// Once a session has ended or expired, this throws VaaniSessionExpiredException (410)

// Events
final sub = client.sessions.events(s.sessionToken).listen(print);
print(client.sessions.wsUrl(s.sessionToken));  // wss://.../api/webrtc/session/ws/<token>

// End
await client.sessions.disconnect(s.sessionToken);                    // starts the grace period
await client.sessions.disconnect(s.sessionToken, explicitEnd: true); // ends immediately

await sub.cancel();  // closes the socket
client.close();

final data = await client.request('GET', '/api/health');

try {
  await session.start();
} on VaaniAuthenticationException {
  print('Invalid API key');
} on VaaniInsufficientBalanceException {
  print('Wallet balance is too low');
} on VaaniNotFoundException {
  print('Agent not found');
} on VaaniAgentTimeoutException {
  print('Agent did not join in time');
} on VaaniException catch (e) {
  print('API error ${e.statusCode}: ${e.message}');
}

import os
import time
from vaani_sdk import VaaniClient

with VaaniClient(api_key=os.environ["VAANI_API_KEY"]) as client:
    transcript = client.get_transcript(room_name)    # room_name sent by the app
    print(transcript.transcript)

    details = client.get_call_details(room_name)
    while details.is_processing:                     # post-call processing still running
        time.sleep(details.retry_after or 5)
        details = client.get_call_details(room_name)
    print(details.raw.get("summary"))