Latest revision as of 18:30, 16 June 2022

WHMCS integrates with popular team communication apps, including Slack and HipChat, to allow WHMCS to notify you in real time as events occur.

You can access this feature at Configuration () > System Settings > Notifications or, prior to WHMCS 8.0, Setup > Notifications.

Example Use

Using conditions, you can set up WHMCS to notify you in your Slack channels and HipChat rooms about the events that are important to you. For example:

• Notify my Support channel or room when a new ticket opens in the Support department with a High priority.
• Notify my Enterprise Support channel or room when a new ticket opens or a customer in the Enterprise Customers client group replies.
• Notify my Emergency channel or room when a new ticket opens containing the words "Emergency" in the subject.
• Notify my Sales channel or room when someone places a new order with a value over $25.
• Notify my Billing channel or room when an invoice is paid by a customer belonging to the High Value client group.
• Notify my Customer Service channel or room when an order is placed for the product Business Hosting.

Configuring Notification Providers

WHMCS supports the following notification providers:

• Configuring Notifications with HipChat
• Configuring Notifications with Slack
• Configuring Notifications via Email

Creating a Notification Rule

Notifications use rules. Each rule defines when to trigger a notification through a combination of events and conditions.

To create a new rule, follow the steps below:

1. Click the Create New Notification Rule button.
2. Enter a name and description for your rule, to allow you to easily identify it again later.
3. Choose an Event Category from the available selector buttons.

4. Choose one or more events that should trigger the notification within the selected event category. Use Ctrl+Click to select multiple ones.
5. Configure any conditions you want to use to restrict when the system triggers the notification. The conditions available to you will vary depending on the selected event category.

By default, all conditions default to unrestricted. To apply a condition to a rule, select or provide a value for a given condition. In the case of a free text-based condition such as Subject, you can choose from an Exact Match or a Containing Match. In a monetary value condition such as Order Total, you have the option of specifying a Greater Than or Less Than match.

6. Configure the desired Notification Settings:

i. Begin by choosing the desired notification provider for this rule. Here we have chosen HipChat.
ii. The other options here will depend upon the notification provider that you selected, but in the case of both HipChat and Slack, you must choose a Room or Channel to post the notification. You will also be able to override the default message with a custom one of your choosing.
iii. In the case of HipChat, you also have the ability to select whether the notification should trigger an alert for the user. When you select this, this can include playing a sound, a mobile notification, and more, depending on an individual user's notification settings.

Modifying a Notification Rule

To edit a notification, locate the notification rule you wish to edit and click the pencil icon. This will open the rule configuration dialog box, where you can make your desired changes.

For more information on the configuration options that are available, see the Creating a Notification Rule guide.

Duplicating a Notification Rule

To duplicate a notification, locate the notification rule you wish to copy and click the copy icon (two files). This will open the rule configuration dialog where you can customise the rule and then click the Duplicate button to complete the process.

For more information on the configuration options that are available, see the Creating a Notification Rule guide.

Enabling/Disabling a Notification Rule

An on-or-off slider in the Notification Rules table indicates the current status of each notification rule. To toggle the status of a notification, click the slide toggle for the desired notification rule.

Deleting a Notification Rule

To delete a notification, locate the notification rule you wish to edit and click the trash can icon.

The system will ask you to confirm that you want to delete the rule before removing it.

The system can't restore a rule after it deletes it. If you may want to reuse the rule in future, we recommend disabling the rule instead of deleting it.

Configuring Email Notifications

Email notifications you to receive notifications to your email address when events occur within WHMCS.

To configure this:

1. Go to Configuration () > System Settings > Notifications or, prior to WHMCS 8.0, Setup > Notifications.
2. Click Configure for Email.
   
3. Configure the Email module settings:
   • Sender Name — The name you wish for emails from this module to be sent as, typically something unique that stands out to prevent these notifications from being missed.
   • Sender Email — The email address the notification should come from.
4. Click Save Changes.

Hooks

Using hooks, it is possible to implement more complex conditional logic than is possible with the conditions available via the Admin Area.

WHMCS includes a "NotificationPreSend" hook point, which executes prior to the system sending a notification. This allows you to apply additional conditional criteria and manipulate the notification message. You can also use this hook point to abort the sending of a Notification that uses your logic.

<?php

add_hook('NotificationPreSend', 1, function($vars) {

    $eventType = $vars['eventType']; // e.g. "Ticket", "Invoice", "Order", "Service" or "Domain"
    $eventName = $vars['eventName'];
    $rule = $vars['rule'];
    $hookParameters = $vars['hookParameters'];
    $notification = $vars['notification'];

    // Perform additional conditional logic and throw the AbortNotification
    // exception to prevent the notification from sending.
    if ($eventType == 'Invoice'
        && $eventName == 'created'
        && (isset($hookParameters['invoiceid'])
        && $hookParameters['invoiceid'] > 1000)
    ) {
        throw new \WHMCS\Notification\Exception\AbortNotification();
    }

    // If allowing the notification to continue, you can manipulate the
    // notification using the \WHMCS\Notification\Notification object.
    $notification->setTitle('Override notification title');
    $notification->setMessage('Override notification message body');

});

By implementing the above hook, any notification for an invoice with an ID above 1000 will abort. To abort a notification, the system returns a `\WHMCS\Notification\Exception\AbortNotification();` exception.

If the ID is below 1000, the system will continue to send the notification, but will override the title and message. To override values, use the "set" functions in $notification. For more information, see Internal Class Documentation.

API

WHMCS makes a TriggerNotificationEvent API function available, which allows you to leverage the Notifications system within WHMCS to send notifications on demand.

Below is an example of using this API method to trigger a notification whenever an admin user logs in to the Admin Area. You can achieve this using a combination of the "AdminLogin" hook and the TriggerNotificationEvent API call:

<?php
add_hook('AdminLogin', 1, function($vars) {

    $command = 'TriggerNotificationEvent';
    $postData = array(
        'notification_identifier' => 'adminarea.staff.login', // A unique identifier used when referencing the notification rule.
        'title' => 'A Staff Member Just Logged In',
        'message' => $vars['username'] . ' just logged in to the WHMCS Admin Area.',
        'url' => 'https://whmcs.example.test/admin/',
        'status' => 'Success',
        'statusStyle' => 'info',
    );
    $adminUsername = 'ADMIN_USERNAME'; // Optional for WHMCS 7.2 and later
    $results = localAPI($command, $postData, $adminUsername);
    print_r($results);
});

After you create your API call, return to the WHMCS Admin Area and define a rule for this event.

1. Click "Create New Notification Rule".
2. Type a name for your Notification Rule.
3. Select "API" and "Custom API Trigger".
4. Under "Trigger Identifier", input the notification identifier you specified in the API call. In our example, this is "adminarea.staff.login".
5. Select "Exact Match" in the select element above.
6. Finally, select and configure the notification method. For example, in the screenshot below, we are configuring an Email notification to login-notifications@example.net.

After you set this up, whenever you trigger this API call, the system will deliver a custom notification via your chosen Notification provider.

Adding a Custom Notification Provider

You can add additional notification providers that notification rules can use by creating a custom notification module. You can learn more about that here: https://developers.whmcs.com/notification-providers/