فرم اطلاعات مهمان در چت بات

یکی از مهم‌ترین چالش‌ها در ارائه خدمات پشتیبانی آنلاین، تعامل با کاربران ناشناس (مهمان) است. زمانی که کاربری بدون ورود به حساب کاربری (Log in) قصد استفاده از چت‌بات هوش مصنوعی را دارد، شناخت هویت او برای پیگیری‌های بعدی، ارجاع به کارشناس یا ارائه خدمات دقیق‌تر بسیار حیاتی است.

سیستم چت‌بات هوشمند همیار تولز، به صورت پیش‌فرض مجهز به یک فرم دریافت اطلاعات است که پیش از شروع گفتگو، نام و شماره موبایل کاربر را دریافت می‌کند. اما نیازهای کسب‌وکار شما ممکن است فراتر از این دو فیلد باشد؛ شاید نیاز داشته باشید کد ملی، ایمیل، واحد سازمانی، شماره سفارش، پذیرش قوانین یا حتی احراز هویت پیامکی (OTP) را نیز دریافت کنید.

در این مستندات، به شما نشان می‌دهیم که چگونه با استفاده از قلاب‌های (Hooks) قدرتمند تعبیه شده در هسته افزونه، بدون دست‌زدن به فایل‌های اصلی افزونه، این فرم را کاملا شخصی‌سازی کنید، فیلدهای جدید بیافزایید و یا فیلدهای پیش‌فرض را مدیریت کنید.

این قابلیت چگونه کار می‌کند؟

معماری فرم مهمان در چت‌بات همیار تولز بر پایه رویدادهای جاوااسکریپت و قلاب‌های وردپرس بنا شده است. این معماری به توسعه‌دهندگان اجازه می‌دهد تنها با افزودن قطعه‌کدهای استاندارد در قالب سایت (یا زیرمنوی «قلاب‌های همیار تولز»)، رفتار فرم را تغییر دهند. فرآیند کلی به شرح زیر است:

1. بررسی وضعیت کاربر: چت‌بات بررسی می‌کند که آیا کاربر لاگین کرده است یا خیر.
2. نمایش فرم: اگر کاربر مهمان باشد، فرم دریافت اطلاعات نمایش داده می‌شود.
3. تزریق فیلدها: شما می‌توانید با کدهای ساده، فیلدهای HTML دلخواه خود را به این فرم اضافه کنید.
4. رهگیری ارسال: زمانی که کاربر دکمه «ثبت اطلاعات و شروع» را می‌زند، سیستم یک رویداد خاص را اجرا می‌کند. شما می‌توانید این رویداد را گرفته، داده‌های فیلدهای خود را به آن اضافه کنید، اعتبارسنجی کنید و یا حتی جلوی ارسال فرم را بگیرید.
5. ذخیره‌سازی خودکار: هر داده‌ای که اضافه کنید، به صورت ساختار JSON در دیتابیس ذخیره و در پنل مدیریت نمایش داده می‌شود.

نکته کلیدی: چه ۲ فیلد بفرستید چه ۲۰ فیلد، هسته افزونه بدون هیچ تنظیم اضافه‌ای همه را ذخیره و در پنل «مدیریت چت‌ها» نمایش می‌دهد.

کاربردهای رایج

• احراز هویت دقیق: دریافت کد ملی برای سایت‌های بیمه، خدمات دولتی یا فروش اقساطی.
• دسته‌بندی درخواست: استفاده از لیست کشویی (Select) برای اینکه کاربر مشخص کند سوالش مربوط به «فروش»، «پشتیبانی فنی» یا «مالی» است تا گفتگو سریع‌تر مسیریابی شود.
• اطلاعات تماس ثانویه: دریافت ایمیل یا شماره ثابت در کنار شماره موبایل.
• قوانین و مقررات: افزودن چک‌باکس «قوانین را می‌پذیرم» که تا تیک نخورد، اجازه چت ندهد.
• انعطاف‌پذیری در UX: شاید بخواهید فیلد شماره موبایل را اختیاری یا حتی حذف کنید و به جای آن ایمیل نمایش دهید.
• اعتبارسنجی پیشرفته: اتصال به API پیامک (OTP) و احراز هویت پیامکی قبل از شروع چت.

مرجع فنی: رویداد hmyt:guest-submit

قلب این سیستم یک رویداد اختصاصی جاوااسکریپتی به نام hmyt:guest-submit است که دقیقا در لحظه کلیک روی دکمه «ثبت اطلاعات و شروع» فراخوانی می‌شود. زمانی که این رویداد را در کد خود دریافت می‌کنید، یک شیء data در اختیار شما قرار می‌گیرد که شامل متدها و پراپرتی‌های زیر است:

• data.guestInfo : حاوی داده‌های ارسالی به سرور. هر کلیدی که به این آبجکت اضافه کنید (مثلا data.guestInfo['ایمیل']) در دیتابیس ذخیره می‌شود. به صورت پیش‌فرض شامل name و mobile است.
• data.elements : دسترسی مستقیم به المان‌های DOM فرم جاری. شامل:
  • container: دیو اصلی فرم (برای جستجوی فیلدها از container.find(...) استفاده کنید)
  • submitBtn: دکمه کلیک شده
  • nameInput: فیلد نام
  • mobileInput: فیلد موبایل
• data.fail(message) : یک متد برای نمایش پیام توست خطا به کاربر و توقف ارسال فرم.
• data.proceed() : متدی برای ادامه ثبت‌نام و ورود به گفتگو. فقط زمانی لازم است که ابتدا e.preventDefault() زده باشید (مثل اعتبارسنجی ناهمگام یا OTP).
• e.preventDefault() : متد استاندارد jQuery برای جلوگیری از ارسال فرم (مفید برای اعتبارسنجی یا توقف عملیات).

دو الگوی اصلی کار

۱) اعتبارسنجی همگام (Synchronous): اگر داده معتبر بود، فقط آن را به guestInfo اضافه کنید و کاری نکنید؛ فرم خودش ادامه می‌دهد. اگر نامعتبر بود، e.preventDefault() به همراه data.fail(...).

۲) اعتبارسنجی ناهمگام (Asynchronous / OTP): همیشه اول e.preventDefault() بزنید تا فرم متوقف شود، سپس درخواست AJAX خود را بفرستید و پس از موفقیت، data.proceed() را صدا بزنید.

مرجع فنی: قلاب‌های PHP

علاوه بر رویداد جاوااسکریپت، دو قلاب سمت سرور نیز در اختیار دارید:

• hmyt_ai_guest_form_fields (filter) — برای فعال یا غیرفعال‌کردن فیلدهای پیش‌فرض (نام و موبایل).
• hmyt_ai_guest_form_after_mobile_field (action) — برای تزریق HTML دلخواه بلافاصله بعد از فیلد موبایل، بدون نیاز به jQuery (مناسب افزودن فیلد OTP یا هر ورودی ثابت).

چند مثال کاربردی آماده

کدهای زیر را می‌توانید مستقیما در زیرمنوی قلاب‌های همیار تولز قرار دهید.

۱) مدیریت فیلدهای پیش‌فرض (حذف نام یا موبایل)

با فیلتر hmyt_ai_guest_form_fields می‌توانید فیلد نام یا موبایل را غیرفعال (مخفی و غیراجباری) کنید.

add_filter('hmyt_ai_guest_form_fields', function($fields) {
    $fields['name_active']   = true;   // فیلد نام فعال بماند
    $fields['mobile_active'] = false;  // غیرفعال‌سازی فیلد موبایل
    return $fields;
});

۲) افزودن فیلد کد ملی (با اعتبارسنجی ۱۰ رقمی)

add_action('wp_footer', function() {
    ?>
    <script>
    jQuery(document).ready(function($) {
        $('#hmyt-guest-mobile').closest('.hmyt-form-group').before('<div class="hmyt-form-group"><input type="number" id="custom-nid" placeholder="کد ملی" style="width:100%;padding:10px;border:1px solid #ddd;border-radius:8px;"></div>');

        $(document).on('hmyt:guest-submit', function(e, data) {
            const val = data.elements.container.find('#custom-nid').val();
            if (!val || val.length !== 10) {
                e.preventDefault();
                data.fail('کد ملی باید دقیقاً ۱۰ رقم باشد.');
                return;
            }
            data.guestInfo['کد ملی'] = val;
        });
    });
    </script>
    <?php
}, 99);

۳) افزودن لیست کشویی «واحد مربوطه»

برای مسیریابی سریع درخواست به واحد درست.

add_action('wp_footer', function() {
    ?>
    <script>
    jQuery(document).ready(function($) {
        const selectHtml = `
            <div class="hmyt-form-group">
                <select id="custom-dept" style="width:100%;padding:10px;border:1px solid #ddd;border-radius:8px;background:#fff;">
                    <option value="پشتیبانی">پشتیبانی فنی</option>
                    <option value="فروش">واحد فروش</option>
                    <option value="مالی">امور مالی</option>
                </select>
            </div>`;

        $('#hmyt-guest-name').closest('.hmyt-form-group').after(selectHtml);

        $(document).on('hmyt:guest-submit', function(e, data) {
            data.guestInfo['واحد'] = data.elements.container.find('#custom-dept').val();
        });
    });
    </script>
    <?php
}, 99);

۴) فیلد شماره سفارش (اختیاری)

add_action('wp_footer', function() {
    ?>
    <script>
    jQuery(document).ready(function($) {
        $('#hmyt-guest-mobile').closest('.hmyt-form-group').after('<div class="hmyt-form-group"><input type="number" id="order-id" placeholder="شماره سفارش (اگر دارید)" style="width:100%;padding:10px;border:1px solid #ddd;border-radius:8px;"></div>');

        $(document).on('hmyt:guest-submit', function(e, data) {
            const oid = data.elements.container.find('#order-id').val();
            if (oid) data.guestInfo['شماره سفارش'] = oid;
        });
    });
    </script>
    <?php
}, 99);

۵) چک‌باکس اجباری قوانین و مقررات

تا تیک نخورد، اجازه شروع چت داده نمی‌شود.

add_action('wp_footer', function() {
    ?>
    <script>
    jQuery(document).ready(function($) {
        $('#hmyt-guest-submit-btn').before('<div style="display:flex;align-items:center;gap:5px;font-size:12px;"><input style="width:auto;" type="checkbox" id="custom-terms"> <label for="custom-terms">قوانین سایت را می‌پذیرم.</label></div>');

        $(document).on('hmyt:guest-submit', function(e, data) {
            if (!data.elements.container.find('#custom-terms').is(':checked')) {
                e.preventDefault();
                data.fail('لطفا ابتدا قوانین را بپذیرید.');
            }
        });
    });
    </script>
    <?php
}, 99);

۶) افزودن فیلد ایمیل (با اعتبارسنجی فرمت)

add_action('wp_footer', function() {
    ?>
    <script>
    jQuery(document).ready(function($) {
        $('#hmyt-guest-mobile').closest('.hmyt-form-group').after('<div class="hmyt-form-group"><input type="email" id="custom-email" placeholder="ایمیل" style="width:100%;padding:10px;border:1px solid #ddd;border-radius:8px;"></div>');

        $(document).on('hmyt:guest-submit', function(e, data) {
            const email = data.elements.container.find('#custom-email').val().trim();
            const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
            if (!emailRegex.test(email)) {
                e.preventDefault();
                data.fail('لطفا یک ایمیل معتبر وارد کنید.');
                return;
            }
            data.guestInfo['ایمیل'] = email;
        });
    });
    </script>
    <?php
}, 99);

۷) جایگزینی موبایل با ایمیل

ترکیب فیلتر PHP (برای حذف موبایل) و رویداد JS (برای افزودن ایمیل الزامی). این نمونه نشان می‌دهد چگونه دو قلاب کنار هم کار می‌کنند.

// گام ۱: غیرفعال‌سازی فیلد پیش‌فرض موبایل
add_filter('hmyt_ai_guest_form_fields', function($fields) {
    $fields['mobile_active'] = false;
    return $fields;
});

// گام ۲: افزودن ایمیل الزامی به‌جای آن
add_action('wp_footer', function() {
    ?>
    <script>
    jQuery(document).ready(function($) {
        $('#hmyt-guest-name').closest('.hmyt-form-group').after('<div class="hmyt-form-group"><input type="email" id="custom-email" placeholder="ایمیل" required style="width:100%;padding:10px;border:1px solid #ddd;border-radius:8px;"></div>');

        $(document).on('hmyt:guest-submit', function(e, data) {
            const email = data.elements.container.find('#custom-email').val().trim();
            const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
            if (!emailRegex.test(email)) {
                e.preventDefault();
                data.fail('لطفا یک ایمیل معتبر وارد کنید.');
                return;
            }
            data.guestInfo['ایمیل'] = email;
        });
    });
    </script>
    <?php
}, 99);

۸) فیلد توضیحات (Textarea) اختیاری

برای گرفتن شرح کوتاه درخواست پیش از شروع گفتگو.

add_action('wp_footer', function() {
    ?>
    <script>
    jQuery(document).ready(function($) {
        $('#hmyt-guest-submit-btn').before('<div class="hmyt-form-group"><textarea id="custom-subject" rows="2" placeholder="موضوع درخواست (اختیاری)" style="width:100%;padding:10px;border:1px solid #ddd;border-radius:8px;resize:vertical;"></textarea></div>');

        $(document).on('hmyt:guest-submit', function(e, data) {
            const subject = data.elements.container.find('#custom-subject').val().trim();
            if (subject) data.guestInfo['موضوع درخواست'] = subject;
        });
    });
    </script>
    <?php
}, 99);

۹) پرکردن خودکار فیلد از پارامتر URL (کمپین/منبع ورود)

اگر کاربر از یک لینک کمپین (مثلا ?utm_source=instagram) وارد شده، منبع را به صورت پنهان همراه اطلاعات ذخیره کنید تا در پنل بدانید کاربر از کجا آمده است.

add_action('wp_footer', function() {
    ?>
    <script>
    jQuery(document).ready(function($) {
        $(document).on('hmyt:guest-submit', function(e, data) {
            const params = new URLSearchParams(window.location.search);
            const source = params.get('utm_source');
            if (source) data.guestInfo['منبع ورود'] = source;
        });
    });
    </script>
    <?php
}, 99);

۱۰) اعتبارسنجی ناهمگام و احراز هویت پیامکی (OTP)

این پیشرفته‌ترین سناریو است و نشان می‌دهد چگونه از e.preventDefault() به همراه data.proceed() استفاده کنید. الگو ساده است:

1. با e.preventDefault() ارسال را متوقف کنید.
2. کد را با AJAX به سرور خود بفرستید و بررسی کنید.
3. اگر تأیید شد، data.guestInfo را کامل کرده و data.proceed() را صدا بزنید تا گفتگو آغاز شود.
4. اگر رد شد، data.fail(...) را نمایش دهید.

add_action('wp_footer', function() {
    ?>
    <script>
    jQuery(document).ready(function($) {
        // افزودن فیلد کد تأیید بعد از موبایل
        $('#hmyt-guest-mobile').closest('.hmyt-form-group').after('<div class="hmyt-form-group"><input type="number" id="custom-otp" placeholder="کد تأیید پیامک‌شده" style="width:100%;padding:10px;border:1px solid #ddd;border-radius:8px;"></div>');

        $(document).on('hmyt:guest-submit', function(e, data) {
            // همیشه اول ارسال را متوقف می‌کنیم چون بررسی ناهمگام است
            e.preventDefault();

            const otp    = data.elements.container.find('#custom-otp').val();
            const mobile = data.guestInfo.mobile;

            if (!otp) {
                data.fail('لطفا کد تأیید را وارد کنید.');
                return;
            }

            // نمونه فراخوانی سرور شما برای بررسی کد
            $.post('/wp-admin/admin-ajax.php', {
                action: 'my_verify_otp',
                mobile: mobile,
                otp: otp
            }, function(res) {
                if (res && res.success) {
                    // تأیید موفق: داده را ذخیره و گفتگو را آغاز کن
                    data.guestInfo['موبایل تأییدشده'] = 'بله';
                    data.proceed();
                } else {
                    data.fail('کد تأیید نادرست است. دوباره تلاش کنید.');
                }
            }).fail(function() {
                data.fail('خطا در ارتباط با سرور. دوباره تلاش کنید.');
            });
        });
    });
    </script>
    <?php
}, 99);

برای تزریق فیلد OTP به صورت سمت‌سرور (بدون jQuery) می‌توانید از اکشن hmyt_ai_guest_form_after_mobile_field هم استفاده کنید. نمونه زیر همان فیلد را از طریق PHP اضافه می‌کند:

add_action('hmyt_ai_guest_form_after_mobile_field', function() {
    echo '<div class="hmyt-form-group"><input type="number" id="custom-otp" placeholder="کد تأیید پیامک‌شده" style="width:100%;padding:10px;border:1px solid #ddd;border-radius:8px;"></div>';
});

مکانیزم ذخیره‌سازی

هسته چت‌بات همیار تولز طوری طراحی شده که تمام اطلاعات ارسالی در آبجکت guestInfo را به صورت یک ساختار JSON با پشتیبانی کامل از یونیکد (فارسی) در دیتابیس ذخیره می‌کند. بنابراین کلیدهای فارسی مثل 'کد ملی' یا 'واحد' بدون هیچ خطایی ذخیره می‌شوند. چه شما ۲ فیلد پیش‌فرض را ارسال کنید و چه ۲۰ فیلد سفارشی جدید، سیستم بدون مشکل آن‌ها را دریافت و ذخیره می‌کند.

نمایش خودکار در پنل مدیریت

بخش «مدیریت چت‌ها» در پیشخوان وردپرس نیز کاملا داینامیک طراحی شده و به صورت خودکار داده‌های ذخیره شده را پردازش کرده و نمایش می‌دهد:

• فیلدهای نام و موبایل با آیکون اختصاصی نمایش داده می‌شوند.
• سایر فیلدهای سفارشی به صورت خودکار با آیکون عمومی و همان کلیدی که تعیین کرده‌اید به عنوان برچسب نمایش داده می‌شوند.

به همین دلیل توصیه می‌شود کلید فیلدها را خوانا و فارسی انتخاب کنید (مثلا data.guestInfo['کد ملی'] به جای data.guestInfo['nid']) تا در پنل مدیریت زیبا و قابل‌فهم دیده شوند.

نکات مهم و بهترین شیوه‌ها

• زمان‌بندی هوک: همیشه از wp_footer با اولویت 99 استفاده کنید تا اسکریپت شما بعد از بارگذاری چت‌بات اجرا شود.
• جستجوی امن فیلدها: برای دسترسی به فیلدهایتان از data.elements.container.find('#your-id') استفاده کنید تا فقط داخل فرم جاری جستجو شود.
• proceed() فقط پس از preventDefault(): اگر ارسال را متوقف نکرده‌اید نیازی به proceed() نیست؛ فرم خودش ادامه می‌دهد. آن را دو بار صدا نزنید.
• اعتبارسنجی سمت سرور: اعتبارسنجی جاوااسکریپت برای تجربه کاربری است؛ برای داده‌های حساس (مثل کد ملی یا OTP) حتما در سمت سرور هم بررسی انجام دهید.
• کلیدهای خوانا: کلید هر فیلد در پنل مدیریت به عنوان برچسب استفاده می‌شود؛ پس آن را معنادار انتخاب کنید.