Get Started

JX WhatsApp Assistant is a modern Joomla site module that adds a floating WhatsApp contact widget with multiple support agents, working-hour schedules, optional pre-chat fields, offline email fallback, analytics events, and full styling controls.

The module does not pretend to be a live WhatsApp API client. It opens WhatsApp Web or the WhatsApp mobile app using clean wa.me links, with optional prefilled message context.

Key Highlights

• Multi-agent WhatsApp support
• Agent priority, routing, department filtering, and schedules
• Global hours, per-agent hours, holidays, always-online, and always-offline modes
• Dynamic message tokens for page URL, page title, and site name
• Optional pre-chat qualification fields
• Offline email fallback using Joomla mail APIs
• GTM dataLayer events and browser CustomEvents
• Complete module-parameter styling controls
• Responsive mobile bottom sheet and accessible keyboard behavior
• Joomla 4, 5 and 6 compatible

System Requirements

• Joomla: 4.x, 5.x or 6.x
• PHP: PHP 8.1+ recommended
• WhatsApp: A valid WhatsApp-enabled phone number for each agent

Install the Module

1. Log in to your Joomla administrator.
2. Go to System > Install > Extensions.
3. Upload and install the module package.
4. Open Content > Site Modules.
5. Find JX WhatsApp Assistant.
6. Set the module to Published.
7. Choose a template position. A footer, debug, or hidden utility position usually works well because the widget is fixed-position.
8. Assign the module to the desired menu items.

After Installation

Add at least one support agent in the Agents tab and enter a valid international WhatsApp number with country code.

Basic Setup

1. Open the module settings.
2. In General, set a heading such as Chat with us.
3. In Agents, click Add.
4. Enter the agent name, role, department, WhatsApp number, and message.
5. Set the agent schedule to Always online for a quick first test.
6. In Style & Appearance, choose a preset and widget position.
7. Save the module and refresh the frontend.

Recommended First Test

• Use one online agent and one always-offline agent.
• Confirm both online and offline badges render.
• Click the online agent and verify the browser opens a wa.me URL.

Panel Text

• Panel Heading: Main title in the widget panel. If empty, the module uses the default language string.
• Subheading: Short intro text under the heading.

Routing

• Priority: Online agents first, then highest priority first.
• First Online: Promotes the first available online agent.
• Random: Promotes a random online agent.
• Round Robin: Rotates the promoted online agent during the visitor session.

Department Filter

Enter a department name such as Sales to show only matching agents. Leave blank to show all agents.

URL Targeting

• URL Include Patterns: Show only when the current URL matches one of the patterns.
• URL Exclude Patterns: Hide when the current URL matches one of the patterns.
• Use one pattern per line. Exclude rules take priority over include rules.

Adding Agents

Open the Agents tab and click Add. Each agent can have:

• Name: Display name shown in the widget.
• Role / Title: Short role text such as Sales Consultant or Support Agent.
• Department: Used for filtering and organization.
• Tags: Optional comma-separated tags for reference.
• WhatsApp Number: International number with country code. Spaces and plus signs are accepted; the module sanitizes the value for wa.me.
• Prefilled Message: Message sent to WhatsApp. Supports {{page_url}}, {{page_title}}, and {{site_name}}.
• Photo: Optional avatar image.
• Priority: Higher values appear before lower values when using priority routing.
• Force Offline: Manually mark an agent offline.
• Availability: Inherit global hours, always online, always offline, or custom hours.

Message Example

Hello, I need help with {{page_title}}.

{{page_url}}

Global Schedule

• Timezone: PHP timezone ID such as UTC or Asia/Kolkata.
• Default Working Days: Use PHP weekday numbers, where 1 is Monday and 7 is Sunday.
• Default Day Start / End: Times in 24-hour format, for example 09:00 and 17:00.
• Holidays: Add dates in YYYY-MM-DD format. Scheduled agents are offline on those days.

Per-Agent Schedule

• Use Global Hours: Agent follows the global schedule.
• Always Online: Agent always appears online, even on holidays.
• Always Offline: Agent always appears offline.
• Custom Hours: Agent uses their own working days and start/end times.

Overnight Windows

If start time is later than end time, the module treats it as an overnight schedule.

Pre-chat fields collect visitor context before opening WhatsApp. When enabled, agent rows become buttons instead of direct links.

Available Fields

• Name
• Email
• Phone
• Message
• Topic / Interest
• Consent checkbox

Required Fields

Name, email, and consent can be required. If required values are missing, JavaScript blocks the WhatsApp redirect and shows an inline error.

How It Works

The module appends collected pre-chat details to the WhatsApp message so the support agent receives useful context immediately.

The offline fallback form appears when all agents are offline and fallback is enabled.

Fallback Options

• Fallback Heading: Form title.
• Fallback Intro: Short helper text.
• Recipient Email: Email address receiving submissions.
• Email Subject: Supports page and visitor tokens.
• Email Body Prefix: Intro text added before submitted fields.
• Include Phone Field: Adds a required phone field to the fallback form.

Security

Fallback submissions use Joomla's CSRF token system and Joomla mail APIs.

Theme Presets

Choose from WhatsApp, minimal, glass, dark, gradient, outline, rounded, and compact presets.

Position

• Bottom right
• Bottom left
• Bottom center
• Side right
• Side left

Visual Controls

• Launcher background and icon color
• Panel background, text, muted text, borders, and accent color
• Online and offline badge colors
• Launcher size, icon scale, panel width, panel radius, avatar size, shadow, z-index, and edge offsets
• Typography source, base font size, heading weight, Google Font family and weights
• Animation type and duration
• Custom CSS

Dynamic styling is scoped per module instance using the module ID.

Data Layer Events

Enable GTM / dataLayer support to push events when visitors open the widget, click an agent, or submit the fallback form.

Browser Events

The module can dispatch browser CustomEvents:

• jx:whatsapp:open
• jx:whatsapp:agent
• jx:whatsapp:fallback-submit

Custom Event Names

The dataLayer event names can be customized in module parameters.

• Does this provide live chat inside my Joomla website?

  No. WhatsApp does not provide that kind of website live-chat API for a normal Joomla module. The widget redirects visitors to WhatsApp Web or the WhatsApp mobile app with a prefilled message.

• Can I add multiple agents?

  Yes. Use the Agents tab and click Add for each support person or department.

• Can each agent have different working hours?

  Yes. Agents can inherit global hours or use custom days and start/end times.

• What happens when all agents are offline?

  If enabled, the module displays an email fallback form so visitors can leave a message.

• Can I track clicks?

  Yes. Enable dataLayer events or browser CustomEvents in the Analytics tab.

• Can I customize the widget design?

  Yes. The Style & Appearance tab includes presets, colors, sizing, typography, animation, and custom CSS.

• Can I show it only on selected pages?

  Yes. Use Joomla module menu assignment and optional URL include/exclude patterns.

• Widget does not appear: Confirm the module is published, assigned to the current menu item, placed in an existing template position, and not hidden by URL exclude patterns.
• Agents do not appear: Confirm at least one agent has a name and a valid phone number. Check department filter and schedules.
• Only fallback appears: All agents are offline or filtered out. Set one agent to Always Online for testing.
• WhatsApp link does not open: Check the phone number format. Use international format with country code.
• Email fallback fails: Check Joomla global mail settings and fallback recipient email.
• Add button missing in Agents tab: Clear Joomla administrator cache and refresh the module edit screen. The Agents field uses Joomla's repeatable subform layout.
• Styling does not update: Clear Joomla/browser cache and check whether template CSS is overriding module CSS.
• Analytics events missing: Confirm dataLayer exists when GTM support is enabled, or listen for the browser CustomEvents.