ring_client_api #

This is an unofficial Dart API for Ring Doorbells, Ring Cameras, the Ring Alarm System, Ring Smart Lighting, and third party devices that connect to the Ring Alarm System.

This package is a Dart port of the popular ring-client-api TypeScript library.

Features #

• Full access to Ring API with Dart null-safety
• Support for Ring Doorbells and Cameras
• Ring Alarm System integration
• Smart Lighting control
• Real-time push notifications via WebSocket
• WebRTC video streaming support (via companion Flutter package)
• Historical event data
• Device status monitoring and control
• Camera snapshots
• Event history and playback
• Two-factor authentication (2FA) support
• CLI tools for authentication and device data

Streaming Support #

This core package provides REST API and WebSocket functionality. For full WebRTC video streaming in Flutter apps, use the companion package:

ring_camera - Full video streaming with flutter_webrtc

Note: Features intentionally not implemented in this core package (WebRTC, FFmpeg, Push Notifications) are tracked in ring_camera/TODO.md with detailed implementation plans.

Troubleshooting Issues #

If you are having issues, please search existing Issues before opening a new one.

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  ring_client_api: ^0.1.0

Then run:

dart pub get

Setup and Config #

First, generate a refreshToken using the Ring authentication process. You will need to authenticate with your Ring account credentials.

import 'package:ring_client_api/ring_client_api.dart';

void main() async {
  // Create API instance with refresh token authentication
  final ringApi = RingApi(
    RefreshTokenAuth(refreshToken: 'your_refresh_token_here'),
    options: RingApiOptions(
      debug: false,
      cameraStatusPollingSeconds: 20,
      locationModePollingSeconds: 20,
      avoidSnapshotBatteryDrain: false,
      controlCenterDisplayName: 'My Dart App',
    ),
  );

  // Listen for refresh token updates to save the new token
  ringApi.onRefreshTokenUpdated.listen((update) {
    print('New refresh token: ${update.newRefreshToken}');
    // Save the updated token to secure storage
  });

  // Get locations and cameras
  final locations = await ringApi.getLocations();
  final cameras = await ringApi.getCameras();

  // Clean up when done
  await ringApi.disconnect();
}

Optional Parameters #

Locations #

final locations = await ringApi.getLocations();
final location = locations[0];

// Check if location has hubs (alarm and/or lighting bridge)
print(location.hasHubs);

// Arm/disarm location
await location.disarm();
await location.armHome([
  /* optional array of zids for devices to bypass */
]);
await location.armAway([
  /* bypass zids */
]);

// Get alarm mode
final mode = await location.getAlarmMode(); // returns 'all', 'some', or 'none'

// Siren control
await location.soundSiren();
await location.silenceSiren();

// Access cameras and history
final cameras = location.cameras;
final history = await location.getHistory();
final cameraEvents = await location.getCameraEvents();

locations is a list of your Ring locations. Each location can be armed or disarmed, and used to interact with all devices in that location.

Devices #

Once you have acquired the desired location, you can start to interact with associated devices. These devices include ring alarm, ring lighting, and third party devices connected to ring alarm.

import 'package:ring_client_api/ring_client_api.dart';

final devices = await location.getDevices();
final baseStation = devices.firstWhere(
  (device) => device.data.deviceType == RingDeviceType.baseStation
);

// Set volume (base station and keypad support volume settings between 0 and 1)
await baseStation.setVolume(0.75);

// Access device data
print(baseStation.data); // object containing properties like zid, name, roomId, faulted, tamperStatus, etc.

// Listen for data updates
baseStation.onData.listen((data) {
  // called any time data is updated for this specific device
});

Cameras #

You can get all cameras using await ringApi.getCameras() or cameras for a particular location with location.cameras.

final camera = location.cameras[0];

// Access camera data
print(camera.data); // camera info including motion zones, light status, battery, etc.

// Listen for data updates
camera.onData.listen((data) {
  // called every time new data is fetched for this camera
});

// Control camera features
await camera.setLight(true); // turn light on/off
await camera.setSiren(true); // turn siren on/off

// Get camera information
final health = await camera.getHealth(); // fetch health info like wifi status
await camera.startVideoOnDemand(); // ask the camera to start a new video stream

// SIP session for RTP control
final sipSession = await camera.createSipSession();

// Event history and recordings
final events = await camera.getEvents(); // fetch ding events for the camera
final recordingUrl = await camera.getRecordingUrl(dingIdStr, transcoded: true);
final snapshot = await camera.getSnapshot(); // returns Uint8List of latest snapshot

Camera also includes the following streams:

• onNewNotification: triggered any time a new push notification is received
• onActiveNotifications: notifications received within the last minute
• onDoorbellPressed: includes the sip info and ding information every time a new ding is created
• onActiveDings: dings created within the last 65 seconds
• onDoorbellPressed: emits a ding every time the doorbell is pressed
• onMotionDetected: true or false based on onActiveDings containing a motion ding

Some other useful properties:

• id
• name: same as description from data
• hasLight: does this camera have a light
• hasSiren: does this camera have a siren
• isDoorbot: is this camera a doorbell

Refresh Token #

Ring has restrictions on refresh tokens that may cause them to expire. Make sure to handle token refresh properly in your application to maintain a stable connection.

CLI Tools #

This package includes command-line tools to help with authentication and debugging:

ring_auth_cli.dart #

Obtain a refresh token by authenticating with your Ring account:

dart run bin/ring_auth_cli.dart

This interactive CLI will prompt for your email/password and handle 2FA if required.

ring_device_data_cli.dart #

Fetch and anonymize device data for debugging purposes:

dart run bin/ring_device_data_cli.dart <refresh_token>

Outputs device information with sensitive data removed.

list_cameras.dart #

List all cameras associated with your Ring account:

dart run bin/list_cameras.dart <refresh_token>

Displays camera names and IDs for quick reference.

Example #

See the example directory for a complete example application.

Documentation #

This package includes comprehensive documentation to help you understand the implementation and migrate from the TypeScript version:

• CHANGELOG.md - Version history, release notes, and feature list for v0.1.0
• TODO.md - Complete project implementation checklist showing all 11 phases of the port
• TYPESCRIPT_DIFFERENCES.md - Detailed guide to differences between TypeScript and Dart implementations, including language features, patterns, and migration guide
• GAP_ANALYSIS.md - Comprehensive analysis showing 100% REST API coverage compared to the original TypeScript library

For information about intentional feature exclusions (WebRTC video streaming, FFmpeg integration, Push Notifications), see the companion package documentation:

• ring_camera - Flutter package with full WebRTC streaming support
• ring_camera/TODO.md - Detailed roadmap for platform-specific features

Additional information #

This package is a port of the TypeScript ring-client-api library by Dusty Greif.

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

Issues #

Please file issues at the GitHub issue tracker.

License #

MIT License - see LICENSE file for details.

Original TypeScript library Copyright (c) 2022 Dusty Greif

Dart port Copyright (c) 2025 Scott Horn