Build visitor and agent communications inside a Flutter app

Overview

What this SDK is for

Use this Flutter SDK for customer-facing support experiences or internal agent workspaces. Visitor and Agent runtimes remain separate.

Server and SDK topology

Architecture that must be set up

The SDK is embedded in the Flutter app, but secret-bearing work belongs to the customer backend. This prevents developers from shipping the Ringnity Server API key inside the mobile bundle.

Overview

Visitor capability map

This map covers the visitor runtime. The native Agent runtime is documented separately below so its token and state are never mixed with visitor sessions.

ringnity_flutter_sdk
  Dart object model, generated operation layer, HTTP adapter,
  Managed UI preview widgets, and Headless SDK objects.

platform adapters
  Android/iOS call adapter bridge, notification/ringtone bridge,
  permissions helpers, and video view integration points.

Native Agent

Build a native agent workspace

Use the separate RingnityAgent root for agent inbox, direct and group Team chat, call-room control, visitor and direct Team WebRTC calls, authoritative badges, and native incoming-call actions. joinRoom connects the Ringnity-managed group-media session while the host owns its visual layout. Visitor and agent tokens never share a runtime.

final nativeCalls = RingnityAgentPlatformCallAdapter();
final agent = await RingnityAgent.create(RingnityAgentConfig(
  tokenProvider: fetchFreshAgentSdkToken,
  nativeCallAdapter: nativeCalls,
));

await agent.connect();
await agent.calls.goOnline();

agent.calls.incoming.listen((call) async {
  await call.accept(video: call.type == RingnityAgentCallType.video);
});

final inbox = await agent.conversations.list(status: 'open');
final peers = await agent.team.chats.list();

await agent.devices.register(
  platform: RingnityPushPlatform.ios,
  provider: RingnityPushProvider.apnsVoip,
  token: (await agent.nativeCalls.voipToken())!,
  apnsEnvironment: (await agent.nativeCalls.voipEnvironment())!,
  appId: 'com.example.support',
);

agent.nativeCalls.actions.listen((action) async {
  await agent.nativeCalls.handleAction(action);
});
await agent.badges.syncNative();

The backend must issue a short-lived Agent SDK token with the required feature scopes, including agent:devices:write when push registration is enabled. The host app owns Firebase initialization, FCM receipt, navigation, and UI.

Server

Server requirements

The backend endpoint is the trust boundary. It authenticates the customer app user, creates Ringnity context, exchanges it to a SDK session token, and returns only that short-lived token to Flutter.

Server

Create the runtime token endpoint

Keep secrets on your backend while Flutter receives only short-lived access. The example below creates a trusted visitor context, exchanges it for a SDK session, then returns the SDK session token.

RINGNITY_API_BASE_URL=https://api.ringnity.com
RINGNITY_SERVER_API_KEY=sk_live_or_test_from_ringnity_dashboard

import express from "express";
import { RingnityServerApi } from "@ringnity/server-api";

const app = express();
app.use(express.json());

const ringnity = RingnityServerApi.create({
  apiBaseUrl: process.env.RINGNITY_API_BASE_URL,
  apiKey: process.env.RINGNITY_SERVER_API_KEY,
});

async function requireCustomer(req) {
  // Replace this with your own session, JWT, or account validation.
  return {
    id: req.body.userId,
    name: req.body.name,
    email: req.body.email,
  };
}

app.post("/ringnity/runtime-token", async (req, res) => {
  const customer = await requireCustomer(req);

  const context = await ringnity.tokens.visitorContext({
    visitor: {
      externalId: customer.id,
      name: customer.name,
      email: customer.email,
    },
    metadata: {
      source: "flutter-app",
      appVersion: req.body.appVersion,
      platform: req.body.platform,
    },
    expiresIn: 900,
  });

  res.json({
    token: context.contextToken,
    expiresIn: context.expiresIn,
    tokenType: context.tokenType,
  });
});

app.listen(3000);

{
  "token": "eyJhbGciOi...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Server

Token lifecycle

Move from app entry to support session with a predictable flow. Flutter can ask the backend for a new token when the app starts, when the SDK returns unauthorized, or before a long chat/call session.

Server

Security checklist

Use this checklist before sharing the Flutter build with a real customer.

Flutter Setup

Download what you need

Current downloadable SDK bundle: 0.2.0-beta.0. Use the Flutter SDK for the app and the Server API SDK for the customer backend token endpoint.

Flutter SDK

Dart SDK, Managed UI preview widgets, Headless object model, platform call adapter, and sample Flutter app.

Version0.2.0-beta.0

Fileringnity-flutter-sdk-0.2.0-beta.0.zip

Open or download

Server API SDK

Backend helper package for token exchange. Keep the Server API key inside this backend only.

Version0.2.0-beta.0

Fileringnity-server-api-sdk-0.2.0-beta.0.zip

Open or download

OpenAPI Contract

Use the live contract for exact REST schemas, fields, and status codes.

VersionLive

Fileopenapi.yaml

Open or download

Scalar Reference

Interactive API reference for backend developers and QA teams.

VersionLive

Filehttps://api.ringnity.com/api/docs

Open or download

Flutter Setup

Install the Flutter SDK

During preview, download the source package and install it from a local package path. When public package publishing is enabled, this section can switch to pub.dev coordinates.

# Pilot install from a local source package
# pubspec.yaml
dependencies:
  ringnity_flutter_sdk:
    path: ./ringnity_flutter_sdk

# Then
flutter pub get

Flutter Setup

Initialize SDK

Create the SDK from a screen, app service, provider, or support module. The token provider calls the customer backend endpoint from the Server section.

import 'dart:convert';

import 'package:http/http.dart' as http;
import 'package:ringnity_flutter_sdk/ringnity_flutter_sdk.dart';

final callAdapter = RingnityPlatformCallAdapter();

Future<RingnityRuntimeToken> fetchRingnityRuntimeToken() async {
  final response = await http.post(
    Uri.parse('https://your-backend.example.com/ringnity/runtime-token'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'userId': currentUser.id,
      'name': currentUser.name,
      'email': currentUser.email,
      'appVersion': '1.0.0',
      'platform': 'flutter',
    }),
  );

  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Ringnity runtime token request failed');
  }

  final data = jsonDecode(response.body) as Map<String, dynamic>;
  return RingnityRuntimeToken(
    token: data['token'] as String,
    tokenType: data['tokenType'] as String? ?? 'Bearer',
    expiresIn: data['expiresIn'] as int? ?? 900,
  );
}

final ringnity = await Ringnity.create(
  RingnityConfig(
    apiBaseUrl: 'https://api.ringnity.com',
    tokenProvider: fetchRingnityRuntimeToken,
    callMode: RingnityCallMode.basic,
    mediaAdapter: callAdapter,
    notificationAdapter: callAdapter,
    notifications: const RingnityNotificationPreferences(
      incomingCall: RingnityRingtoneOptions(
        soundName: 'ringnity_default',
        vibrate: true,
      ),
    ),
  ),
);

Managed UI

Managed UI overview

Launch a complete Ringnity support screen with Flutter widgets. Use Managed UI when the app wants Ringnity to draw the support screen.

import 'package:ringnity_flutter_sdk/ringnity_flutter_sdk.dart';

final callAdapter = RingnityPlatformCallAdapter();

final config = RingnityConfig(
  apiBaseUrl: 'https://api.ringnity.com',
  tokenProvider: fetchRingnityRuntimeToken,
  callMode: RingnityCallMode.basic,
  mediaAdapter: callAdapter,
  notificationAdapter: callAdapter,
);

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

  @override
  Widget build(BuildContext context) {
    return RingnityWidget(
      config: config,
      mode: RingnityWidgetMode.full,
      conversationSubject: 'Mobile customer support',
    );
  }
}

RingnityWidget(
  config: config,
  mode: RingnityWidgetMode.call,
  remoteVideo: YourRemoteVideoView(),
  localPreview: YourLocalPreviewView(),
);

RingnityVideoView(
  session: callSession,
  remoteVideo: YourRemoteVideoView(),
  localPreview: YourLocalPreviewView(),
);

Managed UI

Included features

With Managed UI, the feature implementation is bundled into RingnityWidget. The host app still owns backend token flow, platform permissions, push setup, and app lifecycle.

RingnityWidget(config: config, mode: RingnityWidgetMode.chat);
RingnityWidget(config: config, mode: RingnityWidgetMode.aiChat);
RingnityWidget(config: config, mode: RingnityWidgetMode.call);

final ringnity = await Ringnity.create(config);

Column(
  children: [
    Expanded(child: RingnityChatWidget(ringnity: ringnity)),
    SizedBox(height: 320, child: RingnityCallWidget(ringnity: ringnity)),
  ],
);

Headless UI

Headless UI overview

Use Ringnity as the support engine behind your own Flutter screens. Headless UI is for apps that own navigation, message rendering, call controls, and analytics.

Headless UI

Feature APIs

Each visitor feature can be used from custom Flutter screens. The same secure tokenProvider and SDK instance power every feature.

Visitor Feature

Chat

Create a visitor conversation, send messages, and keep your screen updated while support is active.

final readiness = await ringnity.account.readiness();

final conversation = await ringnity.chat.createConversation(
  subject: 'Need help with my order',
);

final conversationId = conversation['conversationId'] as String;

final message = await ringnity.chat.sendMessage(
  conversationId: conversationId,
  body: 'Hi, I need help.',
);

await ringnity.chat.markRead(
  conversationId: conversationId,
  messageId: message['messageId'] as String,
);

// Also available: availability, activeConversation, getConversation,
// closeConversation, updateProfile, editMessage, deleteMessage, createAttachment,
// uploadAttachment, requestCall, and finalizeCallRequest. AI also exposes routing and searchKnowledge.

final conversationEvents = ringnity.chat.conversations.listen((event) {
  renderConversation(event);
});

final messageEvents = ringnity.chat.messages.listen((message) {
  appendMessage(message);
});

final subscription = await ringnity.chat.subscribe(conversationId);

// Call these when the screen is destroyed or the conversation is closed.
subscription.unsubscribe();
await conversationEvents.cancel();
await messageEvents.cancel();

Visitor Feature

AI Chat

Ask AI and render the answer in your own component, while plan readiness and tenant configuration stay controlled by Ringnity.

await for (final event in ringnity.ai.streamChat(
  conversationId: conversationId,
  message: 'Summarize the customer issue.',
)) {
  switch (event['type']) {
    case 'ai.message.delta':
      final data = event['data'] as Map<String, Object?>;
      appendToChat(data['delta'] as String);
      break;
    case 'ai.message.completed':
      setAiAnswer(event['data'] as Map<String, Object?>);
      break;
    case 'ai.message.failed':
      showAiError(event);
      break;
  }
}

Visitor Feature

Voice Call

Start a production audio session through the bundled authenticated signalling transport and flutter_webrtc media engine.

final permissions = await callAdapter.permissions(video: false);

if (permissions.canStartAudio) {
  final call = await ringnity.calls.startAudio(
    conversationId: conversationId,
  );

  await call.mute();
  await call.unmute();
  await call.end();
}

Visitor Feature

Video Call

Start a production video session through the bundled signalling transport, ICE/TURN configuration, and flutter_webrtc engine.

final permissions = await callAdapter.permissions(video: true);

if (permissions.canStartVideo) {
  final call = await ringnity.calls.startVideo(
    conversationId: conversationId,
  );

  await call.setVideoEnabled(false);
  await call.setVideoEnabled(true);
  await call.end();
}

Visitor Feature

Push Notification

Register the device push token so Ringnity can target the visitor when background delivery is needed.

await ringnity.devices.registerPushToken(
  platform: RingnityPushPlatform.flutter,
  provider: RingnityPushProvider.fcm,
  token: firebaseMessagingToken,
  audience: RingnityPushAudience.customer,
  externalId: 'customer-123',
  appId: 'com.example.customer',
);

Visitor Feature

Ringtone

Play or preview incoming call sounds while the app is in the foreground, then stop when the call is answered, declined, or expired.

// Add Android asset: android/app/src/main/res/raw/ringnity_default.*
// Add iOS asset: ringnity_default.caf in the app bundle.

await ringnity.notifications.previewRingtone();

await ringnity.notifications.playIncomingRingtone();

// Stop when the customer answers, declines, or the call expires.
await ringnity.notifications.stopRingtone();

Operations

Lifecycle

Keep setup predictable by treating the SDK as a runtime service owned by a support screen, app service, or provider.

Operations

Troubleshooting

Most integration failures come from missing tenant context, token exchange mistakes, or platform permission setup.

Operations

Full example

Use Managed UI for the fastest install. Use Headless UI when the product screen must follow the host app design system.

import 'dart:async';
import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:ringnity_flutter_sdk/ringnity_flutter_sdk.dart';

final callAdapter = RingnityPlatformCallAdapter();

Future<RingnityRuntimeToken> fetchRingnityRuntimeToken() async {
  final response = await http.post(
    Uri.parse('https://your-backend.example.com/ringnity/runtime-token'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'userId': currentUser.id,
      'name': currentUser.name,
      'email': currentUser.email,
      'platform': 'flutter',
    }),
  );

  final data = jsonDecode(response.body) as Map<String, dynamic>;
  return RingnityRuntimeToken(
    token: data['token'] as String,
    tokenType: data['tokenType'] as String? ?? 'Bearer',
    expiresIn: data['expiresIn'] as int? ?? 900,
  );
}

final config = RingnityConfig(
  tokenProvider: fetchRingnityRuntimeToken,
  callMode: RingnityCallMode.basic,
  mediaAdapter: callAdapter,
  notificationAdapter: callAdapter,
);

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

  @override
  Widget build(BuildContext context) {
    return RingnityWidget(
      config: config,
      mode: RingnityWidgetMode.full,
      conversationSubject: 'Mobile customer support',
    );
  }
}

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

  @override
  State<HeadlessSupportScreen> createState() => _HeadlessSupportScreenState();
}

class _HeadlessSupportScreenState extends State<HeadlessSupportScreen> {
  final messages = <Map<String, Object?>>[];
  Ringnity? ringnity;
  RingnityChatSubscription? subscription;
  StreamSubscription<Map<String, Object?>>? messageEvents;

  @override
  void initState() {
    super.initState();
    unawaited(start());
  }

  Future<void> start() async {
    final sdk = await Ringnity.create(config);
    final conversation = await sdk.chat.createConversation(
      subject: 'Mobile customer support',
    );
    final conversationId = conversation['conversationId'] as String;

    messageEvents = sdk.chat.messages.listen((message) {
      setState(() => messages.add(message));
    });

    subscription = await sdk.chat.subscribe(conversationId);

    await sdk.chat.sendMessage(
      conversationId: conversationId,
      body: 'Hi, I need help.',
    );

    setState(() => ringnity = sdk);
  }

  @override
  void dispose() {
    subscription?.unsubscribe();
    messageEvents?.cancel();
    ringnity?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return YourCustomSupportView(messages: messages);
  }
}