zorvia_messenger 0.0.4

Official Flutter SDK for Zorvia Messenger, embed a fully-featured live chat widget into any Flutter app with a single method call.

Zorvia Messenger: Flutter SDK

Zorvia Messenger is the official Flutter SDK for adding live customer support to your app. It renders the chat widget as a modal bottom sheet and manages configuration, sessions, conversations, uploads, and real-time updates for you.

Android and iOS only. Web and desktop targets are not supported.

1. Create a Zorvia Messenger channel: Create and configure the channel in your Zorvia workspace.

2. Copy the installation values: From the channel's Installation screen, copy the workspace URL and public messenger key.

3. Install and initialize: Add the package and call Zorvia.initialize().

4. Identify signed-in visitors: Optionally call Zorvia.identify() to link the session to a known user.

The public messenger key is safe to include in your app. The identity signing secret is not. Keep it on your server.

---

Quick start

Add the dependency, initialize in main(), and open the chat with a button — that's the entire integration:

# pubspec.yaml
dependencies:
  zorvia_messenger: ^0.0.1

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

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Zorvia.initialize(
    url: 'https://your-workspace.zorvia.dev',
    livechatKey: 'pk_your_livechat_key',
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: const Center(child: Text('My App')),
        floatingActionButton: FloatingActionButton(
          onPressed: () => Zorvia.show(context),
          child: const Icon(Icons.chat),
        ),
      ),
    );
  }
}

Once the user is signed in, optionally attach their details:

await Zorvia.setVisitor(
  VisitorInfo(
    name: currentUser.name,
    email: currentUser.email,
  ),
);

---

Features

• One-line launch: Zorvia.show(context) opens the chat sheet
• Session persistence: anonymous and identified visitors, automatic restore on relaunch
• Real-time messaging: WebSocket connection with seamless HTTP fallback
• Media attachments: images, video, audio, and file uploads
• Customer satisfaction rating: visitors can rate their support experience after a conversation closes
• Theming: accent colour, dark/light mode, controlled from your Zorvia dashboard
• Visitor identity verification: HMAC-signed tokens for authenticated users

---

Requirements

	Minimum version
Flutter	3.40.0
Dart	3.10.0
Android	API level 21 (Android 5.0)
iOS	13.0

---

Installation

Add the package to your pubspec.yaml:

dependencies:
  zorvia_messenger: ^0.0.1

Then run:

flutter pub get

---

Platform setup

Android

Add the following to android/app/src/main/AndroidManifest.xml inside the <manifest> tag:

<!-- Required for HTTP and WebSocket -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Required only if your workspace has file attachments enabled -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

Most Flutter apps already include INTERNET. The remaining permissions are only needed if your Zorvia workspace has file attachments enabled.

iOS

Add the following to ios/Runner/Info.plist if your workspace has file attachments enabled:

<key>NSCameraUsageDescription</key>
<string>Needed to attach photos to support messages.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Needed to attach images from your library to support messages.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Needed to record audio messages.</string>

---

Identifying visitors

Anonymous (default)

No extra steps. The SDK creates an anonymous session automatically on first launch and restores it on every subsequent launch.

Known visitors

After the user signs in, attach their details so conversations are linked to their account:

await Zorvia.setVisitor(
  VisitorInfo(
    name: 'Amara Nwosu',
    email: '[e-mail]',
    phone: '[phone]',
  ),
);

Identity verification (recommended for production)

To prevent visitors from impersonating other users, enable identity verification. Your server generates an HMAC-SHA256 signature using your Zorvia identity signing secret, and the SDK passes it to Zorvia for validation.

Fetch the signed payload from your server, then call identify:

final identity = await yourApi.getZorviaIdentity(currentUser.id);

await Zorvia.identify(
  externalId: identity.externalId,
  timestamp: identity.timestamp,
  signature: identity.signature,
  name: identity.name,
  email: identity.email,
  phone: identity.phone,
  customData: identity.customData,
);

Parameter	Required	Description
externalId	Yes	A stable unique ID for the user in your system (database ID or UUID)
timestamp	Yes	Unix timestamp in seconds used when generating the signature. Zorvia rejects signatures older than 10 minutes
signature	Yes	HMAC-SHA256 signature generated on your server using your identity signing secret
name	No	The visitor's display name
email	No	The visitor's email address
phone	No	The visitor's phone number
customData	No	Arbitrary key-value pairs attached to the visitor (e.g. {"plan": "premium"})

The identity signing secret is in your Zorvia dashboard under Settings -> Messenger -> Security. Never include it in your app.

Logging out

Clear the visitor session when the user signs out:

await Zorvia.unregisterVisitor();

---

Customisation

Chat appearance (accent colour, avatar, and welcome message) is configured in your Zorvia dashboard under Messenger -> Appearance. The SDK fetches these settings automatically at launch.

To react to config changes at runtime:

Zorvia.configUpdates.listen((config) {
  // config is a ChannelConfig with the latest settings
});

---

Troubleshooting

"Invalid live chat token" error when sending a message

This usually happens when a session was created with a different workspace key. The SDK will automatically refresh the session and retry. If it persists, call Zorvia.unregisterVisitor() to clear the cached session and re-initialize.

Chat does not open (no bottom sheet appears)

Make sure Zorvia.initialize() has been awaited before calling Zorvia.show(). Calling show() before initialization throws a StateError.

WebSocket connection fails on Android emulator

Android emulators sometimes cannot resolve custom hostnames. Test real-time messaging on a physical device. HTTP-based sending and loading still works without a WebSocket connection.

Media permissions not requested

Ensure the CAMERA, RECORD_AUDIO, and READ_MEDIA_IMAGES permissions are declared in AndroidManifest.xml and the corresponding keys are in Info.plist. The SDK does not request runtime permissions on your behalf.

---

Support

• Documentation: https://developers.zorvia.io
• Website: zorvia.io
• Issues: github.com/Apex-Network-NG/Zorvia-messenger-flutter/issues