WhatsApp Notification
Introduction
A WhatsApp Notification record is a rule that automatically sends a WhatsApp message when something happens in iVendNext. The "something" can be a document event (e.g. a Sales Order is submitted), a scheduler event (e.g. every day at 9 AM), or a date-based event (e.g. 3 days before an invoice due date). Each rule specifies the DocType to watch, the event to trigger on, the template to send, the phone number field to send to, and how to map DocType fields to template parameters.
Path in the application
[Path to be confirmed: navigate to WhatsApp Notification in iVendNext Desk.]
Prerequisites
Before you create a WhatsApp Notification, you need:
At least one active WhatsApp Account configured in iVendNext.
At least one WhatsApp Templates record. For Meta accounts, the template must be APPROVED by Meta before the notification will fire successfully.
A clear identification of the Reference DocType you want to watch and the fieldname that holds the recipient phone number on that DocType.
Permissions on the iVendNext site equivalent to System Manager or higher.
How to create
Open a new WhatsApp Notification record.
Enter a Notification Name — a unique label for this rule.
Set Notification Type to either DocType Event or Scheduler Event.
Select the Reference DocType — the DocType this rule will watch (e.g. Sales Order, Sales Invoice).
If Notification Type is DocType Event:
Select the DocType Event to trigger on. Options include Before Insert, After Insert, Before Validate, Validate, On Update, Before Submit, On Submit, Before Cancel, On Cancel, On Trash, After Delete, Before Update After Submit, On Update After Submit, Days Before, Days After.
For Days Before or Days After, additionally set Days Before or After (an integer) and Reference Date (the date field on the DocType to count from).
- If Notification Type is Scheduler Event:
- Select the Event Frequency. Options include All, Hourly, Hourly Long, Daily, Daily Long, Weekly, Weekly Long, Monthly, Monthly Long.
Enter the Field Name — the fieldname on the Reference DocType that holds the recipient phone number (e.g. contact_mobile).
Select the Template — the WhatsApp Templates record to send. The template's Field Names mapping is used to resolve placeholder values from the document.
Optionally enter a Condition — a Python expression evaluated against doc (the source document) before sending. The notification only fires if the condition evaluates to True. Example: doc.docstatus == 1 and doc.grand_total > 1000.
Optionally complete the Fields child table to map specific template parameters to DocType fields. This overrides or supplements the template's own Field Names setting on a per-notification basis.
Optionally configure attachments:
Set Attach Document Print and select a Meta Print Format to attach a PDF of the source document.
Or set Custom Attachment, then either upload a file in Attach or specify a DocType fieldname in Attach From Field that holds a file URL.
Optionally configure Set Property After Alert — select a field on the Reference DocType to update after the notification fires successfully, and enter the Value To Be Set. Used to mark a document as notified (e.g. custom_whatsapp_sent = 1).
Leave Disabled unchecked to enable the rule. Save the record.
Features
Three trigger modes
Document event triggers fire when a specific lifecycle event happens on a specific DocType. Date-based triggers (Days Before, Days After) fire when a date field on a DocType reaches a target date computed from the current date. Scheduler triggers fire on the system's standard scheduler intervals (hourly, daily, weekly, monthly, and long variants).
Global event hook
The notification engine registers a hook on every DocType in the system. When any document event fires, the system checks the cached notification map for matching rules and routes the event to them. No code changes are required to add notifications for custom DocTypes — just create the rule.
Cached rule map
The set of active notifications is cached in Redis under a single key, refreshed when notifications are added or removed. The lookup on every document event is a single cache read, so notifications add negligible overhead even on document types that have no rules configured.
Python conditions
The Condition field accepts any Python expression that returns a truthy value. The expression has access to doc (the source document instance) and runs through safe_exec for security. Common patterns include filtering by docstatus, by document total, by customer attributes, or by flags set elsewhere in the system.
Parameter resolution priority
Template parameter values are resolved in this order: (1) explicit body_param JSON if set on the message; (2) custom data passed via flags.custom_ref_doc; (3) the Fields child table on this notification record; (4) the Field Names setting on the linked template. The first available source wins per placeholder.
PDF document attachments
When Attach Document Print is enabled, the system generates a PDF of the source document using the specified Meta Print Format, appends a secure document share key to the URL, and includes the PDF as a document attachment in the WhatsApp message. The customer taps once on their phone to view the PDF.
Custom file attachments
When Custom Attachment is enabled, the system attaches either a static file (set in Attach) or a file referenced by a fieldname (set in Attach From Field). Useful for attaching a customer-specific document held on the source record.
Post-send property update
When Set Property After Alert is configured, the system writes the specified value to the named field on the source document after the notification fires successfully. The most common use is setting a custom_whatsapp_sent flag so the document carries a record of having been communicated.
Dynamic button URL parameters
If the linked template includes a Visit Website button with a dynamic URL parameter, the parameter value is resolved from a DocType field specified on the notification, allowing each send to carry a unique URL (e.g. an order tracking link or a customer-specific document URL).
Idempotency and skip behaviour
Notifications are skipped automatically during system install, migrate, and uninstall operations to prevent errors during schema changes. They are also skipped if Disabled is checked on the rule. Every send attempt — success or failure — is logged to the WhatsApp Notification Log for audit and troubleshooting.
Scheduler with dynamic recipient lists
Scheduler-type notifications can populate doc._data_list or doc._contact_list inside the condition expression to dynamically resolve recipients at run time. Used for digest messages and any case where the recipient set is not tied to a single document.
**