Convenient Webex Notifications for Laravel Projects

In my last blog post, I showed how Laravel developers can leverage the socialiteproviders/webex package to simplify their workload when authenticating with Webex. Today, I am making another addition to the ecosystem in the form of a Laravel Notifications channel for Webex. Laravel Notifications simplify sending notifications across a variety of delivery channels such as database and email. Although out-of-the-box such support is limited to only a handful of channels, community-driven Laravel Notification Channels can easily extend compatibility to others, including Webex.

That is an exciting development since Laravel based projects can use this single, consistent interface to send notifications through Webex in addition to already supported channels like Telegram, Twitter, Facebook, and many more! You can find the complete list of supported channels on the project's website https://laravel-notification-channels.com/about. The project currently supports more than 50 notification channels.

Installation

Install the package using Composer:

composer require laravel-notification-channels/webex

You will also need to include a Webex service configuration to your application. To do this, edit the config/services.php file and add the following:

'webex' => [
    'notification_channel_url' => env('WEBEX_NOTIFICATION_CHANNEL_URL', 'https://webexapis.com/v1/messages'),
    'notification_channel_id' => env('WEBEX_NOTIFICATION_CHANNEL_ID'),
    'notification_channel_token' => env('WEBEX_NOTIFICATION_CHANNEL_TOKEN')
],

Then use the WEBEX_NOTIFICATION_CHANNEL_ID and WEBEX_NOTIFICATION_CHANNEL_TOKENenvironment variables to define your Webex ID and Token. One way to get these values is by creating a new Webex Bot.

Usage

If you are new to Laravel Notification, I highly recommend reading the official documentation which goes over the basics of generating and sending notifications. The guide below assumes that you have successfully generated a notification class with a via method whose return value includes 'webex' or NotificationChannels\Webex\WebexChannel::class. For example:

<?php
 
namespace App\Notifications;
 
use Illuminate\Bus\Queueable;
use Illuminate\Notifications\Notification;
use NotificationChannels\Webex\WebexChannel;
 
class InvoicePaid extends Notification
{
    use Queueable;
 
    // ...
    
    /**
     * Get the notification's delivery channels.
     *
     * @param  mixed  $notifiable
     * @return array
     */
    public function via($notifiable)
    {
        return [WebexChannel::class];
    }
    
    // ...
}

Formatting Webex Notifications

If a notification supports being sent as a Webex message, you should define a toWebex method on the notification class. This method will receive a $notifiable entity and should return a \NotificationChannels\Webex\WebexMessage instance. Webex messages may contain text content as well as at most one file or an attachment (for buttons and cards).

Let's take a look at a sample toWebex example, which we could add to our InvoicePaid class above.

    /**
     * Get the Webex Message representation of the notification.
     *
     * @param  mixed  $notifiable
     * @return \NotificationChannels\Webex\WebexMessage
     *
     * @throws \NotificationChannels\Webex\Exceptions\CouldNotCreateNotification
     */
    public function toWebex($notifiable)
    {
        return (new WebexMessage)
            ->text('Invoice Paid!')
            ->markdown('# Invoice Paid!')
            ->file(function (WebexMessageFile $file) {
                $file->path('storage/app/invoices/uwnQ0uAXzq.pdf')
                    ->name('invoice.pdf');
            })
    }

Routing Webex Notifications

To route Webex notifications to the proper Webex user or room/space, define a routeNotificationForWebex method on your notifiable entity. This should return a Webex registered email address or a Webex HTTP API resource identifier for a user or room/space to which the notification should be delivered.

<?php
 
namespace App\Models;
 
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
 
class User extends Authenticatable
{
    use Notifiable;
 
    /**
     * Route notifications for the Webex channel.
     *
     * @param  \Illuminate\Notifications\Notification  $notification
     * @return string
     */
    public function routeNotificationForWebex($notification)
    {
        if (!empty($this->email)) {             // a Webex registered email address
            return $this->email;
        } else if (!empty($this->personId)) {   // a Webex HTTP API resource identifier for a user
            return $this->personId;
        } else if (!empty($this->roomId)) {     // a Webex HTTP API resource identifier for a room/space
            return $this->roomId;
        }

        return null;                            // don't route notification for Webex channel
    }
}

Wrapping Up

This article provided a brief overview of the new Laravel Notification Channels Webex package. Laravel project owners are encouraged to use this package to simplify their workload when sending notification via Webex. To see other such community offerings or learn more about our developer platform, please visit Webex Developers.