# WhatsApp Messaging
Share sale documents with customers on WhatsApp — instantly from the invoice screen, or automatically through the Notification System using Meta-approved templates.
On this page
Notification System setup
Send from Sale Invoice
The fastest way to share an invoice — no Notification System setup required.
- Open a Sale Invoice.
- Ensure the customer master has a valid Phone number. The button is hidden when phone is blank.
- Click Send to Whatsapp on the view toolbar.
- WhatsApp opens (web or app) with a pre-filled message containing the invoice type (Cash/Credit), bill number, amount, date, and a PDF download link.
- Review the message and send from your WhatsApp account.
What the message contains. A short thank-you line, whether the invoice is Cash or Credit, the bill number and total, the invoice date, and a link to download the PDF (save.freespaceerp.com/pdf using the document's public token). This does not send through the Notification System — it opens your device's WhatsApp client with the text ready to send.
Related: Sale Invoice · Customers
Overview — Notification System
For **automated** WhatsApp messages on document status change (e.g. on approve), or templated messages through **WhatsApp Cloud API** or **WATI**, configure the Notification System:
| Component | Purpose |
|-----------|---------|
| Providers | Connect to WhatsApp Cloud or WATI with API credentials. |
| Templates | Map Meta-approved template names and parameters to ERP document fields. |
| Recipient Rules | Resolve customer phone from the document. |
| Transaction Configs | Define when to send (document type + status + channel). |
| Transaction History | Audit log of queued, sent, and failed messages. |
This is separate from the in-app Notifications inbox (bell icon) and separate from the Send to Whatsapp quick-link on invoices. See Notifications vs Notification System.
Your company plan must include the WhatsApp feature for Notification System sends. Contact support if Transaction Configs do not queue messages.
Prerequisites
- WhatsApp Business account with Meta Business Manager (for WhatsApp Cloud) or a WATI account.
- Approved message templates on Meta — template name, language, and body structure must match exactly in Freespace.
- Customer mobile on the party master (Phone or Secondary Phone) in a format the API can normalize (include country code where required).
- Admin access to Settings → Notification System.
Quick Start — Full Setup
Step 1 — Provider
Settings → Notification System → Providers → New
| Field | WhatsApp Cloud example |
|-------|------------------------|
| Name | WhatsApp Cloud Main |
| Provider Type | WhatsApp Cloud |
| API Endpoint | https://graph.facebook.com/v18.0 |
| Phone Number ID | *(from Meta developer console)* |
| Access Token | *(permanent or system user token)* |
For **WATI**, select Provider Type WATI, endpoint https://api.wati.io, and API Token instead.
Step 2 — Template
Settings → Notification System → Templates → New
| Field | Example |
|-------|---------|
| Provider Type | WhatsApp Cloud |
| Channel | WhatsApp |
| Name | Invoice Approved WhatsApp |
| Template Name (API) | invoice_approved_default *(must match Meta exactly)* |
| Language Code | en_US |
| Template Category | UTILITY |
| Template Components | Header type and buttons if your Meta template uses them |
Step 2b — Template parameters
Add one row per variable in your Meta template body (and header, if TEXT header with variables):
| Parameter Name | Field Path | Component Type | Data Type | Order |
|----------------|------------|----------------|-----------|-------|
| 1 | customer.name | Body | String | 1 |
| 2 | billNumber | Body | String | 2 |
| 3 | netTotal | Body | Currency | 3 |
Parameter Name must match the variable position or name in your Meta-approved template (often 1, 2, 3 for positional templates). Field Path is the document field the API reads — see Template parameters.
Use Preview on the template to validate parameter resolution before go-live.
Step 3 — Recipient Rule
Settings → Notification System → Recipient Rules → New
| Step | Step Type | Recipient Type | Recipient ID Field Path |
|------|-----------|----------------|-------------------------|
| 1 | resolve | customer | customerId |
Recipient ID Field Path is the field on the loaded document that holds the customer ID — typically customerId. The API then reads phone or secondaryPhone from the customer master.
Step 4 — Transaction Config
Settings → Notification System → Transaction Configs → New
| Field | Example |
|-------|---------|
| Use for Manual Send | Leave unchecked *(WhatsApp manual send from compose is not supported — use automatic configs)* |
| Transaction Type | Sale Invoice |
| Transaction Status | Approved |
| Channel | WhatsApp |
| Default Provider | WhatsApp Cloud Main |
| Notification Template | Invoice Approved WhatsApp |
| Default Recipient Rule | Customer Mobile Rule |
| Delay (minutes) | 0 or 5 *(optional wait before send)* |
Save. Approve a test invoice and check Transaction History.
1. WhatsApp Provider
ERP path: Settings → Notification System → Providers
See Notification Providers for list actions and suspend/activate.
WhatsApp Cloud Configuration
| Field | Description |
|-------|-------------|
| API Endpoint | Meta Graph API base URL (default https://graph.facebook.com/v18.0). |
| Phone Number ID * | Sender phone number ID from Meta Business suite. |
| Access Token * | API token with WhatsApp message permissions. |
WATI Configuration
| Field | Description |
|-------|-------------|
| API Endpoint * | https://api.wati.io |
| Phone Number ID * | WATI phone identifier. |
| API Token * | WATI API bearer token. |
2. WhatsApp Template
ERP path: Settings → Notification System → Templates
See also: Notification Templates.
General
| Field | Description |
|-------|-------------|
| Provider Type * | WhatsApp Cloud or WATI |
| Name * | Internal template name. |
| Channel * | WhatsApp |
| Template Name (API) * | Exact name registered and approved on Meta / WATI. Case-sensitive. |
| Language Code * | Must match approved template (e.g. en_US). |
| Template Category * | UTILITY, MARKETING, etc. |
| Priority | Lower number = higher priority when multiple templates match. |
Template Components
Match the structure of your Meta-approved template:
| Field | Description |
|-------|-------------|
| Header Type | None, Text, Image, Video, or Document — must match Meta template header. |
| Buttons | Optional URL or Quick Reply buttons with index positions matching Meta. |
Email-only sections (Email Subject, Email Body) are hidden when Channel is WhatsApp.
Template parameters
Each row maps a Meta template variable to a field on the transaction record. When a notification fires, the API loads the document, resolves each Field Path, and builds the WhatsApp Cloud API payload.
How it works
- Add a parameter row with Component Type matching your Meta template — Header or Body (and Button if applicable).
- Parameter Name — the Meta variable identifier. For positional templates this is typically
1, 2, 3 in the order they appear in the approved template body.
- Field Path — dot-notation path on the loaded document JSON. Do not prefix with the transaction type (
customer.name, not saleInvoice.customer.name).
- Data Type — String, Number, Currency, Date, URL, etc. Currency formats to two decimals; Date formats to
DD MMM YYYY.
- Order — sort order for parameter resolution.
Phone resolution — Recipient Rules read customer.phone then customer.secondaryPhone (or supplier/employee equivalents). Template parameters supply the message body variables only.
Common field paths (sale documents)
| Field Path | Description |
|------------|-------------|
| billNumber | Document number |
| date | Document date |
| dueDate | Payment due date |
| total | Grand total |
| netTotal | Net total after round-off |
| balance | Outstanding balance |
| customer.name | Customer name |
| customer.phone | Customer phone |
| customer.email | Customer email |
| employee.firstName | Sales employee first name |
| notes | Document notes |
Supported Transaction Types for configs include Sale Invoice, Sale Order, Sale Quotation, Pro Forma Invoice, Credit Note, Delivery Note, Receipt Voucher, and Pay Run — check the Transaction Config form for the full list enabled on your plan.
Use Preview on the template record to validate parameter mapping before enabling automatic sends.
3. Recipient Rule
ERP path: Settings → Notification System → Recipient Rules
See Recipient Rules for full field reference.
Resolution Steps define how the system finds the phone number:
| Step Type | Use when |
|-----------|----------|
| resolve | Look up customer, supplier, or employee contact from a field on the document. |
| manual | Use a fixed phone number if resolve fails or as the only step. |
Example — customer phone from sale invoice:
| Order | Step Type | Recipient Type | Recipient ID Field Path |
|-------|-----------|----------------|-------------------------|
| 1 | resolve | customer | customerId |
For WhatsApp and SMS, the resolver tries phone then secondaryPhone on the customer (or primaryPhone / secondaryPhone on employees).
4. Transaction Config
ERP path: Settings → Notification System → Transaction Configs
See Transaction Configs.
| Field | Description |
|-------|-------------|
| Transaction Type * | Document that triggers the message (e.g. Sale Invoice). |
| Transaction Status * | When to send (e.g. Approved). Hidden when Use for Manual Send is checked. |
| Channel * | WhatsApp |
| Default Provider * | WhatsApp provider record. |
| Notification Template * | Approved template mapping. |
| Default Recipient Rule | Who receives the message. |
| Delay (minutes) | Wait after trigger before sending. |
| Condition JSON | Optional filter (e.g. minimum amount). |
| Fallback Provider / Channel | Retry on another channel if primary fails. |
Only one active manual config per transaction type and channel is allowed. WhatsApp does not use the email Send Email compose screen — automatic configs are the primary Notification System workflow for WhatsApp.
Worked Examples
Example A — Invoice approved WhatsApp (utility template)
Meta template body: "Hello {{1}}, your invoice {{2}} for {{3}} is ready."
Template parameters in Freespace:
| Parameter Name | Field Path | Component Type | Data Type | Order |
|----------------|------------|----------------|-----------|-------|
| 1 | customer.name | Body | String | 1 |
| 2 | billNumber | Body | String | 2 |
| 3 | netTotal | Body | Currency | 3 |
Config: Sale Invoice + Approved + WhatsApp + 0 min delay + Customer recipient rule on customerId.
Example B — Delay 5 minutes after approve
Goal: Allow time to cancel an invoice before WhatsApp goes out.
Set Delay (minutes) = 5 on Transaction Config. Message appears in History as Queued until the delay elapses.
Example C — Quick link vs Notification System
| Method | When to use |
|--------|-------------|
| Send to Whatsapp on invoice | Immediate share with PDF link; you send manually from your WhatsApp; no Meta template required. |
| Notification System | Meta-approved template text; automatic on approve; audit in History; requires provider + template + config setup. |
Transaction History
ERP path: Settings → Notification System → Transaction History
Filter by Channel WhatsApp or status Failed to troubleshoot.
| Status | Meaning |
|--------|---------|
| Queued | Waiting for delay or background worker |
| Sent | Accepted by WhatsApp Cloud / WATI API |
| Failed | Template, phone, or token error — open row for message |
Common failure reasons: template name mismatch, parameter count mismatch, invalid phone format, expired access token, customer opted out.
See Transaction History.
FAQ
Send to Whatsapp vs Notification System — which should I use?
Send to Whatsapp opens WhatsApp with a pre-filled message and PDF link — you tap Send in WhatsApp yourself. The Notification System sends Meta template messages automatically on approve and logs every attempt in History.
Does Send to Whatsapp attach the PDF?
No. It includes a download link in the message text. The customer opens the link to view or save the PDF.
Customer did not receive WhatsApp. What to check?
- Customer Phone on master — correct country code, no typos.
- Transaction History — status Failed? Read the error message.
- Template Name (API) matches Meta exactly (case-sensitive).
- Parameter count and order match the approved Meta template.
- Provider Access Token not expired.
- Customer has opted in / not blocked the business number (Meta policy).
Must templates be approved on Meta first?
Yes for WhatsApp Cloud. Create and approve templates in Meta Business Manager, then copy the exact template name and language into Freespace.
Can I have multiple WhatsApp numbers?
Yes — create separate Provider records with different Phone Number IDs and link each on the relevant Transaction Config.
Can I send WhatsApp and email for the same approve event?
Yes — create two Transaction Configs: one Channel WhatsApp, one Channel Email, both on Approved status for the same transaction type.
Why is a message stuck in Queued?
Delay not elapsed, background worker not running, or provider rate limit. Refresh History after a few minutes; check Failed tab.
Does WhatsApp use Recipient Rules for Send to Whatsapp?
No. Send to Whatsapp uses customer.phone on the invoice. Recipient Rules apply to Notification System sends only.
Why is parameter {{2}} empty in Preview or on send?
Check the Field Path on the matching Template Parameter row. Use document-relative paths like billNumber and customer.name, not saleInvoice.billNumber. Ensure the field has a value on the test document.