ringg_flutter 0.1.3

Ringg AI widget for Flutter — drop-in widget and headless controller for voice/text AI agents.

ringg_flutter

⚠️ Alpha / pre-release. This package is early and under active development — expect rough edges, occasional bugs, and breaking changes between versions. Pin an exact version if you need stability, and please report anything you hit. See Known issues below.

Embeddable chat + voice-call widget for Ringg AI agents — the Flutter implementation. Drop RinggWidget over your app for text chat, voice calls, interactive components (forms, calendars, quick replies, Block Kit) and a post-call feedback screen.

Install

dependencies:
  ringg_flutter: ^0.1.3

Then flutter pub get. Requires Dart ≥ 3.6 · Flutter ≥ 3.27.

Platform setup (required for voice)

Voice calls need microphone + audio permissions.

iOS — ios/Runner/Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>Voice calls use the microphone.</string>
<key>UIBackgroundModes</key>
<array><string>audio</string></array>

Android — android/app/src/main/AndroidManifest.xml:

<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" />

Integrate in 3 steps

Create a transport, build a controller with your agent config, then mount the widget. Hold the transport + controller in a State so you can dispose them.

1 · Get your credentials

From the Ringg dashboard you need: your agent id, a bearer authorization token, and the environment URLs for your account.

2 · Wire up a controller + widget

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

class RinggSupport extends StatefulWidget {
  const RinggSupport({super.key});

  @override
  State<RinggSupport> createState() => _RinggSupportState();
}

class _RinggSupportState extends State<RinggSupport> {
  late final LiveKitTransport _transport;
  late final RinggWidgetController _controller;

  // Environment URLs for your account (from the Ringg dashboard).
  static const _urls = <EnvironmentMode, EnvironmentUrls>{
    EnvironmentMode.prod: EnvironmentUrls(
      backendUrl: 'https://<your-backend-host>/ca/api/v0',
      livekitUrl: 'wss://<your-realtime-host>',
    ),
  };

  @override
  void initState() {
    super.initState();
    _transport = createLiveKitTransport();
    _controller = RinggWidgetController(
      const RinggWidgetConfig(
        agentId: '<your-agent-id>',
        authorization: 'Bearer <your-token>',
        mode: EnvironmentMode.prod,     // selects the URL set above
        title: 'Support',
        description: 'How can we help?',
        defaultTab: MediaType.text,     // or MediaType.voice
      ),
      ControllerPorts(
        transport: _transport.transport,
        urlResolver: const StaticUrlResolver(_urls),
      ),
    );
  }

  @override
  void dispose() {
    _controller.destroy();
    _transport.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => RinggWidget(
        controller: _controller,
        transport: _transport, // enables the in-call audio visualizer
      );
}

3 · Mount it over your app

RinggWidget places its own floating trigger + panel, so give it the full screen on top of your content:

Stack(
  children: const [
    YourApp(),
    RinggSupport(),
  ],
)

Tap the trigger → the chat/voice panel opens. That's the whole integration.

Native platforms & the Origin header. Browsers attach an Origin header automatically; native HTTP does not. If your Ringg backend allow-lists keys by domain, the webcall request will fail without it. Pass an httpClient (from package:http) that stamps the origin your key accepts:

ControllerPorts(
  transport: _transport.transport,
  urlResolver: const StaticUrlResolver(_urls),
  httpClient: _originClient('https://your-allowed-origin'),
);
// _originClient wraps http.Client and sets request.headers['Origin'].
// A ready-made version ships in the example (example/lib/origin_client.dart).

Configuration

RinggWidgetConfig — only agentId is required; everything else is optional:

Field	Type	Purpose
agentId	String	your Ringg agent (required)
authorization	String?	bearer token for your account
mode	EnvironmentMode?	dev / stage / prod — picks the URL set
title / description	String?	panel header text
defaultTab	MediaType?	open in text or voice
hideTabSelector	bool?	hide the text/voice switch
defaultExpanded	bool?	open the panel on load
bypassStartScreen	bool?	jump straight into a call
variables	Map<String, Object>?	values for {{placeholders}} in agent prompts
logoUrl / theme / widgetPosition / legalDisclaimer / buttons	…	branding, placement & styling

Example app

A runnable example ships in the Example tab (the example/ directory) — see its README.md for how to run it.

Platform support

Android · iOS · macOS · Windows · Linux. Web is not supported.

Known issues

This is an alpha — here's what to watch for:

• Breaking changes between releases. APIs may shift while pre-1.0; pin an exact version if you need stability.
• iOS simulators (26.x) have no call audio. The simulator exposes no mic or playout device, so you won't hear the agent or be able to unmute — an OS-simulator + upstream realtime-SDK limitation, not fixable app-side. The widget degrades to a listen-only attempt. Test voice on a real device, an Android emulator, or macOS. (Apple refs: forums 738346, 803364.)
• Voice on Android emulators can fail to connect. Emulator networking often can't establish the media connection; text chat works, but voice needs a real device.
• Expect bugs. If something misbehaves, please file an issue with repro steps.