A Laravel Notification Channel for Webex.
Requires
- php: >=8.1
- ext-json: *
- egulias/email-validator: *
- guzzlehttp/guzzle: ^7.0
- illuminate/notifications: ~10.0 || ~11.0
- illuminate/support: ~10.0 || ~11.0
Requires (Dev)
- laravel/pint: ^1.14
- mockery/mockery: ^1.0
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10.0
This package is auto-updated.
Last update: 2024-09-15 14:52:52 UTC
README
This package makes it easy to send notifications using Webex with Laravel 10 and 11.
/** * Get the Webex Message representation of the notification. * * @return \NotificationChannels\Webex\WebexMessage * * @throws \NotificationChannels\Webex\Exceptions\CouldNotCreateNotification */ public function toWebex(mixed $notifiable) { return (new WebexMessage) ->text('The message, in plain text.') ->markdown('# The message, in Markdown format.') ->file(function (WebexMessageFile $file) { $file->path('https://www.webex.com/content/dam/wbx/global/images/webex-favicon.png'); }); }
Contents
Installation
To use this package, you need to add it as a dependency to your project and provide the necessary configuration.
Install the package using Composer
Pull in and manage the Webex notifications package easily with Composer:
composer require laravel-notification-channels/webex
Add service configuration for 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, or if the webex
key already exists, merge:
'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') ],
Use the WEBEX_NOTIFICATION_CHANNEL_ID
and WEBEX_NOTIFICATION_CHANNEL_TOKEN
environment 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. */ public function via(mixed $notifiable): array { return [WebexChannel::class]; } // ... }
To send notifications on Webex, define a toWebex
method on the notification class and a routeNotificationForWebex
method on the notifiable entity. These steps are discussed below.
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).
Plain Text Message
Let's take a look at a basic toWebex
example, which we could add to our InvoicePaid
class
above.
public function toWebex(mixed $notifiable): WebexMessage { return (new WebexMessage) ->text('Invoice Paid!'); }
Rich Text Message
Send a rich text notification message formatted using the Markdown markup language via
markdown
method.
public function toWebex(mixed $notifiable): WebexMessage { return (new WebexMessage) ->markdown('# Invoice Paid!'); }
Replying to a Parent Message
Reply to a parent message and start or advance a thread via the parentId
method.
public function toWebex(mixed $notifiable): WebexMessage { $messageId = "Y2lzY29zcGFyazovL3VybjpURUFNOnVzLXdlc3QtMl9yL01FU1NBR0UvNGY0ZGExOTAtOGUyMy0xMWVjLTljZWQtNmZkZWE5MjMxNmNj" return (new WebexMessage) ->parentId($messageId) ->text("Invoice Paid!" . "\n" "No Further action required at this time"); }
Including a File
A notification message can have at most one file that you can include via the
file
helper method. When calling the file
method, you should provide the path of the file. The file path could be
local or of the form "scheme://...", that is accessible to your application. Optionally, you can
also provide a name and MIME type to display on Webex clients.
public function toWebex(mixed $notifiable): WebexMessage { $filePath = 'storage/app/invoices/uwnQ0uAXzq.pdf'; return (new WebexMessage) ->file(function (WebexMessageFile $file) use ($filePath){ $file->path($filePath) // required ->name('invoice.pdf') // optional ->type('application/pdf'); // optional }); }
Note
- Including multiple files in the same message is not supported by the
file
helper. - Including file and attachment in the same message is not supported by the
file
helper. - For supported MIME types and file size limits, please refer Webex HTTP API documentation.
Including an Attachment
A notification message can have at most one attachment that you can include via the
attachment
helper method. When calling the attachment
method, you should provide the content of the attachment. The
attachment content must be a PHP array representation for an
adaptive card. Optionally, you can
also provide a content type.
public function toWebex(mixed $notifiable): WebexMessage { $invoicePaidCard = json_decode('{ "type": "AdaptiveCard", "version": "1.0", "body": [ { "type": "TextBlock", "text": "Invoice Paid!", "size": "large" } ], "actions": [ { "type": "Action.OpenUrl", "url": "https://example.com/invoices/uwnQ0uAXzq.pdf", "title": "View Invoice" } ] }'); return (new WebexMessage) ->attachment(function (WebexMessageAttachment $attachment) use ($invoicePaidCard) { $attachment->content($invoicePaidCard) // required ->contentType('application/vnd.microsoft.card.adaptive'); // optional }); }
Note
- Including multiple attachments in the same message is not supported by the
attachment
helper. - Including attachment and file in the same message is not supported by the
attachment
helper. - For supported attachment types, please refer Webex HTTP API documentation.
Room/Space Linking
To Link to a room/space use its Webex protocol handler, i.e. webexteams://im?space=<space_id>
.
public function toWebex(mixed $notifiable): WebexMessage { return (new WebexMessage) ->markdown('We are in the webexteams://im?space=f58064a0-8e21-11ec-9d53-739134f9a8eb space.'); }
User and Group Mentions
To mention someone in a group room/space use their registered Webex email address or Webex HTTP API identifier as shown below.
public function toWebex(mixed $notifiable): WebexMessage { $mentionPersonEmail = 'baburao@example.com'; return (new WebexMessage) ->markdown("Hello <@personEmail:$mentionPersonEmail|Babu Bhaiya>! Your invoice is ready for payment."); }
public function toWebex(mixed $notifiable): WebexMessage { $mentionPersonId = 'Y2lzY29zcGFyazovL3VzL1BFT1BMRS85OTRmYjAyZS04MWI1LTRmNDItYTllYy1iNzE2OGRlOWUzZjY'; return (new WebexMessage) ->markdown("Hello <@personId:$mentionPersonId|Babu Bhaiya>! Your invoice is ready for payment."); }
To mention everyone in a group room/space, use the <@all>
tag.
public function toWebex(mixed $notifiable): WebexMessage { return (new WebexMessage) ->markdown('Hello <@all>! An invoice is ready for payment.'); }
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|null */ public function routeNotificationForWebex($notification): string|null { 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 } }
Available Methods
All messaging classes are under the \NotificationChannels\Webex
namespace.
Webex Message Methods
Public methods of the WebexMessage
class:
text(string $content): WebexMessage
: Sets the plain text content of the message and returns the current instance with$text
property set.markdown(string $content): WebexMessage
: Sets the Markdown content of the message and returns the current instance with$markdown
property set.parentId(string $id): WebexMessage
: Sets the parent message to reply to. Throws aCouldNotCreateNotification
exception if the provided Webex HTTP API resource identifier is invalid. Returns the current instance with updated$parentId
property.file(Closure $callback): WebexMessage
: Adds a file to the message. Throws aCouldNotCreateNotification
exception if there's already a file or an attachment present. Returns the current instance with the$files
property set.attachment(Closure $callback): WebexMessage
: Adds an attachment to the message. Throws aCouldNotCreateNotification
exception if there's already an attachment or file present. Returns the current instance with the$attachments
property set.to(string $recipient): WebexMessage
: Sets the recipient of the message. This method automatically determines if the recipient is a single person/bot (i.e., direct 1:1 room/space) or a group room/space. If the provided recipient is a valid email address, it sets$toPersonEmail
. If it's a valid Webex HTTP API resource identifier, it sets$toPersonId
for people/bots or$roomId
for rooms/spaces. Throws aCouldNotCreateNotification
exception if the provided recipient is neither an email, nor a valid Webex HTTP API resource identifier. Returns the current instance with exactly one of$toPersonEmail
,$toPersonId
, or$roomId
set.
Webex Message File Methods
Public methods of the WebexMessageAttachment
class:
path(string $path): WebexMessageFile
: Sets the path for the file and returns the current instance with$path
property set.name(string $name): WebexMessageFile
: Sets the user provided name for the file and returns the current instance with optional$name
property set.type(string $type): WebexMessageFile
: Sets the user provided MIME type for the file and returns the current instance with optional$type
property set.
Webex Message Attachment Methods
Public methods of the WebexMessageFile
class:
contentType(string $contentType): WebexMessageAttachment
: Sets the content type of the attachment and returns the current instance with$contentType
property set.content(mixed $content): WebexMessageAttachment
: Sets the content of the attachment and returns the current instance with$content
property set.
Interface Method Implementations
In addition, there are some methods available for transforming Webex messaging instances that are used internally for creating the request payload to Webex HTTP API:
toArray(): array
: Converts the current instance into an array suitable formultipart/form-data
request; implemented by all three classesWebexMessage
,WebexMessageFile
,WebexMessageAttachment
.jsonSerialize(): array
:: Converts the current instance as an array suitable forapplication/json
request or passing on tojson_encode
; implemented byWebexMessage
andWebexMessageAttachment
classes.toJson($options = 0): string
: Converts the current instance into a JSON string using PHP'sjson_encode
function, callingjsonSerialize
internally to get the data for serialization. Takes an optional parameter$options
to specify JSON encoding options; implemented byWebexMessage
andWebexMessageAttachment
classes.
Changelog
Please see CHANGELOG for more information what has changed recently.
Testing
$ composer test
Security
If you discover any security related issues, please email ask@mrsinh.com instead of using the issue tracker.
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.