Contacts Getter #

• 🌍 updated by livedbs (Free Live Database, Storage)
• ivedbs.web.app

A powerful and easy-to-use Flutter plugin for accessing contacts, call logs, SMS, and device information on Android and iOS. Permissions are automatically requested with clear error messages.

✨ Features #

📱 Contacts Management #

• Get all contacts with filtering options
• Add, update, and delete contacts
• Find duplicate contacts
• Batch operations (add/delete multiple contacts)
• Add notes and tags to contacts
• Get WhatsApp and Telegram contacts
• Export/Import contacts (JSON & CSV)

📞 Call Logs #

• Get call history with date filtering
• Clear call logs
• Make phone calls

💬 SMS & Messaging #

• Get messages with filtering
• Send SMS
• Schedule SMS for later
• Delete messages
• Mark messages as read/unread
• Get unread message count
• Set auto-reply
• Export messages (JSON & CSV)

📡 Device & Network Info #

• Get SIM card information
• Get signal strength
• Check roaming status
• Get network speed
• Get data usage
• Switch active SIM (dual SIM devices)

🔒 Privacy & Security #

• Block/unblock phone numbers
• Auto-request permissions
• Clear error messages when permissions denied

👥 Social Integration #

• Get device accounts (Google, etc.)
• Get email accounts
• Get social media accounts

� Platform Support #

Legend:

• ✅ Full Support - Feature works completely
• ⚠️ Limited - Feature works with limitations
• ❌ Not Supported - Feature not available on this platform

Note: Some features are limited on iOS due to platform restrictions and privacy policies. Android generally provides more access to system data.

🚀 Quick Start Guide #

Step 1: Installation #

Run this command in your terminal:

flutter pub add contacts_getter

Step 2: Android Configuration #

Open android/app/src/main/AndroidManifest.xml and add only the permissions you need inside the <manifest> tag (above the <application> tag):

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
    <!-- 📞 COPY & PASTE THE PERMISSIONS YOU NEED: -->

    <!-- For CONTACTS features -->
    <uses-permission android:name="android.permission.READ_CONTACTS" />
    <uses-permission android:name="android.permission.WRITE_CONTACTS" />
    
    <!-- For CALL LOGS features -->
    <uses-permission android:name="android.permission.READ_CALL_LOG" />
    <uses-permission android:name="android.permission.WRITE_CALL_LOG" />
    
    <!-- For SMS features -->
    <uses-permission android:name="android.permission.READ_SMS" />
    <uses-permission android:name="android.permission.SEND_SMS" />
    
    <!-- For PHONE CALLS -->
    <uses-permission android:name="android.permission.CALL_PHONE" />
    
    <!-- For SIM & DEVICE Info -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_NUMBERS" />
    
    <!-- For NETWORK Info -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.INTERNET" />
    
    <application ...>

Step 3: iOS Configuration #

Open ios/Runner/Info.plist and add these keys inside the <dict> tag:

<dict>
    <!-- 📱 COPY & PASTE these keys: -->
    
    <key>NSContactsUsageDescription</key>
    <string>We need access to your contacts to display them in the app.</string>
    
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>We need location access to determine signal strength.</string>
    
    <!-- Note: iOS does not support SMS reading or Call Log access -->
</dict>

🚀 Usage #

Get Contacts #

import 'package:contacts_getter/contacts_getter.dart';

final getter = ContactsGetter();

// Get all contacts (permission auto-requested)
final contacts = await getter.getContacts();

// Get contacts with filtering
final recentContacts = await getter.getContacts(
  fromDate: DateTime.now().subtract(Duration(days: 30)),
  limit: 50,
  orderByDesc: true,
);

// Display contacts
for (var contact in contacts) {
  print('Name: ${contact.displayName}');
  print('Phone: ${contact.phoneNumber}');
  print('Email: ${contact.email}');
}

Add/Update/Delete Contacts #

// Add contact
await getter.addContact(
  name: 'John Doe',
  phoneNumber: '+1234567890',
);

// Update contact
await getter.updateContact(
  contactId: '123',
  name: 'Jane Doe',
  phoneNumber: '+0987654321',
  email: '[email protected]',
);

// Delete contact
await getter.deleteContact(contactId: '123');

// Batch add contacts
await getter.batchAddContacts(contacts: [
  {'name': 'Alice', 'phoneNumber': '+1111111111'},
  {'name': 'Bob', 'phoneNumber': '+2222222222'},
]);

Get Call Logs #

// Get all call logs
final callLogs = await getter.getCallLogs();

// Get recent call logs
final recentCalls = await getter.getCallLogs(
  fromDate: DateTime.now().subtract(Duration(days: 7)),
  limit: 20,
);

for (var log in callLogs) {
  print('Number: ${log.phoneNumber}');
  print('Type: ${log.callType}');
  print('Duration: ${log.duration}');
  print('Date: ${log.timestamp}');
}

// Clear all call logs
await getter.clearCallLogs();

SMS Operations #

// Get messages
final messages = await getter.getMessages(limit: 50);

for (var msg in messages) {
  print('From: ${msg.address}');
  print('Body: ${msg.body}');
  print('Date: ${msg.date}');
}

// Send SMS
await getter.sendSMS(
  phoneNumber: '+1234567890',
  message: 'Hello from Flutter!',
);

// Schedule SMS
await getter.scheduleSMS(
  phoneNumber: '+1234567890',
  message: 'Scheduled message',
  scheduledTime: DateTime.now().add(Duration(hours: 1)),
);

// Get unread count
final unreadCount = await getter.getUnreadMessageCount();
print('Unread messages: $unreadCount');

Device & SIM Information #

// Get SIM cards
final simCards = await getter.getSimCards();
for (var sim in simCards) {
  print('Carrier: ${sim['carrierName']}');
  print('Phone Number: ${sim['phoneNumber']}');
  print('Country: ${sim['countryCode']}');
}

// Get signal strength
final signal = await getter.getSignalStrength();
print('Signal strength: $signal');

// Check roaming
final isRoaming = await getter.isRoaming();
print('Roaming: $isRoaming');

// Get network speed
final speed = await getter.getNetworkSpeed();
print('Download: ${speed['downloadSpeed']} Mbps');
print('Upload: ${speed['uploadSpeed']} Mbps');

// Get data usage
final usage = await getter.getDataUsage();
print('Mobile data: ${usage['mobileDataUsage']} MB');
print('WiFi data: ${usage['wifiDataUsage']} MB');

Social Integration #

// Get WhatsApp contacts
final whatsappContacts = await getter.getWhatsAppContacts();

// Get Telegram contacts
final telegramContacts = await getter.getTelegramContacts();

// Get device accounts
final accounts = await getter.getDeviceAccounts();
for (var account in accounts) {
  print('Name: ${account.name}');
  print('Type: ${account.type}');
}

// Get email accounts
final emailAccounts = await getter.getAllEmailAccounts();

// Get social media accounts
final socialAccounts = await getter.getSocialMediaAccounts();

Block Numbers #

// Block a number
await getter.blockNumber(phoneNumber: '+1234567890');

// Unblock a number
await getter.unblockNumber(phoneNumber: '+1234567890');

Find Duplicates #

// Find duplicate contacts
final duplicates = await getter.findDuplicateContacts();
print('Found ${duplicates.length} duplicate contacts');

Export/Import Contacts & Messages #

Export and import your contacts and messages in JSON or CSV format for backup, migration, or data analysis.

Export Contacts

// Export to JSON
final jsonString = await getter.exportContactsToJson();
print('Exported: $jsonString');

// Save to file
await File('contacts_backup.json').writeAsString(jsonString);

// Export to CSV
final csvString = await getter.exportContactsToCsv();
await File('contacts_backup.csv').writeAsString(csvString);

Import Contacts

// Import from JSON file
final jsonData = await File('contacts_backup.json').readAsString();
final importedCount = await getter.importContactsFromJson(jsonData);
print('Imported $importedCount contacts');

// Import from CSV file
final csvData = await File('contacts_backup.csv').readAsString();
final count = await getter.importContactsFromCsv(csvData);
print('Imported $count contacts');

// Bulk import from JSON string
final bulkJson = '''
[
  {"name": "John Doe", "phone": "+1234567890", "email": "[email protected]"},
  {"name": "Jane Smith", "phone": "+0987654321", "email": "[email protected]"}
]
''';
final imported = await getter.importContactsFromJson(bulkJson);
print('Bulk imported $imported contacts');

Export Messages

// Export messages to JSON
final messagesJson = await getter.exportMessagesToJson();
await File('messages_backup.json').writeAsString(messagesJson);

// Export messages to CSV
final messagesCsv = await getter.exportMessagesToCsv();
await File('messages_backup.csv').writeAsString(messagesCsv);

Data Formats

JSON Format (Contacts):

[
  {
    "id": "1",
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "[email protected]"
  }
]

CSV Format (Contacts):

ID,Name,Phone,Email
1,"John Doe","+1234567890","[email protected]"
2,"Jane Smith","+0987654321","[email protected]"

JSON Format (Messages):

[
  {
    "id": "1",
    "address": "+1234567890",
    "body": "Hello!",
    "date": 1735560000000,
    "isRead": true
  }
]

CSV Format (Messages):

ID,Address,Body,Date,Read
1,"+1234567890","Hello!",1735560000000,true

📱 Complete Example #

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

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: ContactsPage(),
    );
  }
}

class ContactsPage extends StatefulWidget {
  @override
  _ContactsPageState createState() => _ContactsPageState();
}

class _ContactsPageState extends State<ContactsPage> {
  final _getter = ContactsGetter();
  List<Contact> _contacts = [];
  bool _loading = false;

  @override
  void initState() {
    super.initState();
    _loadContacts();
  }

  Future<void> _loadContacts() async {
    setState(() => _loading = true);
    
    // Permission is auto-requested
    final contacts = await _getter.getContacts();
    
    setState(() {
      _contacts = contacts;
      _loading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Contacts (${_contacts.length})'),
        actions: [
          IconButton(
            icon: Icon(Icons.refresh),
            onPressed: _loadContacts,
          ),
        ],
      ),
      body: _loading
          ? Center(child: CircularProgressIndicator())
          : ListView.builder(
              itemCount: _contacts.length,
              itemBuilder: (context, index) {
                final contact = _contacts[index];
                return ListTile(
                  leading: CircleAvatar(
                    child: Text(contact.displayName[0].toUpperCase()),
                  ),
                  title: Text(contact.displayName),
                  subtitle: Text(contact.phoneNumber ?? 'No phone'),
                  trailing: IconButton(
                    icon: Icon(Icons.delete),
                    onPressed: () async {
                      await _getter.deleteContact(
                        contactId: contact.id,
                      );
                      _loadContacts();
                    },
                  ),
                );
              },
            ),
      floatingActionButton: FloatingActionButton(
        child: Icon(Icons.add),
        onPressed: () async {
          await _getter.addContact(
            name: 'New Contact',
            phoneNumber: '+1234567890',
          );
          _loadContacts();
        },
      ),
    );
  }
}

⚠️ Permission Handling #

Permissions are automatically requested when you call methods. If permission is denied, you'll see a clear error message in the console:

❌ Contacts permission denied
💡 Add to AndroidManifest.xml:
   <uses-permission android:name="android.permission.READ_CONTACTS" />
   <uses-permission android:name="android.permission.WRITE_CONTACTS" />

🎯 Best Practices #

1. Add only needed permissions - Don't add all permissions if you only use contacts
2. Handle permission denials - Check return values and handle empty lists
3. Use filtering - Use fromDate and limit parameters for better performance
4. Batch operations - Use batch methods for multiple operations

📚 API Reference #

See the API documentation for complete method details.

🐛 Issues & Feedback #

Please file issues on GitHub.

📄 License #

MIT License - see LICENSE file for details.

👨‍💻 Author #

Hassan Ameer - GitHub

⭐ Show Your Support #

Give a ⭐️ if this project helped you!

Our Other Packages #

• LiveDB: - A powerful local database with reactive streams.
• Media Link Generator: - Generate direct download links for various cloud storages.
• MediaGetter: - Complete solution for picking and managing media files.
• Contacts Getter: - Access and manage device contacts and messages.
• Timer Widget: - Countdown, Cooldown, Debounce, Async Loader.