flutter_afriksms

A powerful and easy-to-use Dart package for integrating the AfrikSMS API. Send SMS messages, bulk campaigns, check your balance, and receive delivery reports with just a few lines of code.

🌍 Documentation: English · Français

Pub Version License: MIT

Features

  • ✉️ Send Single SMS - Send SMS to individual recipients
  • 📤 Send Bulk SMS - Send the same message to up to 500 recipients
  • 💬 Personalized Bulk SMS - Send customized messages to multiple recipients
  • 📧 SMS with Email - Send SMS with optional email notifications
  • 📊 Delivery Reports - Receive real-time delivery status via webhooks
  • 💰 Check Balance - Query your account balance for all countries
  • ⚙️ Configure Callbacks - Set up webhook URLs for delivery reports
  • 🔒 Type-Safe - Fully typed with comprehensive error handling
  • ✅ Validation - Built-in input validation for phone numbers and parameters
  • 📝 Logging - Optional debug logging for troubleshooting

⚠️ For Moov : Make sure the Sender name is registered in their registered sender names.

Getting Started

Installation

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

dependencies:
  flutter_afriksms: ^1.0.0

Then run:

dart pub get

Prerequisites

  1. Create an AfrikSMS account by reaching afriksms.com/.
  2. Get your credentials by contacting support@afriksms.com.
  3. Purchase SMS credits to start sending messages.

Usage

Basic Example

import 'package:flutter_afriksms/flutter_afriksms.dart';

Future<void> main() async {
  // Create the client
  final client = AfrikSmsClient(
    config: AfrikSmsConfig(
      clientId: 'your_client_id',
      apiKey: 'your_api_key',
      senderId: 'MYAPP',
      enableLogging: true,
    ),
  );

  try {
    // Send an SMS
    final response = await client.sendSms(
      phoneNumber: '22890909090',
      message: 'Hello from AfrikSMS!',
    );

    if (response.isSuccess) {
      print('SMS sent! Resource ID: ${response.resourceId}');
    }
  } finally {
    client.close();
  }
}

Send Bulk SMS

final response = await client.sendBulkSms(
  phoneNumbers: '22890909090,22996760000,22378810000',
  message: 'Bulk SMS to multiple recipients',
);

print('Sent: ${response.successCount}/${response.data.length}');

Send Personalized Bulk SMS

final response = await client.sendPersonalizedBulkSms(
  messages: [
    PersonalizedSmsMessage(
      mobileNumbers: '22890909090',
      message: 'Hello Bernard, your order #123 is ready!',
    ),
    PersonalizedSmsMessage(
      mobileNumbers: '22996760000',
      message: 'Hello Modeste, your appointment is tomorrow.',
    ),
  ],
);

Send SMS with Email

final response = await client.sendSmsWithEmail(
  phoneNumber: '22890909090',
  message: 'Your verification code is 123456',
  email: 'user@example.com',
  subject: 'Verification Code',
);

Check Balance

final balance = await client.checkBalance();

print('Total credits: ${balance.totalCredits}');

for (final country in balance.information) {
  print('${country.country}: ${country.solde} SMS');
}

Configure Callback URL

final config = await client.configureCallback(
  notifyUrl: 'https://yourdomain.com/delivery-report',
  notificationType: NotificationType.post,
);

Handle Delivery Reports

In your webhook endpoint:

// Parse the delivery report from your webhook
final report = AfrikSmsClient.parseDeliveryReport(request.queryParameters);

if (report.isSuccess) {
  print('SMS ${report.resourceId} was delivered successfully!');
} else if (report.isPending) {
  print('SMS ${report.resourceId} is pending delivery');
} else if (report.isFailed) {
  print('SMS ${report.resourceId} failed: ${report.message}');
}

Error Handling

The package provides specific exception types for different errors:

try {
  await client.sendSms(
    phoneNumber: '22890909090',
    message: 'Test message',
  );
} on AuthenticationException catch (e) {
  // Invalid ClientId or ApiKey
  print('Authentication error: ${e.message}');
} on AuthorizationException catch (e) {
  // IP not whitelisted or sender not authorized
  print('Authorization error: ${e.message}');
} on ValidationException catch (e) {
  // Invalid input parameters
  print('Validation error: ${e.message}');
} on NetworkException catch (e) {
  // Connection issues
  print('Network error: ${e.message}');
} on TimeoutException catch (e) {
  // Request timeout
  print('Timeout: ${e.message}');
} on RateLimitException catch (e) {
  // Too many requests
  print('Rate limit exceeded: ${e.message}');
} on AfrikSmsException catch (e) {
  // Any other AfrikSMS error
  print('Error: ${e.message}');
}

Configuration

AfrikSmsConfig

Parameter Type Required Description
clientId String Yes Your unique API identifier
apiKey String Yes Your API authentication key
senderId String Yes Sender name (max 11 characters)
enableLogging bool No Enable debug logging (default: false)
timeout Duration No Request timeout (default: 30 seconds)

Phone Number Format

⚠️ Important: Phone numbers must include the country code without the + or 00 prefix.

✅ Correct: 22890909090
❌ Incorrect: +22890909090, 0022890909090, 90909090

API Endpoints

All endpoints are available through the AfrikSmsClient:

Method Description Max Recipients
sendSms() Send single SMS 1
sendBulkSms() Send same message to multiple recipients 500
sendPersonalizedBulkSms() Send customized messages 500
sendSmsWithEmail() Send SMS with email notification 1
configureCallback() Configure delivery report webhook -
checkBalance() Check account balance -
parseDeliveryReport() Parse delivery report (static) -

Response Models

SmsResponse

  • code - Response code (100 = success)
  • message - Status message
  • resourceId - Unique tracking identifier
  • isSuccess - Convenience property

BulkSmsResponse

  • code - Overall response code
  • message - Status message
  • data - List of individual delivery statuses
  • successCount - Number of successful deliveries
  • failureCount - Number of failed deliveries
  • successfulItems - List of successful items
  • failedItems - List of failed items

BalanceResponse

  • code - Response code
  • message - Status message
  • information - List of country balances
  • totalCredits - Total credits across all countries
  • getBalanceForCountry(country) - Get balance for specific country

DeliveryReport

  • resourceId - Original SMS identifier
  • code - Delivery status code
  • message - Delivery status message
  • status - Enum (success/pending/failed)
  • isSuccess / isPending / isFailed - Convenience properties

Delivery Status Codes

Code Status Description
000 Success Successfully delivered to recipient
001 Pending Sent to operator, awaiting confirmation
002 Failed Number unreachable or reception error

Best Practices

Security

  • Never expose credentials in client-side code
  • Store ClientId and ApiKey in environment variables
  • Use HTTPS for callback URLs
  • Add authentication tokens to webhook URLs

Performance

  • Use bulk endpoints for multiple recipients
  • Implement exponential backoff for retries
  • Monitor rate limits

Message Content

  • Standard SMS: 160 characters
  • Unicode SMS (with emojis/accents): 70 characters
  • Messages exceeding limits are sent as multiple SMS

Testing

  • Test with your own phone number first
  • Verify callback URL receives delivery reports
  • Monitor balance to avoid service interruption

Example Project

A complete example is available in the example directory. Run it with:

cd example
dart run example.dart

Documentation

Support

Issues

If you encounter any issues, please file them on GitHub Issues.

Contact

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes.

Made with ❤️ by 00auth.dev for the AfrikSMS community

Libraries

flutter_afriksms
A powerful and easy-to-use Dart package for integrating AfrikSMS API.