ziming / laravel-crisp-whatsapp
This is my package laravel-crisp-whatsapp
Fund package maintenance!
ziming
Requires
- php: ^8.4
- illuminate/contracts: ^10.0||^11.0||^12.0
- spatie/laravel-data: ^4.15
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^2.9||^3.0
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.1.1||^7.10.0
- orchestra/testbench: ^10.0.0||^9.0.0||^8.22.0
- pestphp/pest: ^3.0
- pestphp/pest-plugin-arch: ^3.0
- pestphp/pest-plugin-laravel: ^3.0
- phpstan/extension-installer: ^1.3||^2.0
- phpstan/phpstan-deprecation-rules: ^1.1||^2.0
- phpstan/phpstan-phpunit: ^1.3||^2.0
- spatie/laravel-ray: ^1.35
README
Send WhatsApp Notifications with Crisp!
This package is still in testing phase, so I do not recommend it for production use yet
Support us
You can donate to my github sponsor account.
Installation
You can install the package via composer:
composer require ziming/laravel-crisp-whatsapp
You may publish the config file with:
php artisan vendor:publish --tag="crisp-whatsapp-config"
This is the contents of the published config file:
declare(strict_types=1); return [ 'website_id' => env('CRISP_WEBSITE_ID'), 'base_url' => env('CRISP_BASE_URL', 'https://plugins.crisp.chat/urn:crisp.im:whatsapp:0/wa/api/website/'), 'access_key_id' => env('CRISP_WHATSAPP_ACCESS_KEY_ID'), 'secret_access_key' => env('CRISP_WHATSAPP_SECRET_ACCESS_KEY'), 'from_phone' => env('CRISP_WHATSAPP_FROM_PHONE'), // change it to false when you are ready for production 'test_mode' => env('CRISP_WHATSAPP_TEST_MODE', true), // when test_mode is true, all whatsapp notifications will go to this number 'to_test_phone' => env('CRISP_WHATSAPP_TO_TEST_PHONE'), 'enable_caching' => env('CRISP_WHATSAPP_ENABLE_CACHE', true), ];
Quick Usage (More documentation in the future!)
Here are some examples on how you can use it in a laravel notification class.
Quick Example
declare(strict_types=1); use Ziming\LaravelCrispWhatsApp\Enums\ParameterTypeEnum; use Ziming\LaravelCrispWhatsApp\CrispWhatsAppChannel; use Ziming\LaravelCrispWhatsApp\Enums\ParameterTypeEnum; use Ziming\LaravelCrispWhatsApp\CrispWhatsAppMessage; use Ziming\LaravelCrispWhatsApp\Interfaces\CrispWhatsAppNotification; use Ziming\LaravelCrispWhatsApp\CanReceiveCrispWhatsAppNotification; use Ziming\LaravelCrispWhatsApp\Factories\ComponentParameterFactory; use Ziming\LaravelCrispWhatsApp\Factories\ComponentFactory; use Ziming\LaravelCrispWhatsApp\Enums\ButtonSubTypeEnum; use Ziming\LaravelCrispWhatsApp\LaravelCrispWhatsApp; use Ziming\LaravelCrispWhatsApp\Facades\LaravelCrispWhatsApp as LaravelCrispWhatsAppFacade; class OrderShippedNotification extends Notification implements CrispWhatsAppNotification { use Queueable; public function via(CanReceiveCrispWhatsAppNotification $notifiable): array { return [ CrispWhatsAppChannel::class; ]; } public function toCrispWhatsApp(CanReceiveCrispWhatsAppNotification $notifiable): CrispWhatsAppMessage { $templateArray = LaravelCrispWhatsAppFacade::getMessageTemplateArray('hello_world'); return CrispWhatsAppMessageFactory::createFromTemplateArray( $templateArray, [ ComponentParameterFactory::text('Crispy Fries'), ], ); } }
Detailed Example
declare(strict_types=1); use Ziming\LaravelCrispWhatsApp\Enums\ParameterTypeEnum; use Ziming\LaravelCrispWhatsApp\CrispWhatsAppChannel; use Ziming\LaravelCrispWhatsApp\Enums\ParameterTypeEnum; use Ziming\LaravelCrispWhatsApp\CrispWhatsAppMessage; use Ziming\LaravelCrispWhatsApp\Interfaces\CrispWhatsAppNotification; use Ziming\LaravelCrispWhatsApp\CanReceiveCrispWhatsAppNotification; use Ziming\LaravelCrispWhatsApp\Factories\ComponentParameterFactory; use Ziming\LaravelCrispWhatsApp\Factories\ComponentFactory; use Ziming\LaravelCrispWhatsApp\Enums\ButtonSubTypeEnum; use Ziming\LaravelCrispWhatsApp\LaravelCrispWhatsApp; use Ziming\LaravelCrispWhatsApp\Facades\LaravelCrispWhatsApp as LaravelCrispWhatsAppFacade; class OrderShippedNotification extends Notification implements CrispWhatsAppNotification { use Queueable; public function via(CanReceiveCrispWhatsAppNotification $notifiable): array { return [ CrispWhatsAppChannel::class; ]; } public function toCrispWhatsApp(CanReceiveCrispWhatsAppNotification $notifiable): CrispWhatsAppMessage { // See the source code for more methods on CrispWhatsAppMessage! $crispMessages = [] // Example 1 $crispMessages[] = CrispWhatsAppMessage::make() ->templateLanguage('en') ->toNumber($notifiable->mobile_phone) ->templateName('template-name') ->addTemplateBodyComponent( LaravelCrispWhatsApp::make()->getMessageTemplateBodyText('template-name'), [ ComponentParameterFactory::text('Crisp'), ] ) ->addTemplateFooterComponent( // you may use the facade as well! LaravelCrispWhatsAppFacade::getMessageTemplateFooterText('template-name') ) ->addTemplateButtonComponent('CTA', ButtonSubTypeEnum::Url) ->addTemplateButtonComponent('Not interested anymore'); // Example 2 $crispMessages[] = CrispWhatsAppMessage::make() ->rawMessageTemplate([ 'language' => 'en_US', 'name' => 'hello_world', 'components' => [ [ 'type' => 'HEADER', 'FORMAT' => 'TEXT', 'text' => 'Hello World', ], [ 'type' => 'BODY', 'text' => 'This is a body text', ], [ 'type' => 'FOOTER', 'text' => 'This is a footer text', ], ], ]); // Example 3 $crispMessages[] => CrispWhatsAppMessage::make() ->templateLanguage('en') ->toNumber($notifiable->mobile_phone) ->rawTemplateComponents([ ComponentFactory::headerText('Order #12345'), ComponentFactory::body('{{1}} the Builder', ComponentParameterFactory::text('Crisp')), ComponentFactory::button('Call To Action', ButtonSubTypeEnum::Url) ComponentFactory::button('No', ButtonSubTypeEnum::QuickReply) ComponentFactory::footer('This is the footer of your whatsapp template'), ]); return $crispMessages[random_int(0, 2)]; } }
Then in your model classes that can receive WhatsApp notifications, you can use the CanReceiveWhatsAppNotification
trait:
Below is an example:
use Illuminate\Database\Eloquent\Model; use Ziming\LaravelCrispWhatsApp\Interfaces\CanReceiveCrispWhatsAppNotification; class User extends Model implements CanReceiveCrispWhatsAppNotification { public function routeNotificationForCrispWhatsApp(): string { return $this->attributes['mobile_phone']; } }
Caching
Caching is enabled by default. You can disable it by setting the CRISP_WHATSAPP_ENABLE_CACHING
environment variable to false
.
When caching is enabled, the package will cache the message template for an hour. This is to reduce the number of API calls made to Crisp.
This package also uses the spatie/laravel-data
package to build the data objects. You may wish to refer its structure caching documentation too.
Why are the classes final?
This is selfish on my part, my hope is that it would incentivise you to make a pull request so that everyone would benefit. I will also get to know more about where my package is lacking especially in the early days of this library.
Testing
Sending whatsapp messages costs money. Hence there are no tests. So if there are issues, just create an issue to let me know or make a PR fix for it :)
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.