Download the PHP package laravel-notification-channels/webex without Composer

Webex Notifications Channel for Laravel

This package makes it easy to send notifications using Webex with Laravel 10 and 11.

Contents

• Installation
  • Install the package using Composer
  • Add service configuration for Webex
• Usage
  • Formatting Webex Notifications
  • Plain Text Message
  • Rich Text Message
  • Replying to a Parent Message
  • Including a File
  • Including an Attachment
  • Room/Space Linking
  • User and Group Mentions
  • Routing Webex Notifications
• Available Methods
  • Webex Message Methods
  • Webex Message File Methods
  • Webex Message Attachment Methods
  • Interface Method Implementations
• Changelog
• Testing
• Security
• Contributing
• Credits
• License

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:

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:

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:

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.

Rich Text Message

Send a rich text notification message formatted using the Markdown markup language via markdown method.

Replying to a Parent Message

Reply to a parent message and start or advance a thread via the parentId method.

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.

[!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.

[!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>.

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.

To mention everyone in a group room/space, use the <@all> tag.

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.

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 a CouldNotCreateNotification 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 a CouldNotCreateNotification 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 a CouldNotCreateNotification 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 a CouldNotCreateNotification 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 for multipart/form-data request; implemented by all three classes WebexMessageFile, WebexMessageAttachment.
• jsonSerialize(): array:: Converts the current instance as an array suitable for application/json request or passing on tojson_encode; implemented by WebexMessageAttachment classes.
• toJson($options = 0): string: Converts the current instance into a JSON string using PHP's json_encode function, calling jsonSerialize internally to get the data for serialization. Takes an optional parameter $options to specify JSON encoding options; implemented by WebexMessage and WebexMessageAttachment classes.

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Contributing

Please see CONTRIBUTING for details.

Credits

• Ashesh Singh
• All Contributors

License

The MIT License (MIT). Please see License File for more information.