Flutter SDK

Requirements#

• Dart >=3.4.0 <4.0.0.
• Flutter >=3.16.0 (the 3.x line).
• Pure Dart: no native bridges, no pod install, no Gradle edits. Transitive deps are plain Dart packages (http, web_socket_channel, uuid).

Installation#

Add the package from pub.dev:

dependencies:
  respondo_sdk: ^0.1.2

import 'package:respondo_sdk/respondo_sdk.dart';

Initialize#

Bind Respondo.navigatorKey to your MaterialApp so the SDK can open the chat sheet without your BuildContext, call Respondo.init once, then Respondo.open().

import 'package:flutter/material.dart';
import 'package:path_provider/path_provider.dart';
import 'package:respondo_sdk/respondo_sdk.dart';

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

  // File storage directory comes from a host-app plugin; the SDK stays pure.
  final dir = await getApplicationSupportDirectory();

  await Respondo.init(
    RespondoConfig(
      agentId: '<agent-uuid>',
      channelId: '<channel-uuid>',
      storageDirectory: dir.path,
    ),
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: Respondo.navigatorKey, // required so the SDK can open the chat
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

All facade methods are idempotent, safe to call before init (they buffer and replay), and never throw into your app.

Identify users#

By default every visitor is anonymous. On first launch the SDK generates a stable visitor_id and keeps it in local storage, so a returning user finds their conversation again. There is no API key to embed — each conversation is protected by a per-conversation session token the backend mints and slides forward on every message, so an anonymous visitor never has to re-authenticate.

Call identify once your user is signed in. This attaches their real identity so their history follows them across devices and reinstalls, and their name and email show up next to the conversation in your inbox instead of an anonymous visitor.

The userHash is a signature your backend computes from the agent's identity_secret — HMAC-SHA256(secret, userId) (or the email when there is no userId), encoded as lowercase hex. The secret proves the identity is genuine, so it must live only on your backend and is never shipped in the app. See the Identity verification page for the full formula and server-side examples.

// 1. Sign in against your own backend and read the precomputed hash
//    (for example, a field returned alongside the login response).
final session = await api.login(email, password);

// 2. Hand the finished userHash to the SDK — never compute it in the app.
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. On logout: revoke the session and start a fresh anonymous visitor.
Respondo.reset();

If the hash is missing or wrong, nothing throws: the backend silently keeps the visitor anonymous, the chat keeps working, and you simply lose the cross-device link until a valid hash is supplied. Verification only runs when the agent has an identity_secret set — leave it empty during development and userId / email are accepted as-is.

Observables & callbacks#

Everything is available as a broadcast Stream, a callback setter, and a current-value getter.

// Reactive stream of unread counts (for a badge).
Respondo.unreadCountStream.listen((n) => setBadge(n));

// Or a callback setter.
Respondo.onUnreadChanged = (n) => setBadge(n);

// Intercept links/CTAs; return true if the host opened the URL itself.
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

Next steps#

Add Push notifications and Identity verification. The full API surface, engagement surfaces, and troubleshooting are covered in the Flutter SDK getting-started guide on the pub.dev package page.