How to add an AI chatbot to ERPNext
Short answer
An ERPNext chatbot answers questions from live DocTypes and attached documents, shown either in the desk, the customer portal or a website widget. Ground answers in tool calls and retrieval, respect each user's permissions, and run an open-weight model locally if data must stay private.
ERPNext has a search bar and plenty of reports, yet new users still ask colleagues where to find things, and customers ask sales for order updates the portal could answer. A chatbot closes that gap if it answers from the system rather than from general knowledge.
The difficult part is trust. A bot that invents a delivery date or leaks another customer's invoice is worse than no bot. So the design has to tie every answer to a document, check who is asking, and refuse when data is missing.
There are two audiences with different rules: internal staff in the desk, and external customers or suppliers in the portal. This page covers both, how to embed the bot, and how to keep it private on a self-hosted site.
What teams use it for
Staff help in the desk
A side panel answers how-to questions from your own SOPs and finds documents, such as the last Delivery Note for a customer, using the user's own permissions.
Customer order status in the portal
Logged-in portal customers ask about their Sales Orders, shipments and open invoices, and the bot only sees records linked to their Customer.
Supplier self-service
Suppliers ask which Purchase Orders are open and when payment is due, answered from their own documents through the Supplier portal user.
Shop floor questions
Operators ask for the current BOM revision, routing steps or setup notes for a Work Order, answered from linked documents and attached drawings.
Quotation helper for sales
Salespeople describe a request and the bot finds matching Items, recent prices and lead times, then opens a pre-filled Draft Quotation.
Onboarding assistant
New hires ask where to record a stock transfer or how a Production Plan works, and get answers tied to your own configuration notes.
ERPNext integration surface
- Frappe REST and whitelisted methods called with the logged-in user's session, which keeps role permissions and User Permissions in force for staff.
- Portal user model: Customer and Supplier portal users linked to a Contact, with Portal Settings controlling which menus they see.
- Website and Web Page content, Knowledge Base style articles and File attachments as retrieval sources for how-to answers.
- Frappe realtime (Socket.IO) and custom desk pages or Client Script buttons for embedding a chat panel in the UI.
- Webhooks and the Communication DocType for logging conversations against a Customer or Issue when the bot hands off to a person.
How it works
- 1
Decide the audience and scope
Start with one audience, such as staff lookups. Customer-facing bots need stricter scoping and a clear hand-off to humans.
- 2
Build the data tools
Create tools for order status, item lookup and invoice status. Run them as the signed-in user, so Frappe permissions decide what is visible.
- 3
Index documents for retrieval
Chunk SOPs, manuals and attached specifications, add metadata for item group or department, and store embeddings in a vector store you control.
- 4
Add the chat surface
For the desk, use a custom app with a page or a sidebar. For the portal, add a widget to a Web Page, authenticated by the portal session.
- 5
Set answer rules
Require a source link for each factual claim, say I could not find that when data is absent, and never state dates or prices not returned by a tool.
- 6
Create a hand-off path
Offer to create an Issue or notify the account owner, and save the transcript as a Communication.
- 7
Evaluate before launch
Test with real questions from support tickets, including permission traps such as asking for another customer's order.
Example flows
Portal order tracking
Trigger: A customer types: when will order SO-1042 arrive.
- The portal session identifies the user and linked Customer.
- The bot calls the order status tool, which filters by that Customer.
- It reads Delivery Notes and any carrier reference field.
- It replies with status and dates, and offers to raise an Issue if the date is past due.
Result: Routine status questions are answered without sales staff, and exceptions reach a person.
Operator setup lookup
Trigger: An operator asks about the setup notes for the Work Order on press 4.
- The bot identifies the Work Order and linked BOM and Operation.
- It retrieves attached setup sheets and operation descriptions.
- It summarises steps and cites the file names.
- If the sheet is missing, it says so and notifies the process engineer.
Result: Fewer interruptions for supervisors and consistent use of the current document revision.
Keeping data on-prem
A self-hosted ERPNext can host the whole chatbot stack in the same environment. Serve an open-weight model on local GPUs with vLLM or Ollama, keep the vector store and embeddings on your own storage, and call the Frappe API over the internal network. For a customer-facing portal, only the chat widget and a thin gateway need to be public; the model and ERP stay behind the firewall. Size GPUs for peak concurrent chats, not average, and set a clear fallback message when the model is busy. Netray runs this pattern for manufacturers who cannot send documents to a public cloud.
Security checklist
- Run data tools as the signed-in user, never as a service administrator, so Frappe permissions limit every answer.
- For portals, test cross-customer access explicitly and block any tool that takes a customer name from the model.
- Filter and redact fields such as cost price, margin and bank details before the model sees them.
- Keep transcripts under your retention policy and mask personal data in logs.
- Apply rate limits and bot detection on public widgets to stop scraping through the chat.
Ways to get it done
Frappe community chat or helpdesk add-ons
Effort: Low, but limited grounding.
Basic ticketing and live chat. They may not answer from ERP data, so check what they connect to.
Build on the Frappe API with a retrieval layer
Effort: A staff-only pilot in weeks; a public portal bot needs more testing.
You have developers and want a bot tailored to your DocTypes and SOPs.
Netray private assistant
Effort: Scoped pilot, then rollout by audience.
On-prem data, mixed ERP and document questions, and a need for audit and approval rules.
Pitfalls
- !Using general model knowledge for ERPNext how-to answers, which often describe other versions or features.
- !Giving the portal bot a service key, so it can see every customer's data.
- !Indexing outdated SOPs and drawings without revision metadata, so the bot cites superseded files.
- !No hand-off route, which leaves customers stuck when the bot cannot help.
- !Launching without measuring wrong or refused answers.
Frequently asked questions
Can an ERPNext chatbot be limited to a customer's own data?
Yes, if tools run under the portal user's session and filter by the linked Customer. Test it with attempts to ask about other customers. Never pass customer names from the model into queries without a server-side check.
Does the bot need to be inside the ERPNext desk?
No. It can be a desk panel, a portal widget, a website chat or a messaging channel. What matters is that it calls ERPNext tools as the right identity, whichever surface the user sees.
Can the chatbot run without the internet?
Yes. With an open-weight model, a local embedding model and a local vector store, everything can run in your network. You trade some answer quality and need GPU capacity, so test on your own questions before committing.
How do we stop wrong answers?
Ground each answer in a tool result or a retrieved document, require citations and instruct the bot to decline when nothing is found. Review transcripts weekly, and keep a test set of known questions that you rerun after every change.
Will it replace support staff?
It reduces repetitive status questions, but exceptions, disputes and negotiations still need people. Design the bot to hand off cleanly with context, and measure resolved versus escalated conversations rather than aiming for zero tickets.
Want AI chatbot 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