Download the PHP package renderbit/laravel-whatsapp without Composer

Laravel WhatsApp (renderbit/laravel-whatsapp)

A framework-agnostic, Laravel-ready PHP package for sending template-based WhatsApp messages via the Renderbit WhatsApp API.

🚀 Features

• ✅ Works with Laravel 10/11, Symfony, Slim, or any PHP 8.1+ app
• 🔐 PSR-16 token caching — automatic token generation, caching, and refresh with configurable TTL
• 📄 Template-based messaging — pass template IDs with dynamic parameters
• 🧠 51 built-in error codes — maps API error codes to human-readable messages
• 🧰 PSR-compliant — PSR-3 logging, PSR-16 caching, PSR-4 autoloading
• 📡 DLR endpoint — built-in delivery report webhook route
• 🧪 100% test coverage — PHPUnit test suite with CI on 6 matrix configurations
• 🔌 Laravel auto-discovery — service provider auto-registers, facade ready to use

📦 Installation

Requirements

⚙️ Laravel Setup

Note: This package uses Laravel auto-discovery, so the service provider is registered automatically. No manual registration needed.

1. Publish Config (optional)

This publishes the config file and routes to your application:

• config/whatsapp.php — configuration values
• routes/vendor/whatsapp-api.php — DLR webhook route

2. Environment Configuration

Add these to your .env:

Configuration Reference (config/whatsapp.php)

🧱 Usage

In Laravel

Via Dependency Injection

Via Facade

Via app() Helper

Response Format

All sendMessage() calls return a uniform response array:

In Standalone PHP

🔐 Token Management

The TokenManager class handles all authentication token lifecycle automatically.

How it works:

1. getToken() checks PSR-16 cache for a valid (non-expired) token
2. If cached and valid, returns immediately
3. If expired or missing, calls generateToken() which requests a new token from the API
4. The new token and its expiry are stored in cache with the correct TTL (in seconds)
5. On HTTP 401 responses, WhatsappClient::sendRequest() automatically triggers refreshToken()

You can swap the cache backend to Redis, APCu, database, or any PSR-16 implementation.

📡 DLR Webhook

The package registers a POST route for delivery reports:

The WhatsAppDLRController::receiveDLR() handler logs incoming delivery reports via Laravel's Log::info() and responds with {"status": "success"}.

To customize, extend the controller or disable the routes and define your own:

🗺 Error Code Reference

The package ships with 51 mapped error codes in Renderbit\LaravelWhatsapp\Constants\ErrorCodes:

You can customize messages by extending or modifying the ErrorCodes::MAP array.

🧪 Testing

The test suite covers:

• WhatsappClient — message sending, error handling, HTTP failures, token exhaustion
• TokenManager — cache hit/miss, token generation, refresh, invalid actions
• WhatsAppDLRController — DLR endpoint acceptance
• WhatsappServiceProvider — config merge, singleton binding, facade alias, publishable tags
• Whatsapp Facade — accessor resolution
• ErrorCodes — all 51 error codes validated

CI Matrix

The package is tested via GitHub Actions across 6 configurations:

📁 Project Structure

🧩 Extending & Customization

• Error messages — Modify src/Constants/ErrorCodes.php to localize or customize API error messages
• Cache backend — The PSR-16 CacheInterface can be swapped for Redis, APCu, Memcached, or any compliant adapter
• Logger — The PSR-3 LoggerInterface supports Monolog, Loggly, Laravel's Log facade, etc.
• DLR handling — Extend WhatsAppDLRController to implement custom delivery report logic (store in DB, forward to webhook, etc.)
• HTTP client — GuzzleHttp\Client is used internally; customize timeouts/headers in WhatsappClient::__construct()

🤝 Contributing

1. Fork the repository
2. Install dependencies: composer install
3. Write/run tests: vendor/bin/phpunit
4. Submit a pull request

Please ensure all tests pass and maintain at least the current coverage level.

📄 License

MIT © Renderbit Technologies