README

A Laravel package for the Whatsapp Business Cloud API.

• Installation
• Configuration
• Usage
  • Media
  • Business profile
• Notification Channel
• License

Installation

composer require logicalcrow/laravel-whatsapp-api

Configuration

You will need to set the WHATSAPP_TOKEN and WHATSAPP_NUMBER_ID values in your .env.

For further configuration, please see config/whatsapp.php. You can modify the configuration by copying it to your local config directory or by defining the environment variables used in the config file:

php artisan vendor:publish --provider="Logicalcrow\Whatsapp\WhatsappServiceProvider" --tag=config

Usage

You can send a messages to a single or multiple clients.

use Logicalcrow\Whatsapp\Messages;

Whatsapp::send('13333333333', Messages\TemplateMessage::create()
    ->name('one_time_password')
    ->language('en_US')
    ->body(Messages\Components\Body::create([
        Messages\Components\Parameters\Text::create('000000'),
    ])));

You can also respond to other messages in the conversation with any message type (except reaction message):

use Logicalcrow\Whatsapp\Messages\TextMessage;

Whatsapp::send('13333333333', TextMessage::create('Answer to your message')->respondTo('wamid.91n23...'));

and you can mark messages as read:

Whatsapp::markRead('wamid.91n23...');

By default the messages will be sent from the default_number_id, if you want to use other you can use Whatsapp::numberId() or add the alias to the config's numbers list and use Whatsapp::numberName(). Also you can set the token manually with Whatsapp::token() or you can set both the token and numberId you can use Whatsapp::client()

Supported messages

• Text Message
• Media Message
• Template Message
• Reaction Message
• Contacts Message
• Interactive Message
• Location Message

Media

You can also manage media with:

Whatsapp::uploadMedia(string $file, string $type = null, bool $retrieveAllData = true): \Logicalcrow\Whatsapp\WhatsappMedia|string
Whatsapp::getMedia(string $mediaId, bool $download = false): \Logicalcrow\Whatsapp\WhatsappMedia
Whatsapp::deleteMedia(\Logicalcrow\Whatsapp\WhatsappMedia|string $id): bool
Whatsapp::downloadMedia(string|\Logicalcrow\Whatsapp\WhatsappMedia $media): \Logicalcrow\Whatsapp\WhatsappMedia

Business Profile

There are also two ways to manage the number's business profile:

Whatsapp::getProfile(): \Logicalcrow\Whatsapp\BusinessProfile
Whatsapp::updateProfile(\Logicalcrow\Whatsapp\BusinessProfile|array $data): bool

Webhooks

Whatsapp allows you to subscribe to webhooks to receive notifications and most importantly messages from your customers. Both subscriptions and notifications are handled out of the box in the route whatsapp/webhook (you can change the path with the WHATSAPP_WEBHOOK_PATH env variable).

When a you register the webhook meta will send a subscription, this requires a verification token that you set, you will need to set it with WHATSAPP_WEBHOOK_VERIFY_TOKEN env setting. When receiving a subscription intent a Logicalcrow\Whatsapp\Events\SubscriptionIntentReceived event will be fired, if the request is successful the Logicalcrow\Whatsapp\Events\SuccessfullySubscribed event will fire too.

On the other hand notifications will trigger a Logicalcrow\Whatsapp\Events\WebhookReceived event with all the payload, if you want to protect this route verifying the sha256 signature you must set the WHATSAPP_WEBHOOK_SIGNATURE_VERIFY to true and the WHATSAPP_SECRET to your whatsapp's app secret.

If the payload is invalid a Logicalcrow\Whatsapp\Events\UnprocessableWebhookPayload event will be fired with the exception describing the error.

If you want to know when a specific notification is fired you can subscribe to this events:

• Logicalcrow\Whatsapp\Events\WebhookEntry generic entry
• Logicalcrow\Whatsapp\Events\MessagesReceived for the messages entry

Notification Channel

This library has support for channel notification, just add the routeNotificationForWhatsapp() function to the Notifiable user (it can return a single whatsapp_id or an array of them):

class User extends Authenticatable
{
    use Notifiable;

    /**
     * @return string|array
     */
    public function routeNotificationForWhatsapp(): string|array
    {
        return "{$this->phone_code}{$this->phone}";
    }
}

Now just create a notification that implements the toWhatsapp() function:

//...
use Logicalcrow\Whatsapp\Messages\TemplateMessage;
use Logicalcrow\Whatsapp\Messages\Components\Parameters;
use Logicalcrow\Whatsapp\WhatsappChannel;

class VerificationCode extends Notification
{
    use Queueable;

    /**
     * Create a new notification instance.
     *
     * @return void
     */
    public function __construct(protected string $code)
    {
        //
    }

    /**
     * Get the notification's delivery channels.
     *
     * @param  mixed  $notifiable
     * @return array
     */
    public function via($notifiable)
    {
        return [WhatsappChannel::class];
    }

    /**
     * Get the message representation of the notification.
     *
     * @param  mixed  $notifiable
     * @return \Logicalcrow\Whatsapp\Messages\WhatsappMessage
     */
    public function toWhatsapp($notifiable)
    {
        return TemplateMessage::create('one_time_password')
            ->language('en_US')
            ->body([
                Parameters\Text::create('123456'),
            ]);
    }
}

Now you can send whatsapp notifications:

$user->notify(new VerificationCode('12345678'));

Configuration file

return [
    /**
     * The whatsapp token to be used.
     */
    'token' => env('WHATSAPP_TOKEN'),

    /**
     * The whatsapp's app secret code. Required for webhook request signature verification.
     */
    'secret' => env('WHATSAPP_SECRET'),

    /**
     * The default NUMBER ID used to send the messages.
     */
    'default_number_id' => env('WHATSAPP_NUMBER_ID'),

    /**
     * If you want to use other number id's you can add them here so you can call
     * `numberName` with the name you provide here and make it easier to change
     * the phone where the messages are sended.
     */
    'numbers' => [
        // 'fallback' => env('WHATSAPP_FALLBACK_NUMBER_ID'),
    ],

    'webhook' => [
        /**
         * Wether to enable the webhook routes
         */
        'enabled' => env('WHATSAPP_WEBHOOK_ENABLED', true),

        /**
         * The webhook path, by default "/whatsapp/webhook"
         */
        'path' => env('WHATSAPP_WEBHOOK_PATH', 'whatsapp'),

        /**
         * The webhook verification token.
         * For more information check https://developers.facebook.com/docs/graph-api/webhooks/getting-started#verification-requests
         */
        'verify_token' => env('WHATSAPP_WEBHOOK_VERIFY_TOKEN'),

        /**
         * Wether the webhook request signature should be verified or not.
         */
        'verify_signature' => env('WHATSAPP_WEBHOOK_SIGNATURE_VERIFY', false),
    ],
];

Missing features

• Register/deregister/validate new phone numbers

License

This project is licensed under the MIT License.