elevenlabs_flutter_sdk #

Flutter plugin for ElevenLabs conversational agents on Android and iOS.

This package provides a unified Dart API over native ElevenLabs SDKs, including:

• session start/end
• voice controls (mute/unmute)
• text messaging and contextual updates
• feedback signaling
• native events as Dart streams

Features #

• Public and private session startup:
  • public agent via agentId
  • private agent via backend-issued conversationToken
• Event stream support:
  • connection, status, mode, messages, VAD, audio alignment, tool calls
• Convenience API in Dart:
  • startPublicSession(...), startPrivateSession(...)
• Works on:
  • Android
  • iOS

Installation #

Add the package:

dependencies:
  elevenlabs_flutter_sdk: ^0.0.1

Then run:

flutter pub get

Platform Setup #

Android #

Add microphone permission to your Android app manifest:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

Request runtime microphone permission in your Flutter app before startSession(...).

iOS #

1. Set deployment target to iOS 13.0+.
2. Add microphone usage description to ios/Runner/Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for voice conversations.</string>

3. Add the ElevenLabs Swift SDK package to your app target in Xcode:
   • URL: https://github.com/elevenlabs/elevenlabs-swift-sdk.git
   • Version: 2.0.0 or newer

Reference docs: ElevenLabs Swift SDK

Quick Start #

import 'package:elevenlabs_flutter_sdk/elevenlabs_flutter_sdk.dart';

final sdk = ElevenlabsFlutterSdk();

// Public agent session
await sdk.startPublicSession(
  agentId: 'your_public_agent_id',
  userId: 'user_123',
);

// Send text message
await sdk.sendUserMessage('Hello!');

// End session
await sdk.endSession();

Private Agent Session #

Never ship ElevenLabs API keys in the app. Generate a temporary conversation token on your backend, then use:

await sdk.startPrivateSession(
  conversationToken: tokenFromBackend,
  userId: 'user_123',
);

API #

Session #

• startSession({String? agentId, String? conversationToken, String? userId})
• startPublicSession({required String agentId, String? userId})
• startPrivateSession({required String conversationToken, String? userId})
• endSession()

Messaging and Context #

• sendUserMessage(String message)
• sendContextualUpdate(String context)
• sendUserActivity()

Feedback #

• sendFeedback(bool isPositive)

Audio and Status #

• toggleMute()
• setMicMuted(bool muted)
• isMuted()
• getStatus()
• getConversationId()

Events #

Raw broadcast stream:

• events (Stream<Map<String, dynamic>>)

Convenience streams:

• onConnect
• onMessage
• onModeChange
• onStatusChange
• onCanSendFeedbackChange
• onUnhandledClientToolCall
• onVadScore
• onAudioAlignment

Example listener:

final sub = sdk.onStatusChange.listen((status) {
  debugPrint('Status: $status');
});

Permissions Guidance #

This package does not manage UI permission prompts for you. Use a package like permission_handler in your app:

• request microphone before starting a session
• if permanently denied, prompt users to open app settings

Security #

• For private agents, use conversationToken from your backend.
• Do not store ElevenLabs API keys in client applications.

Known Notes #

• iOS Local Network permission warnings in debug builds can come from Flutter VM service publishing and are usually unrelated to ElevenLabs session auth.
• Audio session behavior can vary by simulator/device and OS version.