MxChat Forms

Custom in-chat forms and multi-step wizards that fire naturally during conversations — for lead capture, support tickets, product recommendations, eligibility quizzes, and any other structured data you need to pull out of a chat session.

Overview

MxChat Forms turns your chatbot into a structured data-collection tool without breaking the conversational flow. Instead of bouncing visitors to a separate contact page, the form appears inline when the AI detects the right intent (or after a set number of messages). You build the fields, define the trigger phrases, and the add-on hooks straight into MxChat's action recognition system. Two wizard modes — Conditional (linear questions with outcome rules) and Branching (dynamic decision trees) — cover everything from a simple "drop your email" capture up to multi-step troubleshooting flows. Pro license required.

Setup

Install the mxchat-forms plugin via Plugins → Add New → Upload Plugin, or download from the MxChat add-ons gallery.
Activate via Plugins → Installed Plugins. MxChat (mxchat-basic) must already be active or you'll see a dependency notice.
Confirm your MxChat Pro license is active under MxChat → License. The Forms admin will warn you if it isn't.
Find the admin under MxChat → Form Collection. From there: "Create New Form" for a standard form, or pick "Wizards" to build a Conditional or Branching wizard.
Add fields, set trigger phrases (the chatbot will match these via embeddings), pick role restrictions and message-count triggers as needed, then save.

Settings

Form Fields

Drag-and-drop field builder. Supported types include text, email, dropdown, checkbox, radio, and textarea. Each field has a label, optional placeholder, required/optional toggle, and a "Use label as placeholder" option for tighter layouts.

Trigger Phrases

Tag-style input where each phrase becomes its own embedding vector for accurate intent matching. Add as many as you need — the AI fires the form when the user message is semantically similar to any one of them. Legacy comma-separated phrase groups still work and display as a single "legacy" tag.

Similarity Threshold

Per-form slider controlling how closely a user message has to match a trigger phrase before the form fires. Raise it if forms trigger too eagerly; lower it if intent is being missed.

Message-Count Trigger

Fire the form after N total messages in the session, ignoring intent matching. Useful for "ask for email after the third exchange"-style nudges. Set to 0 to disable.

Role Restrictions

Limit triggering to specific WordPress roles (admin, subscriber, customer, visitor, etc.). The form is invisible to anyone outside the allowed roles.

Regex Pattern (optional)

Advanced match field. If set, the user message also has to match this regex before the form will fire — a useful way to lock a form to messages that contain a phone number, postcode, or other concrete pattern.

Success Message

The response text shown in chat after a successful submission. Supports basic placeholders for the submitted field values.

Chat Input Blocking

Toggle that disables the chat textarea while the form is on-screen, forcing the user to either submit or cancel before they can keep typing. Use it when you need complete responses.

Email Notifications

Per-form email address (or comma-separated list) that receives a notification on every submission. Defaults to the WP admin email. Each notification uses human-readable field labels, sets a Reply-To header to the visitor's submitted email, and optionally attaches the full chat transcript as a .txt file.

Custom Subject Line

Per-form email subject override. Leave blank to use the form title.

Features

Custom form builder: Multiple field types (text, dropdown, checkbox, radio, textarea, email) with validation and required-field control — build the form once, fire it as many times as the chatbot needs.
Conditional Wizards: Linear question flows with outcome rules based on answer combinations. Great for guided lead-qualification where you want every visitor to answer the same set of questions.
Branching Wizards: Dynamic decision trees where each answer determines the next question. Ideal for product recommendations, troubleshooting paths, and eligibility checks where the path depends on what the visitor said.
Action-based triggering: Forms appear naturally during chats when the AI detects relevant intent. No "open form" CTA needed — the conversation just routes into the form when it makes sense.
Message-based triggers: Fire a form after a set number of messages for more controlled engagement (e.g. ask for contact info after the third exchange).
Role-specific forms: Restrict triggers to specific WordPress user roles so you can collect different data from admins, customers, and visitors.
Wizard session tracking: Completion rates, full session history per wizard, and a Delete All button to clean up old data. Export to CSV for iteration analysis.
Custom email notifications + transcript: Route submissions to any inbox with the full chat conversation attached as a .txt file, plus a Reply-To header so replies go straight to the visitor.
Chat input blocking + CSV export: Block free-text while a form is open to guarantee complete responses, and export every submission to CSV with one click.

API & Integration

MxChat Forms registers itself with MxChat's trigger system via the standard filter pipeline. Useful hooks:

mxchat_available_callbacks — Forms registers mxchat_handle_form_collection and mxchat_handle_wizard_collection so the chatbot can route messages into a form or wizard handler.
mxchat_pre_process_message — used to check message-count triggers on every incoming message.
mxchat_prepare_context — injects form/wizard state into the AI context so the model knows when a form is pending (shown but not submitted) vs successfully submitted, and adjusts its replies accordingly.

AJAX endpoints (all nonce-protected via mxchat_forms_nonce):

mxchat_submit_form — public submission handler.
mxchat_wizard_answer / mxchat_wizard_cancel / mxchat_wizard_resume_check — wizard step handlers.
mxchat_export_submissions — admin-only CSV export.

Email notifications go through standard wp_mail(), so any SMTP plugin (WP Mail SMTP, FluentSMTP, etc.) catches them automatically. There is no native webhook endpoint in 1.2.6 — for outbound HTTP, route the submission via the email-to-webhook pattern or hook the AJAX handler.

Daily cron event mxchat_forms_wizard_cleanup sweeps abandoned wizard sessions so the table doesn't bloat.

Requirements

MxChat (mxchat-basic): Required, active.
MxChat Pro License: Required — activate under MxChat → License. See https://mxchat.ai/pricing/.
WordPress: 5.0 or newer.
PHP: 7.4 or newer.
Third-party: None. Uses your existing MxChat AI provider (OpenAI / Gemini / xAI / etc.) for trigger phrase embeddings — no separate API key needed.

Troubleshooting

Form never appears in chat

Check three things in order: (1) MxChat Pro license is active — the admin shows a warning notice if it isn't; (2) the form's enabled toggle is on; (3) raise the similarity threshold or add more trigger phrases. If the form has role restrictions, confirm you're testing as a user in an allowed role.

Database update issue notice on admin pages

If the regex_pattern column is missing from the forms or intents table, the plugin shows an "update issue detected" notice. Deactivate and reactivate the plugin to re-run the schema migration.

Apostrophes in form titles showing as `I\'m`

Fixed in 1.2.6. Update the plugin and re-save the affected form — the heal routine strips accumulated backslashes automatically.

Notification emails not arriving

Test wp_mail() deliverability with any SMTP plugin first. If your test email arrives but form notifications don't, check the per-form email address setting (typos are the usual cause). Confirm the form actually submitted by checking MxChat → Form Collection → Submissions.

Duplicate submissions on a single click

Fixed in 1.2.3. Update to the current version — the fix includes a 5-second server-side dedup window plus a per-form click guard.

Wizard session table growing without bound

The daily mxchat_forms_wizard_cleanup cron sweeps abandoned sessions automatically. Confirm WP-Cron is running (some hosts disable it) — if it isn't, trigger it manually via WP-CLI or set up a real system cron pointing at wp-cron.php.

Last reviewed by Sage on 2026-05-21. Spotted an issue? Open a ticket and we'll patch the doc.