Frappe Framework v15 Realtime API — Complete Documentation

Introduction: What Is the Realtime API in Frappe v15?

The Realtime API in Frappe v15 enables instant, WebSocket-based communication between the server and the browser.
It is used for real-time messaging, notifications, progress updates, background job status sharing, and broadcasting events across all connected users.

Frappe uses:

• WebSockets (via Socket.IO 4.x)
• Redis (as the event queue backend)
• Python APIs for server → client messaging
• JavaScript APIs for client handling

This feature is critical for ERPNext implementations where users expect live updates, such as background job progress, document workflow updates, chat, and dashboard refreshes.

What Can You Do with Realtime API in Frappe v15?

• Send messages to individual users
• Broadcast events to all connected sessions
• Stream progress of long-running tasks
• Push notifications to Desk/Website
• Trigger UI updates (e.g., form reload)
• Send custom event payloads from Python or JS

Realtime communication significantly improves user experience for ERPNext-based systems.

Architecture Overview (Frappe v15)

Frappe v15 uses Redis channels internally and automatically manages WebSocket connections.

How to Use Realtime API in Frappe v15

How to Publish a Realtime Event (Python)

Basic Example

import frappe
frappe.publish_realtime(
event="msgprint",
message="Task completed successfully",
user=frappe.session.user
)

Important Parameters (v15 verified)

Ensures event fires only after DB commit

• Works with all background workers
• Safe for task monitoring and job updates

Sending Events After Commit

This ensures events don’t fire if DB transaction fails.

frappe.publish_realtime(
event="refresh_dashboard",
after_commit=True
)

Broadcasting Events to All Users

frappe.publish_realtime(
event="system_update",
message={"status": "completed"},
room="all"
)

room=”all” is equivalent to a global broadcast.

Realtime Progress Updates (Built-In Support)

Frappe automatically handles progress UI elements.

Python:

frappe.publish_realtime(
"progress",
{"percent": 60, "title": "Processing Sales Orders..."},
user="Administrator"
)

Used heavily in:

• Data imports
• Background jobs
• Email queue execution
• Reports generation

Client-side Realtime Handling (JavaScript)

Basic Listener

frappe.realtime.on("msgprint", (data) => {
console.log("Received:", data);
});

Listening for Custom Events

frappe.realtime.on("refresh_dashboard", (data) => {
frappe.show_alert("Dashboard refreshed!");
});

Listening to Document-Specific Events (v15 Feature)

frappe.realtime.on("doc_update:Sales Order:SO-0001", (data) => {
console.log("Sales Order updated:", data);
});

Frappe creates internal event names like:

doc_update:<doctype>:<docname>

Auto-connected Socket.IO

In Desk:

frappe.socketio.socket.connected === true

The connection is opened automatically by the Desk app.

Advanced Usage & Integration Patterns

Using Realtime API with Background Jobs

Example:

def long_task():
for i in range(1, 101):
frappe.publish_realtime("progress", {"percent": i})

Sending Realtime Events via REST (Allowed in v15)

frappe.call({
method: "frappe.realtime.publish_realtime",
args: {
event: "chat_message",
message: { text: "Hello!" }
}
});

(Not recommended for high-frequency messaging; use socket-based).

Multi-User ERP Example (ERPNext Manufacturing)

Scenario: A production manager updates Work Order status. All machine operators see live updates.

Python (backend):

frappe.publish_realtime(
"work_order_update",
{"work_order": wo.name, "status": wo.status},
room="MachineOperators"
)

JS (frontend):

frappe.realtime.on("work_order_update", (data) => {
frappe.show_alert(`WO ${data.work_order} → ${data.status}`);
});

Best Practices

• Use meaningful event names
• Group users via custom rooms
• Always use after_commit for DB-dependent events
• Avoid large payloads in Realtime messages
• Use Redis monitoring tools to debug channels
• Remove or throttle events in production to reduce load

Cross References

• Permissions: Needed for protected DocTypes
• Background Jobs: Realtime progress uses queue workers
• Email Alerts: Can trigger realtime updates
• Notification System: Uses realtime push

Conclusion

The Frappe Realtime API in version 15 provides a powerful and scalable communication layer ideal for ERPNext production environments. It offers WebSocket events, instant UI refresh, background job progress tracking, and cross-user broadcasting—essential for modern ERP experiences.
This guide provides a complete breakdown of all server-side and client-side capabilities, implementation patterns, and best practices strictly following Frappe v15 documentation and GitHub source.