ashrafcodes/wasenderapi-laravel

Laravel package for WasenderAPI WhatsApp sessions, messages, contacts, groups, channels, uploads, and webhooks.

v1.1.0 2026-05-21 16:43 UTC

Requires

• php: ^8.1
• illuminate/contracts: ^10.0|^11.0|^12.0|^13.0
• illuminate/http: ^10.0|^11.0|^12.0|^13.0
• illuminate/routing: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
• phpunit/phpunit: ^10.0|^11.0|^12.0

MIT

README

Laravel package for WasenderAPI, built to help you manage WhatsApp sessions, send messages, handle media, work with contacts, groups, channels, and receive webhooks from Laravel.

العربية

نبذة

هذه الحزمة توفر واجهة Laravel سهلة للتعامل مع WasenderAPI بدل كتابة طلبات HTTP يدويًا في كل مشروع. بعد تثبيتها يمكنك استخدام Facade جاهز مثل:

use AshrafCodes\WasenderApi\Facades\WasenderApi;

WasenderApi::messages()->text('[phone]', 'مرحبا من Laravel');

المتطلبات

• PHP 8.1 أو أحدث
• Laravel 10 أو 11 أو 12 أو 13
• Composer
• حساب WasenderAPI
• Personal Access Token لإدارة الجلسات
• Session API Key لإرسال الرسائل والتعامل مع الجلسة

التثبيت من GitHub

ثبت الحزمة:

composer require ashrafcodes/wasenderapi-laravel:^1.1.0

أو:

composer require ashrafcodes/wasenderapi-laravel:dev-main

بعد التثبيت، انشر ملف الإعدادات:

php artisan vendor:publish --tag=wasenderapi-config

إعداد ملف .env

أضف القيم التالية داخل مشروع Laravel:

WASENDERAPI_BASE_URL=https://www.wasenderapi.com/api
WASENDERAPI_PERSONAL_ACCESS_TOKEN=your_personal_access_token
WASENDERAPI_API_KEY=your_session_api_key
WASENDERAPI_WEBHOOK_SECRET=your_webhook_secret

الفرق بين المفاتيح

• WASENDERAPI_PERSONAL_ACCESS_TOKEN: يستخدم لإدارة الجلسات مثل إنشاء جلسة، عرض الجلسات، إعادة تشغيل جلسة، حذف جلسة، وتجديد API key.
• WASENDERAPI_API_KEY: يستخدم لعمليات الجلسة نفسها مثل إرسال الرسائل، حالة الجلسة، جهات الاتصال، المجموعات، والقنوات.

الحزمة تختار المفتاح المناسب تلقائيًا في أغلب الطرق.

إرسال رسالة نصية

use AshrafCodes\WasenderApi\Facades\WasenderApi;

WasenderApi::messages()->text('[phone]', 'مرحبا من Laravel');

إرسال صورة

WasenderApi::messages()->image(
    to: '[phone]',
    imageUrl: 'https://example.com/image.jpg',
    text: 'صورة مع تعليق'
);

إرسال فيديو

WasenderApi::messages()->video(
    to: '[phone]',
    videoUrl: 'https://example.com/video.mp4',
    text: 'فيديو جديد'
);

إرسال ملف

WasenderApi::messages()->document(
    to: '[phone]',
    documentUrl: 'https://example.com/report.pdf',
    text: 'التقرير',
    fileName: 'report.pdf'
);

إرسال موقع

WasenderApi::messages()->location(
    to: '[phone]',
    latitude: 37.7749,
    longitude: -122.4194,
    name: 'Company HQ',
    address: 'San Francisco'
);

إرسال Poll

WasenderApi::messages()->poll(
    to: '[phone]',
    question: 'ما اللون المفضل؟',
    options: ['Blue', 'Green', 'Red'],
    multiSelect: false
);

أنواع الرسائل المدعومة

• text($to, $text, $extra = [])
• image($to, $imageUrl, $text = null, $extra = [])
• video($to, $videoUrl, $text = null, $extra = [])
• document($to, $documentUrl, $text = null, $fileName = null, $extra = [])
• audio($to, $audioUrl, $extra = [])
• sticker($to, $stickerUrl, $extra = [])
• contactCard($to, $contact, $extra = [])
• location($to, $latitude, $longitude, $name = null, $address = null, $extra = [])
• poll($to, $question, $options, $multiSelect = false, $extra = [])
• quoted($to, $text, $quoted, $extra = [])
• withMentions($to, $text, $mentions, $extra = [])
• viewOnce($to, $media, $extra = [])

إدارة الرسائل

WasenderApi::messages()->info('MESSAGE_ID');
WasenderApi::messages()->edit('MESSAGE_ID', 'النص الجديد');
WasenderApi::messages()->delete('MESSAGE_ID');
WasenderApi::messages()->resend(100000);

WasenderApi::messages()->markAsRead([
    'id' => 'MESSAGE_ID',
    'remoteJid' => '[e-mail]',
    'fromMe' => false,
]);

رفع الوسائط وفك تشفيرها

WasenderApi::messages()->uploadBase64(
    base64: 'data:image/png;base64,iVBORw0KGgo...'
);

WasenderApi::messages()->uploadBinary(
    path: storage_path('app/photo.jpg'),
    mimetype: 'image/jpeg'
);

WasenderApi::messages()->decryptMedia($payload['data']);

إدارة الجلسات

WasenderApi::sessions()->all();

WasenderApi::sessions()->create([
    'name' => 'Main WhatsApp',
    'webhook_url' => 'https://your-app.com/wasenderapi/webhook',
]);

WasenderApi::sessions()->get(1);
WasenderApi::sessions()->update(1, ['name' => 'Sales']);
WasenderApi::sessions()->connect(1);
WasenderApi::sessions()->qrCode(1);
WasenderApi::sessions()->restart(1);
WasenderApi::sessions()->disconnect(1);
WasenderApi::sessions()->delete(1);
WasenderApi::sessions()->messageLogs(1, ['page' => 1]);
WasenderApi::sessions()->logs(1);
WasenderApi::sessions()->regenerateApiKey(1);

عمليات جلسة API key:

WasenderApi::sessions()->status();
WasenderApi::sessions()->user();
WasenderApi::sessions()->isOnWhatsApp('[phone]');
WasenderApi::sessions()->sendPresenceUpdate('[e-mail]', 'typing');

جهات الاتصال

WasenderApi::contacts()->all();
WasenderApi::contacts()->get('[phone]');
WasenderApi::contacts()->picture('[phone]');
WasenderApi::contacts()->block('[phone]');
WasenderApi::contacts()->unblock('[phone]');

WasenderApi::contacts()->createOrUpdate([
    'phone' => '[phone]',
    'name' => 'Customer',
]);

WasenderApi::contacts()->lidFromPhoneNumber('[phone]');
WasenderApi::contacts()->phoneNumberFromLid('lid-value');

المجموعات

WasenderApi::groups()->create('Team', ['[phone]', '[phone]']);
WasenderApi::groups()->all();
WasenderApi::groups()->metadata('[e-mail]');
WasenderApi::groups()->participants('[e-mail]');
WasenderApi::groups()->sendMessage('[e-mail]', 'رسالة للمجموعة');
WasenderApi::groups()->addParticipants('[e-mail]', ['[phone]']);
WasenderApi::groups()->removeParticipants('[e-mail]', ['[phone]']);
WasenderApi::groups()->updateParticipants('[e-mail]', ['[phone]'], 'promote');
WasenderApi::groups()->picture('[e-mail]');
WasenderApi::groups()->inviteLink('[e-mail]');
WasenderApi::groups()->inviteInfo('INVITE_CODE');
WasenderApi::groups()->acceptInvite('INVITE_CODE');
WasenderApi::groups()->leave('[e-mail]');

القنوات

WasenderApi::channels()->sendMessage('120363xxxx@newsletter', 'رسالة للقناة');

WasenderApi::channels()->send([
    'to' => '120363xxxx@newsletter',
    'text' => 'رسالة مخصصة',
]);

الويبهوكس

الحزمة تضيف مسارًا افتراضيًا:

POST /wasenderapi/webhook

عند وصول webhook صحيح، تطلق الحزمة event باسم WasenderWebhookReceived:

use AshrafCodes\WasenderApi\Events\WasenderWebhookReceived;
use Illuminate\Support\Facades\Event;

Event::listen(WasenderWebhookReceived::class, function (WasenderWebhookReceived $event) {
    logger()->info('Wasender event received', [
        'event' => $event->event,
        'data' => $event->data,
    ]);
});

لتغيير مسار الويبهوك:

WASENDERAPI_WEBHOOK_ROUTE_PATH=api/wasender/webhook

لتعطيل المسار الافتراضي وبناء controller خاص بك:

WASENDERAPI_WEBHOOK_ROUTE_ENABLED=false

استخدام endpoint غير موجود كطريقة جاهزة

WasenderApi::get('status');

WasenderApi::post('send-message', [
    'to' => '[phone]',
    'text' => 'رسالة عامة',
]);

WasenderApi::put('contacts', [
    'phone' => '[phone]',
    'name' => 'Ali',
]);

WasenderApi::delete('messages/MESSAGE_ID');

التعامل مع الأخطاء

افتراضيًا، الحزمة ترمي WasenderApiException عند فشل الطلب:

use AshrafCodes\WasenderApi\Exceptions\WasenderApiException;

try {
    WasenderApi::messages()->text('[phone]', 'Hello');
} catch (WasenderApiException $exception) {
    report($exception);
}

لتعطيل رمي الاستثناءات:

WASENDERAPI_THROW=false

لإرجاع headers وحالة HTTP داخل الرد:

WASENDERAPI_INCLUDE_RESPONSE_HEADERS=true

مشاكل شائعة

إذا أردت إزالة الحزمة من مشروع Laravel، لا تكتب رقم الإصدار مع أمر الإزالة:

composer remove ashrafcodes/wasenderapi-laravel

إذا ظهر خطأ أن Composer وجد v1.0.0 فقط ولم يجد ^1.1، فهذا يعني أن مستودع GitHub لا يحتوي tag باسم v1.1.0 أو أحدث. أنشئ tag من مستودع الحزمة ثم ارفعه:

git tag v1.1.0
git push origin v1.1.0

بعدها ثبّت النسخة المستقرة:

composer require ashrafcodes/wasenderapi-laravel:^1.1 -W

إذا أردت استخدام آخر كود من الفرع main بدون tag، ثبّت نسخة التطوير:

composer require ashrafcodes/wasenderapi-laravel:dev-main -W

إذا كان مشروعك يستخدم Laravel/Illuminate أحدث من المدعوم في v1.0.0، لا تثبت ^1.0؛ استخدم dev-main أو أنشئ tag جديد مثل v1.1.0.

إذا كان Composer يستخدم cache قديمًا:

composer clear-cache

إذا لم يجد Composer الحزمة، تأكد من تعريف repository:

composer config repositories.wasenderapi-laravel vcs https://github.com/AshrafCodes/wasenderapi-laravel.git

تشغيل الاختبارات

composer install
vendor/bin/phpunit

English

Overview

This package provides a Laravel-friendly wrapper for WasenderAPI. It lets you manage WhatsApp sessions, send messages, upload and decrypt media, work with contacts, groups, channels, and receive webhook events without writing raw HTTP requests in every project.

Basic usage:

use AshrafCodes\WasenderApi\Facades\WasenderApi;

WasenderApi::messages()->text('[phone]', 'Hello from Laravel');

Requirements

• PHP 8.1 or higher
• Laravel 10, 11, 12, or 13
• Composer
• WasenderAPI account
• Personal Access Token for account/session management
• Session API Key for messaging and session-level operations

Installation From GitHub

Install Packagist:

composer require ashrafcodes/wasenderapi-laravel:^1.1.0

Or:

composer require ashrafcodes/wasenderapi-laravel:dev-main

Publish the configuration file:

php artisan vendor:publish --tag=wasenderapi-config

Environment Configuration

Add these values to your Laravel .env file:

WASENDERAPI_BASE_URL=https://www.wasenderapi.com/api
WASENDERAPI_PERSONAL_ACCESS_TOKEN=your_personal_access_token
WASENDERAPI_API_KEY=your_session_api_key
WASENDERAPI_WEBHOOK_SECRET=your_webhook_secret

Token Types

• WASENDERAPI_PERSONAL_ACCESS_TOKEN: Used for account-level session management, such as creating, listing, restarting, deleting sessions, and regenerating API keys.
• WASENDERAPI_API_KEY: Used for session-level actions, such as sending messages, checking status, contacts, groups, and channels.

The package automatically uses the proper token for the built-in methods.

Send a Text Message

use AshrafCodes\WasenderApi\Facades\WasenderApi;

WasenderApi::messages()->text('[phone]', 'Hello from Laravel');

Send an Image

WasenderApi::messages()->image(
    to: '[phone]',
    imageUrl: 'https://example.com/image.jpg',
    text: 'Image caption'
);

Send a Video

WasenderApi::messages()->video(
    to: '[phone]',
    videoUrl: 'https://example.com/video.mp4',
    text: 'New video'
);

Send a Document

WasenderApi::messages()->document(
    to: '[phone]',
    documentUrl: 'https://example.com/report.pdf',
    text: 'Report file',
    fileName: 'report.pdf'
);

Send a Location

WasenderApi::messages()->location(
    to: '[phone]',
    latitude: 37.7749,
    longitude: -122.4194,
    name: 'Company HQ',
    address: 'San Francisco'
);

Send a Poll

WasenderApi::messages()->poll(
    to: '[phone]',
    question: 'What is your favorite color?',
    options: ['Blue', 'Green', 'Red'],
    multiSelect: false
);

Supported Message Methods

• text($to, $text, $extra = [])
• image($to, $imageUrl, $text = null, $extra = [])
• video($to, $videoUrl, $text = null, $extra = [])
• document($to, $documentUrl, $text = null, $fileName = null, $extra = [])
• audio($to, $audioUrl, $extra = [])
• sticker($to, $stickerUrl, $extra = [])
• contactCard($to, $contact, $extra = [])
• location($to, $latitude, $longitude, $name = null, $address = null, $extra = [])
• poll($to, $question, $options, $multiSelect = false, $extra = [])
• quoted($to, $text, $quoted, $extra = [])
• withMentions($to, $text, $mentions, $extra = [])
• viewOnce($to, $media, $extra = [])

Message Management

WasenderApi::messages()->info('MESSAGE_ID');
WasenderApi::messages()->edit('MESSAGE_ID', 'Updated text');
WasenderApi::messages()->delete('MESSAGE_ID');
WasenderApi::messages()->resend(100000);

WasenderApi::messages()->markAsRead([
    'id' => 'MESSAGE_ID',
    'remoteJid' => '[e-mail]',
    'fromMe' => false,
]);

Media Upload and Decryption

WasenderApi::messages()->uploadBase64(
    base64: 'data:image/png;base64,iVBORw0KGgo...'
);

WasenderApi::messages()->uploadBinary(
    path: storage_path('app/photo.jpg'),
    mimetype: 'image/jpeg'
);

WasenderApi::messages()->decryptMedia($payload['data']);

Session Management

WasenderApi::sessions()->all();

WasenderApi::sessions()->create([
    'name' => 'Main WhatsApp',
    'webhook_url' => 'https://your-app.com/wasenderapi/webhook',
]);

WasenderApi::sessions()->get(1);
WasenderApi::sessions()->update(1, ['name' => 'Sales']);
WasenderApi::sessions()->connect(1);
WasenderApi::sessions()->qrCode(1);
WasenderApi::sessions()->restart(1);
WasenderApi::sessions()->disconnect(1);
WasenderApi::sessions()->delete(1);
WasenderApi::sessions()->messageLogs(1, ['page' => 1]);
WasenderApi::sessions()->logs(1);
WasenderApi::sessions()->regenerateApiKey(1);

Session API key methods:

WasenderApi::sessions()->status();
WasenderApi::sessions()->user();
WasenderApi::sessions()->isOnWhatsApp('[phone]');
WasenderApi::sessions()->sendPresenceUpdate('[e-mail]', 'typing');

Contacts

WasenderApi::contacts()->all();
WasenderApi::contacts()->get('[phone]');
WasenderApi::contacts()->picture('[phone]');
WasenderApi::contacts()->block('[phone]');
WasenderApi::contacts()->unblock('[phone]');

WasenderApi::contacts()->createOrUpdate([
    'phone' => '[phone]',
    'name' => 'Customer',
]);

WasenderApi::contacts()->lidFromPhoneNumber('[phone]');
WasenderApi::contacts()->phoneNumberFromLid('lid-value');

Groups

WasenderApi::groups()->create('Team', ['[phone]', '[phone]']);
WasenderApi::groups()->all();
WasenderApi::groups()->metadata('[e-mail]');
WasenderApi::groups()->participants('[e-mail]');
WasenderApi::groups()->sendMessage('[e-mail]', 'Group message');
WasenderApi::groups()->addParticipants('[e-mail]', ['[phone]']);
WasenderApi::groups()->removeParticipants('[e-mail]', ['[phone]']);
WasenderApi::groups()->updateParticipants('[e-mail]', ['[phone]'], 'promote');
WasenderApi::groups()->picture('[e-mail]');
WasenderApi::groups()->inviteLink('[e-mail]');
WasenderApi::groups()->inviteInfo('INVITE_CODE');
WasenderApi::groups()->acceptInvite('INVITE_CODE');
WasenderApi::groups()->leave('[e-mail]');

Channels

WasenderApi::channels()->sendMessage('120363xxxx@newsletter', 'Channel message');

WasenderApi::channels()->send([
    'to' => '120363xxxx@newsletter',
    'text' => 'Custom channel message',
]);

Webhooks

The package registers this default webhook endpoint:

POST /wasenderapi/webhook

When a valid webhook is received, the package dispatches WasenderWebhookReceived:

use AshrafCodes\WasenderApi\Events\WasenderWebhookReceived;
use Illuminate\Support\Facades\Event;

Event::listen(WasenderWebhookReceived::class, function (WasenderWebhookReceived $event) {
    logger()->info('Wasender event received', [
        'event' => $event->event,
        'data' => $event->data,
    ]);
});

To change the webhook route:

WASENDERAPI_WEBHOOK_ROUTE_PATH=api/wasender/webhook

To disable the default route and use your own controller:

WASENDERAPI_WEBHOOK_ROUTE_ENABLED=false

Calling Custom Endpoints

If WasenderAPI adds an endpoint that does not have a dedicated method yet, use the generic HTTP helpers:

WasenderApi::get('status');

WasenderApi::post('send-message', [
    'to' => '[phone]',
    'text' => 'Generic message',
]);

WasenderApi::put('contacts', [
    'phone' => '[phone]',
    'name' => 'Ali',
]);

WasenderApi::delete('messages/MESSAGE_ID');

Error Handling

By default, failed requests throw WasenderApiException:

use AshrafCodes\WasenderApi\Exceptions\WasenderApiException;

try {
    WasenderApi::messages()->text('[phone]', 'Hello');
} catch (WasenderApiException $exception) {
    report($exception);
}

To disable exceptions:

WASENDERAPI_THROW=false

To include HTTP status and response headers in the returned array:

WASENDERAPI_INCLUDE_RESPONSE_HEADERS=true

Troubleshooting

To remove the package from a Laravel project, do not include a version constraint:

composer remove ashrafcodes/wasenderapi-laravel

If Composer says it found only v1.0.0 and cannot install ^1.1, your GitHub repository does not have a v1.1.0 or newer tag yet. Create and push the tag from the package repository:

git tag v1.1.0
git push origin v1.1.0

Then install the stable version:

composer require ashrafcodes/wasenderapi-laravel:^1.1 -W

If you want to use the latest code from the main branch without a tag, install the development branch:

composer require ashrafcodes/wasenderapi-laravel:dev-main -W

If your project uses a Laravel/Illuminate version newer than what v1.0.0 supports, do not install ^1.0; use dev-main or create a newer tag such as v1.1.0.

If Composer is using stale package metadata:

composer clear-cache

If Composer cannot find the package, make sure the GitHub repository is registered:

composer config repositories.wasenderapi-laravel vcs https://github.com/AshrafCodes/wasenderapi-laravel.git

Testing

composer install
vendor/bin/phpunit

Official WasenderAPI Documentation

• API Docs
• Laravel SDK Docs
• Authentication
• Webhook Setup

License

MIT