noti_fire_api 0.0.5

A Flutter package for interacting with the Noti Fire WhatsApp API.

Noti Fire API

A Flutter package for seamless integration with the Noti Fire WhatsApp API, a powerful platform for sending WhatsApp messages programmatically. This package allows developers to send text messages, media (images, videos, audio, PDFs), contacts, locations, and group messages with ease, while supporting web and mobile platforms.

Features

• Text Messages: Send messages to individual WhatsApp numbers.
• Bulk Messages: Send a single message to multiple recipients.
• Media Messages: Send images, videos, audio, and PDFs via URL or file upload.
• Voice Notes: Send audio as voice notes.
• Contacts: Share contact information as vCards.
• Locations: Share geographical coordinates as location pins.
• Group Messages: Send various message types to WhatsApp groups.
• Automated Replies: Support for webhook-based auto-replies (configure via dashboard).
• Error Handling: Structured error responses with custom NotiFireException.
• Platform Compatibility: Optimized file uploads using Uint8List for web and File for mobile.

Installation

Add the package and dependencies to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  noti_fire_api: ^0.0.5


Run flutter pub get to install the dependencies.
Assets (Optional)
For testing with assets, add them to pubspec.yaml:
flutter:
  assets:
    - assets/images/test.png



Sign Up for a Free Trial:

Create an account at https://noti-fire.com .
Connect your WhatsApp number by scanning a QR code to obtain a unique device_id.
Enjoy a 4-day free trial with full access to all features.


Initialize NotiFireService:
import 'package:noti_fire_api/noti_fire_api.dart';

final notiFireService = NotiFireService(
  deviceId: 'xxxxxxxx-xxxx-xxxx-xxxxx-xxxxxxxxxxxx', // Replace with your device ID
);

Optionally, provide a custom Dio instance:
import 'package:dio/dio.dart';

final dio = Dio(BaseOptions(
  baseUrl: 'https://noti-fire.com/api',
  headers: {'Custom-Header': 'value'},
));
final notiFireService = NotiFireService(deviceId: 'your-device-id', dio: dio);



Usage
The NotiFireService class provides methods to interact with the Noti Fire WhatsApp API. All methods return a Future<MessageResponse> or throw a NotiFireException on error.
Methods

sendTextMessage: Send a text message to a single recipient.
sendBulkMessages: Send a text message to multiple recipients.
sendMediaUrl: Send media using a URL.
sendMedia: Send media using raw Uint8List (web-optimized).
sendMediaFromFile: Send media using a File (mobile-optimized).
sendContact: Share a contact as a vCard.
sendLocation: Share a location pin.
sendGroupMessage: Send messages to a WhatsApp group.

Example Usage
Below are examples using the API base URL https://noti-fire.com/api and a sample device ID.
Send Text Message
try {
  final response = await notiFireService.sendTextMessage(
    to: '+20xxxxxxxxx',
    message: 'Hello from Noti Fire API!',
  );
  print('Success: ${response.messageId}');
} catch (e) {
  print('Error: $e');
}

Send Bulk Messages
try {
  final response = await notiFireService.sendBulkMessages(
    message: 'Hello everyone!',
    numbers: ['+20xxxxxxxxx', '+20xxxxxxxxx'],
  );
  print('Success: ${response.messageId}');
} catch (e) {
  print('Error: $e');
}

Send Media (URL)
try {
  final response = await notiFireService.sendMediaUrl(
    to: '+20xxxxxxxxx',
    type: 'image',
    mediaUrl: 'https://example.com/image.jpg',
    caption: 'Test image',
  );
  print('Success: ${response.messageId}');
} catch (e) {
  print('Error: $e');
}

Send Media (File Upload - Web)
For web, use sendMedia with Uint8List from file_picker:
import 'package:file_picker/file_picker.dart';
import 'package:flutter/foundation.dart' show kIsWeb;

final result = await FilePicker.platform.pickFiles(
  type: FileType.custom,
  allowedExtensions: ['jpg', 'jpeg', 'png', 'gif', 'mp4', 'mov', 'avi', 'mkv', 'mp3', 'wav', 'pdf'],
  allowMultiple: false,
);

if (result != null && result.files.single.bytes != null && kIsWeb) {
  try {
    final response = await notiFireService.sendMedia(
      to: '+20xxxxxxxxx',
      bytes: result.files.single.bytes!,
      fileName: result.files.single.name,
      caption: 'Test media (web)',
    );
    print('Success: ${response.messageId}');
  } catch (e) {
    print('Error: $e');
  }
}

Send Media (File Upload - Mobile)
For mobile, use sendMediaFromFile with a File:
import 'package:file_picker/file_picker.dart';
import 'package:universal_io/io.dart';

final result = await FilePicker.platform.pickFiles(
  type: FileType.custom,
  allowedExtensions: ['jpg', 'jpeg', 'png', 'gif', 'mp4', 'mov', 'avi', 'mkv', 'mp3', 'wav', 'pdf'],
  allowMultiple: false,
);

if (result != null && result.files.single.path != null) {
  try {
    final file = File(result.files.single.path!);
    final response = await notiFireService.sendMediaFromFile(
      to: '+20xxxxxxxxx',
      file: file,
      caption: 'Test media (mobile)',
    );
    print('Success: ${response.messageId}');
  } catch (e) {
    print('Error: $e');
  }
}

Send Contact
try {
  final response = await notiFireService.sendContact(
    to: '+20xxxxxxxxx',
    contactName: 'John Doe',
    contactPhone: '[phone]',
  );
  print('Success: ${response.messageId}');
} catch (e) {
  print('Error: $e');
}

Send Location
try {
  final response = await notiFireService.sendLocation(
    to: '+20xxxxxxxxx',
    latitude: 30.4589847,
    longitude: 31.1472218,
  );
  print('Success: ${response.messageId}');
} catch (e) {
  print('Error: $e');
}

Send Group Message
try {
  final response = await notiFireService.sendGroupMessage(
    groupId: '120363406573708642',
    type: 'text',
    text: 'Hello group members!',
  );
  print('Success: ${response.messageId}');
} catch (e) {
  print('Error: $e');
}

Error Handling
Methods throw a NotiFireException with a message and optional status code. Common errors include:

400 Bad Request: Invalid parameters (e.g., unsupported file type, exceeded length limits).
401 Unauthorized: Invalid device ID.
403 Forbidden: Device not connected or suspended.
429 Too Many Requests: Exceeded 60 requests/minute limit.
500 Internal Server Error: Server-side issue (contact support).

Example:
try {
  await notiFireService.sendTextMessage(to: '+20xxxxxxxxx', message: 'Test');
} on NotiFireException catch (e) {
  print('Error: ${e.message} (Status: ${e.statusCode})');
}

API Constraints

Base URL: https://noti-fire.com/api
Rate Limit: 60 requests per minute.
File Size: Max 10MB for media uploads.
Supported Formats: JPEG, PNG, JPG, GIF, MP4, MOV, AVI, MKV, MP3, WAV, PDF.
Max Lengths:
Phone numbers (to, contact_phone): 20 characters.
Message, caption: 5000 characters.
Media URL: 1000 characters.
File name (PDF only): 100 characters.
Contact name: 25 characters.
Group ID: 50 characters.



Free Trial and Pricing

Free Trial: Sign up at https://noti-fire.com/ for a 4-day trial with full access to all features, including unlimited messages and webhook support.
Pricing Plans:
Basic Plan: Affordable option for sending unlimited messages to individuals and groups, with basic webhook and auto-reply features.
Professional Plan: Includes advanced features like multiple auto-replies and active ad campaigns.
Custom Plan: Tailored solutions for specific needs (contact sales for details).
Visit https://noti-fire.com for more information.



Testing
The package includes an example app (example/main.dart) to test all methods:

Ensure assets are set up (e.g., assets/images/test.png).
Run on web:flutter run -d chrome


Test file uploads using sendMedia with Uint8List.


Run on mobile:flutter run


Test file uploads using sendMediaFromFile with File.


The app displays an image preview for selected image files (JPG, JPEG, PNG, GIF).

Webhook and Auto-Replies
Configure webhooks and automated replies via the Noti Fire dashboard to handle incoming messages and integrate with CRMs or e-commerce platforms. See the API documentation for details.
Contact

Support: Reach out via WhatsApp at [phone] 
Documentation: https://noti-fire.com/documentation

License
MIT License```