How to add WhatsApp to ERPNext
Short answer
Use the WhatsApp Business Platform (Cloud API or a BSP) for outbound messages and a small Frappe app or middleware service for inbound replies. ERPNext triggers sends through Webhook, Notification or doc_events hooks, and replies come back through the standard /api/resource and /api/method endpoints with a scoped API user.
Most ERPNext sites are self-hosted on a bench, or on Frappe Cloud, and the people who actually need to hear from the system are not sitting at the Desk. Suppliers confirm dates by phone, drivers send a photo of a delivery note, and shop supervisors approve things between machines. WhatsApp is where those people already are, so the request is usually 'tell the supplier when the PO is submitted and let them confirm by replying'.
ERPNext gives you the right hooks but no WhatsApp channel in the core product. Its Notification DocType covers Email, System Notification and (depending on version) Slack and SMS, so WhatsApp needs either a community Frappe app, a BSP connector, or a thin service you own. The decision that matters is whether replies need to write back into ERPNext, because that is where the real work and the real risk are.
What teams use it for
Purchase Order dispatch and confirmation
When a Purchase Order is submitted, send the supplier a template with PO number, item lines and required-by date, and accept 'confirm' or a revised date as a reply that updates the schedule date on the PO item.
Delivery Note and shipment alerts
On submit of a Delivery Note, send the customer contact the dispatch details and carrier tracking reference taken from the Delivery Note and its linked Sales Order.
Mobile approvals through Workflow
ERPNext Workflow sends Workflow Action emails today. A WhatsApp message with approve and reject quick-reply buttons for Material Requests or Expense Claims moves the document along without opening the Desk.
Payment reminders from Sales Invoice
A scheduled job finds overdue Sales Invoices (outstanding_amount greater than zero, due_date passed) and sends a reminder template with the invoice number and balance, then logs it as a Communication.
Job card and rework nudges
When a Work Order operation is delayed or a Quality Inspection fails, message the production supervisor with the work order, workstation and item so they can respond from the floor.
ERPNext integration surface
- Webhook DocType: fires on doc events (after_insert, on_submit, on_update and others) with an optional Python-style condition and a Jinja request body, signed with a secret header if configured.
- Notification DocType: event-driven alerts with Jinja message templates; channels vary by version, and WhatsApp is not a built-in channel in the core product as far as I know.
- REST API: /api/resource/<DocType> for CRUD and /api/method/<dotted.path> for whitelisted server methods, authenticated with 'Authorization: token api_key:api_secret' from the user's API Access section.
- hooks.py doc_events and scheduler_events in a custom Frappe app, for sends that need logic a Webhook condition cannot express, run through the RQ background workers backed by Redis.
- Communication and Contact DocTypes: where phone numbers (mobile_no, phone) live and where you can record each message so it shows in the document timeline.
How it works
- 1
Set up a WhatsApp Business Account and sender
Register a number with the WhatsApp Business Platform, directly on the Cloud API or through a BSP. Create and submit message templates for each flow (order confirmation, shipment, reminder) and wait for approval before building anything on top.
- 2
Create a scoped ERPNext API user
Make a dedicated User with a Role that can only read the DocTypes you message about and write only the fields replies may change. Generate its API key and secret, and keep them in the middleware, never in a client script.
- 3
Capture opt-in and clean numbers
Add a custom check field such as whatsapp_opt_in on Contact or Supplier, store numbers in E.164 format, and block sends when it is unchecked. Opt-in evidence should be recorded, not assumed.
- 4
Trigger the send from ERPNext
Use a Webhook on Purchase Order on_submit that posts a compact JSON payload (name, supplier, contact, items) to your middleware. The middleware maps it to a template and calls the WhatsApp send-message endpoint.
- 5
Receive replies through the platform webhook
Point the WhatsApp webhook at your middleware, verify the signature, match the reply to the original message by context id, and parse buttons or short text. Anything ambiguous goes to a human.
- 6
Write back through a whitelisted method
Call a custom /api/method endpoint that validates the document state and updates one field or adds a Comment, rather than patching the DocType blindly. Log every inbound and outbound message as a Communication.
Example flows
Supplier confirms a Purchase Order
Trigger: Purchase Order is submitted for a supplier with opt-in set.
- Webhook posts PO name, supplier contact and schedule dates to the middleware.
- Middleware sends the approved 'po_confirmation' template with a Confirm button.
- Supplier taps Confirm or replies with a new date.
- Middleware calls a whitelisted method that sets a custom 'supplier_confirmed' field or proposes the new schedule_date as a Comment for the buyer.
Result: The buyer sees confirmation on the PO timeline without chasing by phone, and date changes are reviewed rather than silently applied.
Delivery update to a customer
Trigger: Delivery Note is submitted with a tracking number.
- A doc_events hook enqueues a background job so the submit is not slowed down.
- The job reads the customer's contact and tracking reference.
- A shipment template is sent; the message id is stored on a Communication linked to the Delivery Note.
Result: Customers get a dispatch notice in their usual app, and the sales team can see exactly what was sent and when.
Keeping data on-prem
The WhatsApp Business Platform itself is cloud hosted by Meta, so message content leaves your network by design; there is no on-prem WhatsApp. What you control is the middle. Keep ERPNext and the middleware inside your network, expose only the webhook receiver through a reverse proxy, and send templates that carry identifiers and dates rather than prices, drawings or part specifications. If you add an AI layer to interpret free-text replies, run an open-weight model locally so supplier messages are not forwarded to another cloud service. For air-gapped sites, WhatsApp is simply not the right channel and email or an internal messenger fits better.
Security checklist
- Use a dedicated API user with narrow roles and User Permissions, so a leaked key cannot read the whole ledger.
- Verify the platform's webhook signature and your Webhook secret on every inbound call; reject anything unsigned.
- Keep templates free of commercially sensitive detail; treat the phone as an untrusted channel and a SIM swap as possible.
- Never let a reply change prices, quantities or bank details; only low-risk fields, and queue the rest for human review.
- Log every message against the document and retain it according to your own records policy.
Ways to get it done
Community or marketplace Frappe app for WhatsApp
Effort: Days to configure; ongoing care at each major version bump.
Small teams with simple notifications who are comfortable maintaining a third-party app across ERPNext version upgrades.
Build a thin Frappe app plus middleware in-house
Effort: Two to four weeks for a first flow with testing, depending on approvals.
Teams with a Frappe developer who want full control of templates, opt-in and write-back rules.
Work with a partner such as Netray
Effort: Scoped pilot on one flow first, then extended.
Manufacturers who want supplier and approval flows plus AI reading of replies, with write-backs gated by approval.
Pitfalls
- !Free-form messages are only allowed inside the customer service window; outside it you need an approved template, and templates take time to approve.
- !Phone numbers stored without country codes break delivery; clean Contact data before launch.
- !Webhooks that fire on every on_update will spam recipients; use conditions or on_submit only.
- !Doing the HTTP call inside the save transaction slows users and rolls back oddly on failure; enqueue instead.
- !Treating a free-text 'ok' as a binding confirmation invites disputes; use buttons and keep the audit trail.
Frequently asked questions
Does ERPNext have built-in WhatsApp?
Not in the core product as far as I know. The Notification DocType handles email and system alerts, and channel support varies by version. WhatsApp is normally added through a community Frappe app, a BSP connector, or custom middleware that calls the WhatsApp Business Platform API.
Can suppliers reply and update ERPNext?
Yes, if you build the inbound side. The platform sends replies to a webhook you host, your service matches them to the original message and calls a whitelisted ERPNext method. Keep writes narrow and send anything ambiguous to a buyer.
Do I need the official API or can I use a personal number?
Use the official Business Platform. Personal-number automation through unofficial tools violates the terms and risks the number being banned, which is a poor foundation for supplier communication that the business depends on.
Will this work with self-hosted ERPNext behind a firewall?
Yes. ERPNext only needs outbound HTTPS to your middleware, and the middleware needs an inbound endpoint for the WhatsApp webhook, exposed through a reverse proxy. The ERP database and API never need to be publicly reachable.
How do I stop duplicate messages on document updates?
Trigger on on_submit rather than on_update, add a Webhook condition, and store a sent flag or Communication record per document and template. Check that record in the middleware before sending, so retries do not message twice.
Want WhatsApp working on your ERPNext?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment