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>
  1. 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.

Libraries

elevenlabs_flutter_sdk
elevenlabs_flutter_sdk_method_channel
elevenlabs_flutter_sdk_platform_interface