PHPackages                             am-sender/am-sender - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. am-sender/am-sender

ActiveLibrary[API Development](/categories/api)

am-sender/am-sender
===================

Laravel package for AM-Sender API integration

v1.1.0(8mo ago)02MITPHPPHP ^8.1

Since Aug 21Pushed 8mo agoCompare

[ Source](https://github.com/AM-naguib/am-sender-laravel-package)[ Packagist](https://packagist.org/packages/am-sender/am-sender)[ Docs](https://github.com/AM-naguib/am-sender-laravel-package)[ RSS](/packages/am-sender-am-sender/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (4)Versions (6)Used By (0)

AM-Sender Laravel Package
=========================

[](#am-sender-laravel-package)

A Laravel package for integrating with the AM-Sender API () to send WhatsApp messages programmatically.

Features
--------

[](#features)

- Easy integration with Laravel 10+
- Auto-discovery support
- Facade-based API
- Comprehensive error handling
- Configurable HTTP client with retry logic
- Device management
- Message sending with support for images

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require am-naguib/am-sender
```

The package will be automatically discovered by Laravel.

Configuration
-------------

[](#configuration)

Publish the configuration file:

```
php artisan vendor:publish --provider="AMSender\AMSenderServiceProvider"
```

This will create a `config/am-sender.php` file. Add your AM-Sender credentials to your `.env` file:

```
AM_SENDER_AUTH_KEY=your-auth-key-here
AM_SENDER_BASE_URL=https://am-sender.com/api
AM_SENDER_TIMEOUT=30
AM_SENDER_RETRY_TIMES=3
AM_SENDER_RETRY_SLEEP=1000
```

Usage
-----

[](#usage)

### Using the Facade

[](#using-the-facade)

```
use AMSender\Facades\AMSender;

// List all devices
try {
    $devices = AMSender::listDevices();
    echo "Devices: " . json_encode($devices);
} catch (\AMSender\Exceptions\AMSenderException $e) {
    echo "Error: " . $e->getMessage();
}

// Create a new device
try {
    $device = AMSender::createDevice('My Device');
    echo "Device created: " . json_encode($device);
} catch (\AMSender\Exceptions\AMSenderException $e) {
    echo "Error: " . $e->getMessage();
}

// Send a message
try {
    $result = AMSender::send([
        'message' => 'Hello from Laravel!',
        'receivers' => ['+1234567890', '+0987654321'],
        'device_ids' => ['device-id-1', 'device-id-2'],
        'delay_time' => 5,
        'image' => 'https://example.com/image.jpg' // optional
    ]);
    echo "Message sent: " . json_encode($result);
} catch (\AMSender\Exceptions\AMSenderException $e) {
    echo "Error: " . $e->getMessage();
}
```

### Using Dependency Injection

[](#using-dependency-injection)

```
use AMSender\AMSender;

class MessageController extends Controller
{
    public function sendMessage(AMSender $amSender)
    {
        try {
            $result = $amSender->send([
                'message' => 'Hello World!',
                'receivers' => ['+1234567890'],
                'device_ids' => ['your-device-id']
            ]);

            return response()->json($result);
        } catch (\AMSender\Exceptions\AMSenderException $e) {
            return response()->json(['error' => $e->getMessage()], 400);
        }
    }
}
```

API Methods
-----------

[](#api-methods)

### listDevices()

[](#listdevices)

Retrieve all devices associated with your account.

```
$devices = AMSender::listDevices();
```

**Returns:**

```
{
    "success": true,
    "devices": [
        {
            "device_id": "device-123",
            "name": "My Device",
            "status": "active",
            "qr": "qr-code-data"
        }
    ]
}
```

### createDevice(string $name)

[](#createdevicestring-name)

Create a new device.

```
$device = AMSender::createDevice('My New Device');
```

**Returns:**

```
{
    "success": true,
    "data": {
        "device_id": "device-456",
        "name": "My New Device",
        "status": "pending",
        "qr": "qr-code-data"
    }
}
```

### send(array $payload)

[](#sendarray-payload)

Send a message to one or more recipients.

```
$result = AMSender::send([
    'message' => 'Your message here',
    'receivers' => ['+1234567890', '+0987654321'],
    'device_ids' => ['device-id-1'],
    'delay_time' => 5, // optional delay in seconds
    'image' => 'https://example.com/image.jpg' // optional image URL
]);
```

**Parameters:**

- `message` (required): The message text to send
- `receivers` (required): Array of phone numbers (with country code)
- `device_ids` (required): Array of device IDs to send from
- `delay_time` (optional): Delay between messages in seconds
- `image` (optional): URL of image to send with the message

**Returns:**

```
{
    "success": true,
    "message": "Message Sent Successfully"
}
```

Input Validation
----------------

[](#input-validation)

The package automatically validates all input data before sending requests to the API. This helps catch errors early and provides clear feedback.

### Validation Rules

[](#validation-rules)

#### Device Name Validation:

[](#device-name-validation)

- **Required**: Cannot be empty
- **Length**: 3-50 characters
- **Characters**: Letters, numbers, spaces, hyphens, and underscores only

#### Message Validation:

[](#message-validation)

- **Required**: Cannot be empty
- **Length**: 3-4096 characters

#### Phone Number Validation:

[](#phone-number-validation)

- **Format**: Flexible format - accepts any phone number format
- **Length**: 5-20 characters
- **Characters**: Numbers, spaces, hyphens, parentheses, and plus sign allowed
- **Auto-Cleaning**: Empty phone numbers are automatically filtered out
- **No Duplicates**: Duplicate numbers are automatically detected

#### Device IDs Validation:

[](#device-ids-validation)

- **Required**: At least one device ID
- **Limit**: Maximum 10 devices per request
- **Length**: 3-100 characters per device ID
- **No Duplicates**: Duplicate device IDs are detected

#### Optional Fields:

[](#optional-fields)

- **delay\_time**: 0-3600 seconds (1 hour max)
- **image**: Valid URL pointing to image file (jpg, jpeg, png, gif, webp, bmp)

### Validation Examples

[](#validation-examples)

```
use AMSender\Facades\AMSender;
use AMSender\Exceptions\ValidationException;

try {
    // This will throw ValidationException - device name too short
    AMSender::createDevice('Hi');
} catch (ValidationException $e) {
    echo $e->getMessage(); // "Device name must be at least 3 characters long."
}

try {
    // This will throw ValidationException - phone number too short
    AMSender::send([
        'message' => 'Hello!',
        'receivers' => ['123'], // Too short
        'device_ids' => ['device-1']
    ]);
} catch (ValidationException $e) {
    echo $e->getMessage(); // "Phone number at index 0 is too short. Minimum 5 characters required."
}

try {
    // This will throw ValidationException - message too short
    AMSender::send([
        'message' => 'Hi', // Too short
        'receivers' => ['+1234567890'],
        'device_ids' => ['device-1']
    ]);
} catch (ValidationException $e) {
    echo $e->getMessage(); // "Message must be at least 3 characters long."
}

// Valid example
try {
    $result = AMSender::send([
        'message' => 'Hello from Laravel!',
        'receivers' => ['+1234567890', '+0987654321'],
        'device_ids' => ['device-1'],
        'delay_time' => 5,
        'image' => 'https://example.com/image.jpg'
    ]);
    echo "Message sent successfully!";
} catch (ValidationException $e) {
    echo "Validation error: " . $e->getMessage();
}
```

Image Handling
--------------

[](#image-handling)

The package provides comprehensive image URL validation and helpful error messages for image-related issues.

### Image URL Requirements:

[](#image-url-requirements)

- Must be publicly accessible (no localhost or private URLs)
- Must use HTTP or HTTPS protocol
- Should point to a valid image file (jpg, jpeg, png, gif, webp, bmp, svg)
- Maximum URL length: 2048 characters

### Common Image Issues and Solutions:

[](#common-image-issues-and-solutions)

```
use AMSender\Facades\AMSender;
use AMSender\Exceptions\InvalidImageException;
use AMSender\Helpers\ImageHelper;

try {
    $result = AMSender::send([
        'message' => 'Check this image!',
        'receivers' => ['+1234567890'],
        'device_ids' => ['device-1'],
        'image' => 'https://example.com/image.jpg'
    ]);
} catch (InvalidImageException $e) {
    echo "Image error: " . $e->getMessage();

    // Get suggestions for fixing the URL
    $suggestions = ImageHelper::getImageUrlSuggestions('https://example.com/image.jpg');
    foreach ($suggestions as $suggestion) {
        echo "- " . $suggestion . "\n";
    }
}

// Test an image URL before sending
$imageUrl = 'https://example.com/image.jpg';
$testResult = ImageHelper::testImageUrl($imageUrl);

if (!$testResult['is_accessible']) {
    echo "Image URL is not accessible\n";
    foreach ($testResult['errors'] as $error) {
        echo "Error: " . $error . "\n";
    }
}

if ($testResult['warnings']) {
    foreach ($testResult['warnings'] as $warning) {
        echo "Warning: " . $warning . "\n";
    }
}
```

### Image Error Messages:

[](#image-error-messages)

```
// Common error scenarios:

// 1. URL not accessible
"Image URL is not accessible. Please check: 1) URL is publicly accessible, 2) URL points to a valid image file, 3) Image server allows external access."

// 2. Invalid file type
"The provided URL does not point to a valid image file. Please ensure the URL ends with a valid image extension (jpg, jpeg, png, gif, webp, bmp)."

// 3. URL format issues
"Image must be a valid URL format."
"Image URL must use HTTP or HTTPS protocol."
```

Exception Handling
------------------

[](#exception-handling)

The package provides specific exception classes for different error scenarios:

- `AMSenderException` - Base exception class
- `UserNotFoundException` - User not found
- `SubscriptionExpiredException` - Subscription has expired
- `DeviceNotFoundException` - Device not found or inactive
- `InvalidImageException` - Invalid or inaccessible image URL
- `AuthKeyNotValidException` - Invalid authentication key
- `LimitExceededException` - API limits exceeded
- `ValidationException` - Input validation errors (422 status code)

```
use AMSender\Exceptions\SubscriptionExpiredException;
use AMSender\Exceptions\DeviceNotFoundException;

try {
    $result = AMSender::send($payload);
} catch (SubscriptionExpiredException $e) {
    // Handle subscription expiry
    echo "Your subscription has expired: " . $e->getMessage();
} catch (DeviceNotFoundException $e) {
    // Handle device issues
    echo "Device error: " . $e->getMessage();
} catch (\AMSender\Exceptions\AMSenderException $e) {
    // Handle other AM-Sender errors
    echo "AM-Sender error: " . $e->getMessage();
}
```

Configuration Options
---------------------

[](#configuration-options)

The `config/am-sender.php` file provides several configuration options:

```
return [
    // API base URL
    'base_url' => env('AM_SENDER_BASE_URL', 'https://am-sender.com/api'),

    // Your authentication key
    'auth_key' => env('AM_SENDER_AUTH_KEY'),

    // Request timeout in seconds
    'timeout' => env('AM_SENDER_TIMEOUT', 30),

    // Retry configuration
    'retry' => [
        'times' => env('AM_SENDER_RETRY_TIMES', 3),
        'sleep' => env('AM_SENDER_RETRY_SLEEP', 1000),
    ],
];
```

Best Practices
--------------

[](#best-practices)

### Input Sanitization

[](#input-sanitization)

The package automatically trims whitespace from all string inputs and validates data formats. However, you should still sanitize your inputs before passing them to the package.

### Error Handling

[](#error-handling)

Always wrap your API calls in try-catch blocks to handle both validation errors and API errors gracefully:

```
use AMSender\Facades\AMSender;
use AMSender\Exceptions\ValidationException;
use AMSender\Exceptions\AMSenderException;

try {
    $result = AMSender::send($payload);
    // Handle success
} catch (ValidationException $e) {
    // Handle validation errors (400-level errors)
    Log::warning('Validation error: ' . $e->getMessage());
} catch (AMSenderException $e) {
    // Handle API errors (500-level errors)
    Log::error('API error: ' . $e->getMessage());
}
```

### Phone Number Formatting

[](#phone-number-formatting)

The package accepts flexible phone number formats and automatically filters out empty numbers:

```
// ✅ All these formats are accepted
$receivers = [
    '+1234567890',      // International format
    '01234567890',      // Local format
    '123-456-7890',     // With hyphens
    '(123) 456-7890',   // With parentheses
    '123 456 7890',     // With spaces
    '',                 // Empty - will be filtered out automatically
    '   ',              // Whitespace only - will be filtered out
];

// Result: Empty numbers are automatically removed
// Final receivers: ['+1234567890', '01234567890', '123-456-7890', '(123) 456-7890', '123 456 7890']
```

### Batch Processing

[](#batch-processing)

For large recipient lists, consider breaking them into smaller batches:

```
$allReceivers = ['+1111111111', '+2222222222', /* ... many more */];
$chunks = array_chunk($allReceivers, 100); // Process 100 at a time

foreach ($chunks as $chunk) {
    try {
        AMSender::send([
            'message' => 'Bulk message',
            'receivers' => $chunk,
            'device_ids' => ['device-1'],
            'delay_time' => 2 // Add delay between batches
        ]);
        sleep(5); // Wait between batches to avoid rate limits
    } catch (Exception $e) {
        Log::error("Batch failed: " . $e->getMessage());
    }
}
```

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 10.0 or higher
- Guzzle HTTP client

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

Support
-------

[](#support)

For support and questions about the AM-Sender API, please visit .

For package-specific issues, please create an issue in the repository.

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance59

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

5

Last Release

261d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/bc6ad6477afcd2c5f800039df2156271fbb0073c1155a6d80f792e5f2b30f1dc?d=identicon)[AM-naguib](/maintainers/AM-naguib)

---

Top Contributors

[![AM-naguib](https://avatars.githubusercontent.com/u/132526024?v=4)](https://github.com/AM-naguib "AM-naguib (5 commits)")

---

Tags

apilaravelsmsmessagingwhatsappam-sender

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/am-sender-am-sender/health.svg)

```
[![Health](https://phpackages.com/badges/am-sender-am-sender/health.svg)](https://phpackages.com/packages/am-sender-am-sender)
```

###  Alternatives

[openai-php/laravel

OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API

3.7k7.6M74](/packages/openai-php-laravel)[scriptdevelop/whatsapp-manager

Paquete para manejo de WhatsApp Business API en Laravel

762.6k](/packages/scriptdevelop-whatsapp-manager)[nickurt/laravel-postcodeapi

Universal PostcodeApi for Laravel 11.x/12.x/13.x

97221.2k](/packages/nickurt-laravel-postcodeapi)[mozex/anthropic-laravel

Anthropic PHP for Laravel is a supercharged PHP API client that allows you to interact with the Anthropic API

71226.4k1](/packages/mozex-anthropic-laravel)[ardakilic/mutlucell

Mutlucell SMS API wrapper for sending sms text messages for Laravel

457.3k](/packages/ardakilic-mutlucell)[crenspire/laravel-whatsapp

Laravel WhatsApp Business API package

133.0k](/packages/crenspire-laravel-whatsapp)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)