Skip to main content

truhuddle_widget 1.0.0 copy "truhuddle_widget: ^1.0.0" to clipboard
truhuddle_widget: ^1.0.0 copied to clipboard

Native TruHuddle customer support for Flutter with live messaging, AI agents, voice notes and workspace-controlled permissions.

TruHuddle Widget for Flutter #

Native Android and iOS support, opened from your app's own button as a full-screen page. Home, Messages and Profile follow the TruHuddle web widget, including its League Spartan font, Hugeicons, brand gradient, compact messages and voice waves. This package does not use a WebView and does not add a floating launcher.

Install #

Requires Flutter 3.41 / Dart 3.11 or newer.

dependencies:
  truhuddle_widget: ^1.0.0

Create a session on your backend #

Native integration is available on Startup and Enterprise. Add your Android package / iOS bundle identifier in Widget settings. Your backend, not your app, authenticates the customer and chooses their stable ID, name and verified email.

// Server only: npm install @retinalabsllc/truhuddle-widget
import { createServerClient } from '@retinalabsllc/truhuddle-widget/server';
const support = createServerClient({
  publicKey: process.env.SDK_PUBLIC_KEY!,
  secretKey: process.env.SDK_SECRET_KEY!,
});
const session = await support.createWidgetSession({
  packageName: 'com.example.app',
  user: { id: signedInUser.id, name: signedInUser.name, email: signedInUser.email },
});
// Return session to this authenticated customer only. Cache-Control: private, no-store.

Protect this endpoint using your existing app login. Never accept an unchecked customer ID from the request body. A package allowlist is an integration label, not proof that an installed app is genuine; verify app attestation on your own backend when appropriate. Neither developer key belongs in a mobile binary.

Open support #

import 'package:truhuddle_widget/truhuddle_widget.dart';

await TruhuddleWidget.open(context, options: TruhuddleOptions(
  appId: 'YOUR_PUBLIC_APP_ID',
  packageName: 'com.example.app',
  getSession: () async {
    final sessionJson = await yourSignedInApi.createSupportSession();
    return TruhuddleSession.fromJson(sessionJson);
  },
));

You can also push TruhuddleWidget(options: options) through your existing Navigator. For direct widget mounting, use a Flutter key tied to the signed-in customer ID. Pop/unmount the page on logout or customer changes. The session provider must always return the current, same authenticated customer's session for this page. Verified sessions expire after 15 minutes; the package renews through this callback and never falls back to anonymous identity on failure. Session tokens stay in memory, never in URLs, logs or persistent storage.

Platform permissions #

Android (android/app/src/main/AndroidManifest.xml):

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

Use Android API 24 or newer. Microphone permission is requested only after the customer taps the enabled record button. Gallery images use the platform picker.

iOS (ios/Runner/Info.plist), with iOS 13 or newer:

<key>NSMicrophoneUsageDescription</key>
<string>Record voice notes for your support conversation.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Share a photo with your support team.</string>

Do not enable cleartext HTTP or disable TLS validation for production. baseUrl accepts HTTPS service origins; local HTTP is limited to loopback / Android emulator addresses for development. The package targets Android and iOS, not Flutter Web.

Workspace-controlled behavior #

  • Widget enabled/disabled state, plan checks, bans, tenant isolation and native package permissions are enforced by the server on every API request.
  • Workspace light/dark/system theme, color, greeting, logo and branding are used.
  • The supported attachment audience controls image and voice-note buttons. Uploads and downloads use authorized customer endpoints and private workspace storage.
  • AI badges follow the workspace switch. Internal team notes are never returned.
  • Customer lists show up to 20 recent conversations; history is bounded to the most recent 100 messages, loaded in 11-message pages. Older pages load on demand.
  • New replies follow the scroll only when already near the bottom. Otherwise a floating count lets the customer jump to the new messages.
  • Name/email passed by the developer remain read-only. No agent last-seen timestamp is exposed to the customer. The support header shows connected/available status.
  • Sound and in-app message notice switches apply to the current page. They do not request OS push-notification permission or provide background push delivery.

Voice notes and images #

Voice recordings use AAC in an MP4/M4A container, capped at 90 seconds. Playback uses decoded audio waveforms and position-based highlighting, with seeking. Private recordings are downloaded only when played and temporary files are removed when their player/page is disposed. Supported playback codecs depend on the device OS; an unsupported recording shows an error rather than a fake player. Images open in an in-app full-screen zoomable preview. Select a supported image under 4 MB; recordings must be below 8 MB. The backend independently checks size, file signatures, plan, permissions and conversation ownership.

Live updates #

The page requests a short-lived, customer-scoped edge ticket, then connects to the Cloudflare WebSocket with the ticket in the subprotocol, not the URL. Events carry invalidation IDs; the actual messages are fetched from the authenticated API. After a disconnect or app resume, the page renews access and reloads authorized state. The API also supports an SSE fallback. App inactivity stops the live stream and recordings; five-minute activity heartbeats expire visitor presence.

Example and publishing #

example/lib/main.dart shows the complete button integration with a backend session callback. To run it as a standalone example, generate its platform shells with cd example && flutter create --platforms=android,ios ., then add the platform permissions above before running it. Use your app's normal authentication there, never developer keys.

From packages/truhuddle_widget:

flutter pub get
flutter pub publish

Publishing is a manual action. Review the listed files and confirm the upload in your terminal. The npm package is published separately from packages/truhuddle-widget with npm publish --access public --registry=https://registry.npmjs.org/.

League Spartan is included under its bundled SIL Open Font License in assets/fonts/OFL.txt; package source is MIT licensed.

0
likes
0
points
1.14k
downloads

Publisher

unverified uploader

Weekly Downloads

Native TruHuddle customer support for Flutter with live messaging, AI agents, voice notes and workspace-controlled permissions.

Homepage
Repository (GitHub)
View/report issues

Funding

Consider supporting this project:

truhuddle.com

License

unknown (license)

Dependencies

audio_waveforms, flutter, http, hugeicons, image_picker, path_provider, url_launcher, uuid

More

Packages that depend on truhuddle_widget