flutter_telnyx_voice_ai_widget 1.1.0

Flutter Voice AI Embeddable Widget

Flutter Telnyx Voice AI Widget

A Flutter widget that provides a standalone voice AI assistant interface using the Telnyx WebRTC SDK.

Features

• Configurable Dimensions: Set custom height and width for the widget
• Icon-Only Mode: Floating action button-style interface for minimal UI footprint
• Multiple UI States:
  • Collapsed (initial state)
  • Connecting (during call setup)
  • Expanded (active call with audio visualizer)
  • Conversation (full transcript view)
• Agent Status Indicators: Shows when the agent is thinking or waiting for interruption
• Audio Visualizer: Animated bars that respond to call activity
• Theme Support: Light and dark theme configurations
• Call Controls: Mute/unmute and end call functionality
• Conversation View: Full transcript with message history
• Responsive Design: Adapts to different screen sizes
• Custom Call Parameters: Configure caller name, number, destination, and client state

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_telnyx_voice_ai_widget:
    git:
      url: https://github.com/team-telnyx/flutter-telnyx-voice-ai-widget.git
      ref: main

Usage

Basic Usage

Regular Mode

import 'package:flutter/material.dart';
import 'package:flutter_telnyx_voice_ai_widget/flutter_telnyx_voice_ai_widget.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: TelnyxVoiceAiWidget(
            height: 60,
            width: 300,
            assistantId: 'your-assistant-id',
          ),
        ),
      ),
    );
  }
}

Icon-Only Mode

import 'package:flutter/material.dart';
import 'package:flutter_telnyx_voice_ai_widget/flutter_telnyx_voice_ai_widget.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        floatingActionButton: TelnyxVoiceAiWidget(
          assistantId: 'your-assistant-id',
          iconOnlySettings: IconOnlySettings(
            size: 56.0,
            logoIconSettings: LogoIconSettings(
              size: 40.0,
              borderRadius: 20.0,
            ),
          ),
        ),
      ),
    );
  }
}

Widget Parameters

Regular Mode Parameters

• height (required for regular mode): The height of the widget in its collapsed state
• width (required for regular mode): The width of the widget
• assistantId (required): The ID of the AI assistant to connect to
• expandedHeight (optional): The height of the widget in its expanded state
• expandedWidth (optional): The width of the widget in its expanded state
• startCallTextStyling (optional): Text styling for the start call text in collapsed state
• logoIconSettings (optional): Settings for customizing the logo/avatar icon
• widgetSettingOverride (optional): Widget settings override

Icon-Only Mode Parameters

• assistantId (required): The ID of the AI assistant to connect to
• iconOnlySettings (required for icon-only mode): Configuration for icon-only mode
  • size (required): Size of the circular icon widget
  • logoIconSettings (optional): Settings for customizing the logo/avatar icon
  • widgetSettingOverride (optional): Widget settings override

Call Parameters

Note that these are primarily used for logging and call referencing except in the case of custom headers - which can be used to pass dynamic variables to your assistant. The call will always be routed to the AI assistant after anonymous login.

• callParams (optional): Custom parameters for call initialization
  • callerName (optional): The caller name to display (defaults to 'AI Assistant User')
  • callerNumber (optional): The caller number to use (defaults to 'anonymous')
  • destinationNumber (optional): The destination number to call (defaults to 'xxx')
  • clientState (optional): Custom client state data (defaults to empty string)
  • customHeaders (optional): Custom headers to include with the call

Note that you can also provide customHeaders in the newInvite method. These headers need to start with the X- prefix and will be mapped to dynamic variables in the AI assistant (e.g., X-Account-Number becomes {{account_number}}). Hyphens in header names are converted to underscores in variable names.

TelnyxVoiceAiWidget(
  assistantId: 'your-assistant-id',
  height: 60,
  width: 200,
  callParams: const CallParams(
    callerName: 'John Doe',
    callerNumber: '[phone]',
    destinationNumber: '+0987654321',
    clientState: 'custom-client-state-data',
    customHeaders: {
      'X-Custom-Header': 'custom-value',
      'X-User-ID': 'user-123',
    },
  ),
)

For the customHeaders here, the variables will be available in the portal settings for the AI assistant as {{custom_header}} and {{user_id}}.

Widget States

Regular Mode States

The widget automatically transitions between different states:

1. Loading: Shows a loading indicator while initializing
2. Collapsed: Initial state with assistant avatar and call-to-action text
3. Connecting: Shows loading while establishing the call
4. Expanded: Active call state with audio visualizer and controls
5. Conversation: Full transcript view with message history
6. Error: Error state if something goes wrong

Icon-Only Mode Behavior

In icon-only mode, the widget behavior is simplified:

1. Loading: Shows a loading indicator in circular form
2. Normal State: Shows the icon in a circular container with theme-based background
3. Connecting State: Shows a loading indicator while establishing the call connection
4. Error State: Shows a red warning icon in a circular container
5. Call Flow: Tapping the icon shows a loading indicator until the call is answered, then opens the conversation overlay
6. Error Handling: Tapping the error icon opens an error dialog instead of an overlay

Theming

The widget supports light and dark themes that are automatically applied based on the assistant configuration:

// Themes are automatically applied based on widget settings
// Light theme: Clean white background with blue accents
// Dark theme: Dark background with purple accents

Audio Visualizer

The widget includes an animated audio visualizer that:

• Shows activity during active calls
• Supports different color schemes (verdant, blue, purple, red)
• Uses rounded bars preset for a modern look
• Responds to call audio activity

Agent Status

The widget displays different agent statuses:

• Thinking: Agent is processing user input
• Waiting: Agent is speaking and can be interrupted
• Idle: Agent is not active

Example

See the example/ directory for a complete example app that demonstrates:

• Multiple widget sizes
• Different configurations
• Interactive assistant ID input
• Usage instructions

To run the example:

cd example
flutter run

Integration with Telnyx WebRTC SDK

This widget integrates with the Telnyx WebRTC SDK to provide:

• Anonymous login with assistant ID
• WebRTC call management
• Real-time transcript handling
• Audio controls (mute/unmute)
• Call state management

Requirements

• Flutter SDK 3.7.2 or higher
• Dart SDK 3.0.0 or higher
• Telnyx WebRTC SDK access

Development

Project Structure

lib/
├── src/
│   ├── models/
│   │   ├── agent_status.dart        # Agent status enum (idle, thinking, waiting)
│   │   ├── widget_state.dart        # Widget state enum
│   │   ├── widget_theme.dart        # Theme configuration (light/dark)
│   │   ├── logo_icon_settings.dart  # Logo/avatar customization settings
│   │   └── icon_only_settings.dart  # Icon-only mode configuration
│   ├── services/
│   │   └── widget_service.dart      # Main service for Telnyx WebRTC integration
│   ├── widgets/
│   │   ├── audio_visualizer.dart    # Animated audio visualizer with gradients
│   │   ├── avatar_widget.dart       # Reusable avatar display component
│   │   ├── collapsed_widget.dart    # Regular mode collapsed state
│   │   ├── compact_call_widget.dart # Compact call controls for conversation view
│   │   ├── connecting_widget.dart   # Connection loading state
│   │   ├── control_button.dart      # Reusable control button component
│   │   ├── conversation_view.dart   # Full transcript view with compact controls
│   │   ├── error_display_widget.dart # Error state display
│   │   ├── expanded_widget.dart     # Regular mode expanded state with visualizer
│   │   ├── icon_only_widget.dart    # Icon-only mode implementation
│   │   ├── loading_widget.dart      # Initial loading state
│   │   └── message_content.dart     # Message bubble content renderer
│   └── telnyx_voice_ai_widget.dart  # Main widget controller
└── flutter_telnyx_voice_ai_widget.dart # Public API exports

Key Components

Regular Mode Flow

1. LoadingWidget: Shows loading indicator during initialization
2. CollapsedWidget: Displays avatar and call-to-action text
3. ConnectingWidget: Shows connection progress
4. ExpandedWidget: Active call with audio visualizer and controls
5. ConversationView: Full transcript with CompactCallWidget header

Icon-Only Mode Flow

1. IconOnlyWidget: Circular FAB-style button
2. On tap: Shows loading indicator
3. On connect: Opens full-screen conversation overlay
4. On error: Shows red warning icon, tap for error dialog

Conversation View Features

• CompactCallWidget: Horizontal header with close button, mini visualizer, status text, and call controls
• Transcript Display: Scrollable message history with user/assistant bubbles
• Message Input: Text field for sending messages during conversation
• Auto-scroll: Automatically scrolls to latest messages

Building

flutter packages get
flutter analyze
flutter test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions, please contact the Telnyx development team or create an issue in the repository.