Notifications in PortaBilling

PortaBilling sends notifications to admins, customers, and resellers via email or SMS. Each notification is triggered by a specific system event – for example, when a report is generated, or a route becomes unavailable.

Notification content is defined by templates. Templates are grouped into notification sets and assigned either to a customer class (for customer and reseller notifications) or directly to a PortaBilling user (for admin notifications).

Each template contains static text and placeholders for variables. When a notification is sent, PortaBilling replaces each placeholder with the actual value – for example, Dear <% $customer_name %> becomes Dear John Doe.

Each notification template, which includes the email subject, email body, and SMS text, is editable in the PortaBilling web interface.

Templates support multiple languages so you can assign customers a notification set in their language.

Templates contain variables – such as "Company name," "Invoice number," or "Amount due" – that PortaBilling replaces with actual values when the notification is sent. To insert a variable, drag it from the panel on the right side of the editor. Templates are composed using the HTML::Mason syntax.

To preview a notification, click Send me a sample. PortaBilling sends a test notification to the email address specified in the Email field and the phone number specified in the Alt. phone field on the user page.

If you use an external service such as Twilio (available via Add-on Mart) to send SMS notifications, long messages may be split into multiple parts. To control this, update the Notifications.MaxSMSLength option on the Configuration server web interface. This option defines the maximum number of UTF-8 characters allowed in an SMS template body, including variable names and special characters. If a message exceeds the configured limit, the message is sent, and a warning is saved to the log. The default value is 0 (no limit).

A notification set is a collection of templates for all available notifications. Templates are grouped into categories, such as "Billing notifications" or "Password recovery." When assigning a notification set to a customer class or a PortaBilling user, you can enable or disable individual notifications or entire categories.

For example, if an admin in the finance department only requires report generation notifications, you can disable all other categories for that user.

PortaBilling provides two types of notification sets:

• Customer class notifications – defines notifications sent to customers and their accounts (for example, when an invoice is overdue or a quota is exhausted). Since resellers are treated as customers, this type also covers reseller notifications. A customer class notification set is assigned to a customer class, which is then linked to a specific customer or reseller.
• User notifications – defines notifications sent to administrators. This type is assigned directly to a PortaBilling user.

To set up customer notifications:

1. Create a notification set of the "Customer class notifications" type.
2. Assign the notification set to a customer class.
3. Within the assigned notification set, select the notification categories or specific notifications to send via email or SMS.

For detailed instructions, see How to manage customer class notifications.

Variables in the message text – such as "Company name," "Invoice number," or "Amount due" – are enclosed in <% %> tags. Perl expressions are supported within these tags. For example, the following conditional statement displays the company name if one is defined, or the customer name otherwise:

<% $companyname ? $companyname : $name %>

The following functions are available:

• column (text, width => N, align => 'left'|'right') – generates a padded string of specified width; text is left-aligned by default. Parameters:
  • text – the text to output
  • N – the width of the padding space
  • align – text alignment: left or right
• line (char, width) – outputs a string of repeated characters (for example, dashes to underline text). Parameters:
  • char – the character to repeat
  • width – the number of times to repeat the character

For example:

<% column('Previous Balance:', width => 45) %> <% column($previous_balance, width => 10, align => 'right') %> <% line('-', 25) %>

produces the following output:

• "Previous Balance:" is left-aligned within a 45-character wide space.
• The value of $previous_balance ("10.00") is right-aligned within a 10-character wide space.
• A line of 25 dashes is generated below the text.

The following table lists the customer notification messages available in PortaBilling.