Migrate from Agora

An existing agora_rtc_engine app needs three edits: the dependency, the import, and one line of configuration. Your call sites, event handlers, enums and error handling stay exactly as they are.

Swap the dependency

pubspec.yaml

dependencies:
-  agora_rtc_engine: ^6.6.3
+  voxa_rtc_engine: ^0.2.8

Swap the import

A project-wide find and replace:

bash

# macOS / BSD sed
grep -rl "package:agora_rtc_engine/agora_rtc_engine.dart" lib \
  | xargs sed -i '' \
    's|package:agora_rtc_engine/agora_rtc_engine.dart|package:voxa_rtc_engine/voxa_rtc_engine.dart|g'

The barrel exports the same names, so nothing below the import line changes. If your app imports Agora sub-libraries directly (e.g. agora_rtc_engine/agora_rtc_engine_ex.dart), replace the package segment the same way.

Point at your gateway

lib/main.dart

import 'package:voxa_rtc_engine/voxa.dart';

void main() {
  VoxaRtc.serverUrl = 'https://gate.zamansheikh.com';
  runApp(const MyApp());
}

Set it before any initialize() call. It is a static, so a single assignment at startup covers the whole app.

Your backend, unchanged

The gateway verifies genuine Agora tokens — both AccessToken2 (007…) and legacy AccessToken v1 (006…) — against the app certificate. So a token server built on agora-access-token, agora-token, or Agora's own Go/Python/Java builders keeps working. The only change is which credentials it signs with.

Two ways to handle that:

Import your existing Agora credentials. Create the project with your current App ID and certificate, and your token server needs no change at all. Existing tokens verify immediately.
Use new credentials. Create a project, then update the App ID and certificate in your token server's configuration.

Either way it is one step in the console: create a project, and tick "import existing Agora credentials" if you want to keep the App ID and certificate you already sign with.

Dependency conflicts to expect

wakelock_plus

Common in live-streaming apps, and it will fail the version solve. The media engine pulls device_info_plus 12.x, which pins win32 5.x; wakelock_plus needs win32 6.x. Lift device_info_plus instead of pinning win32 — 13.x uses win32 6.x and satisfies both:

pubspec.yaml

dependency_overrides:
  device_info_plus: ^13.2.0

Android Gradle Plugin

Removing agora_rtc_engine also removes its AAR, which some builds were pinned around. A build on AGP 8.7–8.11 with Gradle 8.14 and compileSdk 36 is a known-good combination.

Verifying the migration

Behavioural parity is not assumed here — it is recorded. Scenarios are captured from the live Agora service as golden transcripts (callback sequence, arguments, ordering) and replayed against VoxaRTC, then diffed. Eight scenarios currently pass, covering join/leave, roles, mute, reconnection and media bursts.

For your own app, the fastest confidence check is the callback log. Put a debugPrint in every handler you register, run the same user flow before and after, and diff the two logs. Order matters as much as content — onJoinChannelSuccess before onUserJoined, onUserJoined before onUserPublished.

Known differences

Area	Difference
Unimplemented APIs	Media player, spatial audio, channel media relay, raw frame observers and RTM throw `AgoraRtcException(-4, errNotSupported)`.
Subscriber publish rights	A subscriber-role token may still publish by default, matching Agora's co-host behaviour. Set `enforceCoHostAuth` on the project for strict enforcement.
Web	Not supported yet. Android and macOS are device-tested; iOS is expected to work but is not CI-verified.
Statistics	`onRtcStats` and `onNetworkQuality` fire with engine- derived values; the fields are populated, the exact numbers are not Agora's.

The full list is in API compatibility.

PreviousQuickstart NextTokens & auth