bench get-app https://github.com/Zibmoc-Business-Solutions-Pvt-Ltd/Frappe_WebChat

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=Zibmoc-Business-Solutions-Pvt-Ltd%2FFrappe_WebChat)](https://frappegems.com/gems/apps/Zibmoc-Business-Solutions-Pvt-Ltd/Frappe_WebChat)

Frappe Webchat

Embeddable website chat widget for Frappe v16 — successor to the old frappe/chat repo, focused on the visitor-to-agent use case (Intercom / Tawk.to style).

A floating chat bubble appears on every Frappe website page. Visitors can start a conversation; logged-in agents reply from a Desk dashboard.

Features

• Visitor widget — auto-injects on all website pages via web_include_js. No build step on the consumer side.
• Token-based visitor identity — visitors authenticate via an opaque visitor_id stored in localStorage. No account needed.
• Agent dashboard — a Desk page (/app/webchat-dashboard) where staff with the Web Chat Agent role triage and reply.
• Realtime + polling — emits web_chat_message socket.io events on insert and ships a 4 s polling fallback in the widget.
• Rate-limited public endpoints — start (10/min/IP), send (30/min per visitor).
• Per-domain allow-list — Web Chat Settings.allowed_domains restricts which embedding origins may use the widget.
• Configurable — Single doctype Web Chat Settings controls title, welcome message, color, position, name/email gating, max message length, etc.
• Tested — 55 unit/integration tests covering doctype validations, the full visitor API surface, agent API, permissions, and rate-limiting hooks.

DocTypes

DocType	Purpose
Web Chat Settings (Single)	Global configuration — enabled flag, branding, behavior, security.
Web Chat Visitor	One row per browser. Holds the visitor token, name, email, last-seen.
Web Chat Conversation	A chat session (Open / Assigned / Closed) tied to one visitor.
Web Chat Message	Messages from Visitor, Agent, or System.
Web Chat Agent	Maps a Frappe User to an agent profile (status, max concurrent chats).

API surface

Visitor (Guest, whitelisted)

GET  /api/method/frappe_webchat.api.visitor.get_config
POST /api/method/frappe_webchat.api.visitor.start_conversation
POST /api/method/frappe_webchat.api.visitor.send_message
POST /api/method/frappe_webchat.api.visitor.poll_messages
POST /api/method/frappe_webchat.api.visitor.end_conversation

Agent (authenticated, role-gated)

POST /api/method/frappe_webchat.api.agent.list_conversations
POST /api/method/frappe_webchat.api.agent.get_conversation
POST /api/method/frappe_webchat.api.agent.claim_conversation
POST /api/method/frappe_webchat.api.agent.reply
POST /api/method/frappe_webchat.api.agent.close_conversation
POST /api/method/frappe_webchat.api.agent.set_agent_status

Install

There are three deployment scenarios. Pick whichever matches your setup.

Scenario A — Existing Frappe v16 bench, new site

Use this when your website is the Frappe site (the Frappe-rendered website pages will host the widget).

# from your bench root
bench get-app https://github.com/chinmaybhatk/frappe-webchat
bench --site  install-app frappe_webchat
bench --site  migrate
bench --site  clear-cache

The widget auto-injects on every website page via web_include_js. The agent dashboard is at /app/webchat-dashboard.

Scenario B — Separate Frappe install (multi-tenant)

Same as Scenario A — just install the app on each site that needs the widget. Each site has its own Web Chat Settings, conversations, and agents (data is isolated by site).

If the bench is fresh:

bench init frappe-bench --frappe-branch version-16
cd frappe-bench
bench new-site mysite.localhost
bench get-app https://github.com/chinmaybhatk/frappe-webchat
bench --site mysite.localhost install-app frappe_webchat
bench start

Scenario C — Embed on a non-Frappe website (WordPress, Next.js, static HTML, …)

Use this when your marketing/product site is hosted somewhere else and you want the chat widget there, with the Frappe site acting purely as the backend.

1) On the Frappe site, open Web Chat Settings and add the embedding domain to Allowed Domains (comma-separated, no scheme):

example.com, www.example.com, app.example.com

2) Enable CORS on the Frappe site so the cross-origin fetch is permitted. Add to sites//site_config.json:

{
  "allow_cors": ["https://example.com", "https://www.example.com"]
}

Then bench --site clear-cache.

3) Drop this snippet into the (or just before) of every page on your external site:

data-endpoint is optional — if omitted, the widget infers the endpoint from the script's own origin, which is what you want 99% of the time.

You can also configure inline before loading:

The widget will: - POST to ${endpoint}/api/method/frappe_webchat.api.visitor.* - Persist the visitor token in localStorage on the embedding site (so each external host has its own visitor identity) - Skip cookies on cross-origin calls (visitor identity comes from the token, not a session cookie)

Configure the widget

Open Web Chat Settings (Single doctype) and set:

• Enabled — kill switch.
• Widget Title / Welcome Message / Primary Color / Position — visible to visitors.
• Require Name / Require Email — gate the start form.
• Max Message Length / Rate Limit / Inactivity Timeout — abuse controls.
• Allowed Domains — restrict which external sites may embed (Scenario C).

Add an agent

To make a Frappe user available to reply:

1. Assign them the Web Chat Agent role (User → Roles).
2. Create a Web Chat Agent record linked to that user (auto-created on first reply if the user already has the role).
3. They can now reply from /app/webchat-dashboard.

Tests

bench --site  set-config allow_tests true
bench --site  run-tests --app frappe_webchat

55 tests, all green:

• test_web_chat_settings.py — Single doctype validation, domain allow-list normalization.
• test_web_chat_visitor.py — email canonicalization, uniqueness, touch().
• test_web_chat_agent.py — role auto-grant on agent creation.
• test_web_chat_conversation.py — status transitions, rating bounds, assignment guards.
• test_web_chat_message.py — content size limits, sender constraints, conversation activity bumps.
• test_visitor_api.py — full Guest API: cross-visitor isolation, blocked-visitor lockout, closed-conversation rejection, oversize/empty rejection.
• test_agent_api.py — auth gating, claim/reply/close flow, status changes.

License

MIT