چت بلادرنگ برای وردپرس

WP Persian Chat

افزونهٔ پیام‌رسانی برای کاربران واردشده با REST API، چت خصوصی و گروهی، رسانهٔ قابل‌پیکربندی، رمزنگاری سرتاسری اختیاری در چت دو نفره، ویجت سایت، شورت‌کد تمام‌صفحه و پیام‌رسان پیشخوان.

شروع مستندات شورت‌کد تمام‌صفحه

توسعه‌دهنده

Alireza Aminzadeh

هزینه استفاده

رایگان

منشأ و بومی‌سازی

کاملاً ایرانی

زبان رابط و مستندات

فارسی (RTL)

معرفی و پیش‌نیاز

WP Persian Chat افزونه‌ای است که تمام endpointهای چت را از مسیر wppc/v1 در اختیار می‌گذارد. هر درخواست REST (به‌جز صفحات عمومی وردپرس) نیازمند ورود کاربر است؛ مهمان‌ها فقط محتوای جایگزین شورت‌کد را می‌بینند.

  • نسخهٔ فعلی در کد: 1.0.4 — با به‌روزرسانی افزونه، مقدار wppc_db_version در هنگام plugins_loaded با نسخه همگام می‌شود و جداول با dbDelta به‌روز می‌مانند.
  • وردپرس و PHP: سازگار با همان نسخه‌هایی که هستهٔ وردپرس شما پشتیبانی می‌کند؛ برای آپلود و رسانه از توابع استاندارد wp_handle_upload و در صورت انتخاب، کتابخانهٔ رسانه استفاده می‌شود.
  • Text domain: wp-persian-chat برای ترجمه رشته‌ها.
تفاوت با WebSocket خالص: به‌روزرسانی گفتگو در فرانت‌اند فعلی با بارگذاری دوره‌ای (polling) انجام می‌شود (مثلاً حدود هر ۳ ثانیه برای پیام‌های باز). معماری REST همچنان امکان اتصال به مکانیزم بلادرنگ دیگر در آینده را حفظ می‌کند.

رابط‌های کاربری (سه سطح)

۱. ویجت شناور سایت

  • با wp_footer برای کاربران لاگین‌شده رندر می‌شود؛ استایل و اسکریپت عمومی فقط در این حالت بارگذاری می‌شود.
  • اگر برگهٔ جاری در محتوا شورت‌کد [wppc_web_chat] داشته باشد، ویجت شناور نمایش داده نمی‌شود تا با چت تمام‌صفحه تداخل نکند.
  • تب‌های کاربران و گروه‌ها، جستجو، لیست گفتگو، ارسال متن، ایموجی، پیوست فایل، ضبط صوت از مرورگر (دکمه میکروفون).
  • منوی تنظیمات داخل ویجت: حالت تاریک، اندازهٔ متن (۱۲–۲۰px)، صدای پیام جدید، ارسال با Enter (در غیر این صورت Ctrl+Enter).
  • ظاهر کلی (رنگ اصلی، موقعیت پایین راست/چپ، پیام خوش‌آمد) از تنظیمات پیشخوان قابل تغییر است.

۲. چت وب تمام‌صفحه (شورت‌کد)

جدا از ویجت؛ برای مهمان محتوای قابل‌ویرایش از تنظیمات (ویرایشگر وردپرس) نمایش داده می‌شود — جزئیات در بخش پایانی فهرست.

۳. پیام‌رسان پیشخوان

  • منوی سطح‌بالا «چت وردپرس» با آیکن dashicons-format-chat؛ زیرمنو «پیام‌رسان» همان رابط چت در ادمین است.
  • دسترسی منو و تنظیمات: قابلیت manage_options.
  • اسکریپت پیام‌رسان همان rest_url('wppc/v1/') و محدودیت‌های آپلود محلی‌شده (wppc_get_upload_limits_for_client) را دریافت می‌کند.

پیام خصوصی (۱ به ۱)

  • حداکثر طول متن: ۲۰۰۰ کاراکتر (اعتبارسنجی در سرور).
  • محتوا: می‌تواند متن خالی نباشد با ترکیب message و/یا attachment_id و/یا media_url؛ نوع پیام با message_type (مثلاً text، image، video، audio، file).
  • رمزنگاری: فیلد is_encrypted برای ذخیرهٔ متن رمزشده در دیتابیس؛ فقط در چت دو نفره معنا دارد (جزئیات در بخش E2E).
  • صفحه‌بندی تاریخچه: پارامترهای offset و limit (پیش‌فرض ۵۰)؛ حداکثر ۱۰۰ پیام در هر درخواست.
  • ویرایش: فقط فرستندهٔ همان پیام؛ متن جدید همان سقف ۲۰۰۰ کاراکتر.
  • حذف: حذف نرم با پر شدن deleted_at؛ پیام‌های حذف‌شده در لیست نمایش داده نمی‌شوند تا کرون بعدی آن‌ها را پاک کند.
  • پیام‌های ذخیره‌شده: گفتگو با خودتان — همان کاربر به‌عنوان فرستنده و گیرنده؛ در API کاربران اولین آیتم لیست بدون جستجو با برچسب «پیام‌های ذخیره شده» نمایش داده می‌شود.

رمزنگاری سرتاسری (E2E)

  • از تنظیمات → امنیت و حریم خصوصی با گزینهٔ «رمزنگاری End-to-End» فعال می‌شود (wppc_enable_e2e).
  • کلید عمومی کاربر در متای کاربر wppc_public_key ذخیره می‌شود؛ مسیرهای POST wppc/v1/keys و GET wppc/v1/keys/{user_id} برای ذخیره و دریافت استفاده می‌شوند.
  • متن رمزشده در فیلد پیام ذخیره می‌شود؛ رمزگشایی سمت کلاینت است. چت گروهی در سرور به‌صورت متن عادی ذخیره می‌شود (is_encrypted = 0 در پیام گروه).

چت گروهی

  • ایجاد گروه: نام اجباری؛ توضیحات و avatar_url اختیاری. سازنده به‌عنوان عضو با نقش admin ثبت می‌شود.
  • لیست گروه‌ها: فقط گروه‌هایی که کاربر جاری عضو آن است.
  • جزئیات / ویرایش / حذف: مشاهده و ویرایش مشخصات و حذف کامل گروه فقط برای مدیر گروه. حذف گروه، پیام‌ها و عضویت‌ها را از دیتابیس حذف می‌کند.
  • اعضا: مدیر می‌تواند عضو اضافه کند؛ حذف عضو توسط مدیر یا خروج خود عضو (حذف رکورد خودش).
  • پیام گروه: همان قوانین طول و پیوست مانند چت خصوصی؛ نمایش با نام و آواتار فرستنده.
  • ویرایش / حذف نرم پیام گروه: فقط برای فرستندهٔ همان پیام (مسیرهای جدا از پیام خصوصی با پیشوند /groups/messages/).
آپلود امن و قابل‌پیکربندی

رسانه، آپلود و ذخیره‌سازی

فایل‌ها از مسیر REST استاندارد بارگذاری می‌شوند؛ سقف حجم و نوع MIME با تنظیمات وردپرس و گزینه‌های افزونه هماهنگ است و همان محدودیت‌ها در فرانت‌اند هم به کاربر نشان داده می‌شود.

Endpoint POST wppc/v1/media/upload

فیلد فایل استاندارد؛ پارامتر context برابر chat یا avatar.

پیوست‌های چت

تصویر (JPEG, GIF, PNG, WebP)، ویدیو (MP4, MPEG, MOV, WebM)، صوت (MP3/M4A, WAV, OGG, WebA) — هر دسته با چک‌باکس جدا در تنظیمات.

پیام صوتی

فایل‌هایی مثل voice-message.weba / .webm با فیلتر fix_voice_webm_filetype به audio/webm نرمال می‌شوند تا با محدودیت‌های وردپرس هم‌راستا بماند.

آواتار گروه

JPEG, PNG, GIF, WebP به‌صورت جداگانه قابل فعال/غیرفعال؛ حداکثر حجم ۰٫۱ تا ۵۰ مگابایت.

wp_media

فایل به کتابخانهٔ رسانهٔ وردپرس متصل می‌شود؛ مدیریت و مجوزها همان الگوی هسته است.

custom_dir

ذخیره در uploads/wppc-media با .htaccess (Deny from all)؛ دانلود فقط از مسیر REST media/download/{file} برای کاربر لاگین.

تنظیمات پیشخوان (صفحهٔ تنظیمات چت)

مسیر: چت وردپرس → تنظیمات. گزینه‌ها در گروه wppc_options_group ثبت می‌شوند.

گزینه کاربرد
wppc_welcome_message پیام خوش‌آمد در ویجت (پیش‌فرض: «سلام! چطور می‌توانیم کمکتان کنیم؟»).
wppc_chat_position right یا left — گوشهٔ ویجت.
wppc_primary_color رنگ اصلی رابط (پیش‌فرض آبی).
wppc_media_storage_type wp_media یا custom_dir.
wppc_chat_max_file_mb حداکثر حجم فایل چت؛ ۰٫۱ تا ۱۰۰ (پیش‌فرض ۵).
wppc_chat_allow_image|video|audio سه فلگ مجزا؛ اگر همه غیرفعال شوند، سرور در عمل همهٔ انواع پایه را برمی‌گرداند تا آپلود کاملاً قفل نشود.
wppc_avatar_max_file_mb ۰٫۱ تا ۵۰ مگابایت برای آواتار گروه.
wppc_avatar_allow_* jpeg, png, gif, webp — هر کدام جدا.
wppc_enable_e2e روشن/خاموش کردن مسیر E2E در کلاینت (مقدار در wppc_data.enable_e2e).
wppc_shortcode_fallback_content HTML مهمان برای شورت‌کد؛ با ویرایشگر کامل (دکمه‌های رسانه و …).

فهرست کاربران و حریم خصوصی

Endpoint GET wppc/v1/users رفتار ترکیبی دارد:

  • بدون پارامتر search: ابتدا آیتم «پیام‌های ذخیره شده»، سپس تا ۲۰ کاربر که اخیراً با آن‌ها مکالمهٔ دوطرفه داشته‌اید (فقط ردیف‌هایی که فرستنده و گیرنده متفاوتند؛ چت با خود در این فهرست «اخیر» نمی‌آید)، با مرتب‌سازی بر اساس زمان آخرین پیام.
  • با search: اگر طول رشته حداقل ۳ کاراکتر باشد، جستجو در نام نمایشی، نام کاربری، nicename و ایمیل با حداکثر ۲۰ نتیجه؛ کاربر جاری از نتایج حذف می‌شود.
  • هدف: عدم افشای فهرست کامل کاربران سایت با یک درخواست خالی.

محدودیت نرخ، خطاها و GDPR

محدودیت نرخ (سرور)

  • ارسال پیام (خصوصی یا گروه): حداکثر ۱۰ پیام در هر ۱۰ ثانیه برای هر کاربر (ترنزینت با کلید wppc_rate_limit_msg_{user_id})؛ در صورت عبور، پاسخ ۴۲۹ با متن فارسی.
  • ساخت گروه: حداکثر یک بار در دقیقه (wppc_rate_limit_grp_{user_id}، ۶۰ ثانیه).

حذف دائم پیام‌های حذف‌شدهٔ نرم

  • هوک کرون: wppc_gdpr_hard_delete_cron با زمان‌بندی روزانه (ثبت در فعال‌سازی افزونه).
  • رکوردهایی که deleted_at دارند و قدیمی‌تر از ۳۰ روز هستند از جداول wppc_messages و wppc_group_messages به‌طور فیزیکی حذف می‌شوند.
  • با غیرفعال‌سازی افزونه، رویداد زمان‌بندی‌شده لغو می‌شود (WPPC_Deactivator)؛ دادهٔ جداول دست‌نخورده می‌ماند مگر حذف کامل افزونه از طریق uninstall.

مرجع REST API (wppc/v1)

همه با permission_callback معادل is_user_logged_in() مگر خلاف آن ذکر شود. درخواست‌ها معمولاً هدر nonce REST وردپرس را همراه دارند.

مسیر متد توضیح کوتاه
/users GET فهرست ترکیبی ذخیره‌شده + اخیر + جستجو؛ پارامتر search اختیاری.
/messages/{user_id} GET تاریخچه دوطرفه با همان کاربر؛ offset، limit (حداکثر ۱۰۰).
/messages/send POST ارسال پیام خصوصی؛ بدنه شامل receiver_id، message، is_encrypted، attachment_id، media_url، message_type.
/messages/{id} PATCH ویرایش متن توسط فرستنده.
/messages/{id} DELETE حذف نرم.
/media/upload POST multipart؛ پارامتر context: chat یا avatar.
/media/download/{file_name} GET خروجی فایل از پوشه اختصاصی (نام فایل با کاراکترهای امن).
/groups GET / POST لیست عضویت‌ها / ایجاد گروه.
/groups/{id} GET / PATCH / DELETE مشاهده (عضو)، ویرایش/حذف (مدیر).
/groups/{id}/members GET / POST لیست اعضا؛ افزودن عضو توسط مدیر.
/groups/{id}/members/{user_id} DELETE حذف عضو یا خروج خود کاربر.
/groups/{id}/messages GET پیام‌های گروه با نام فرستنده؛ صفحه‌بندی مانند خصوصی.
/groups/{id}/messages/send POST ارسال در گروه؛ بدون E2E در سرور.
/groups/messages/{id} PATCH / DELETE ویرایش / حذف نرم پیام گروه توسط فرستنده.
/keys POST ذخیرهٔ public_key کاربر جاری.
/keys/{user_id} GET خواندن کلید عمومی کاربر.

دیتابیس، متای کاربر و چرخهٔ عمر

جداول سفارشی (پیشوند جدول وردپرس)

  • wppc_messages — پیام خصوصی؛ فیلدها از جمله sender_id، receiver_id، message_text، message_type، attachment_id، media_url، is_encrypted، is_read، created_at، updated_at، deleted_at.
  • wppc_groups — name، description، avatar_url، created_by، created_at.
  • wppc_group_members — کلید ترکیبی (group_id, user_id)، role، joined_at.
  • wppc_group_messages — مشابه پیام خصوصی با group_id؛ is_encrypted در درج گروه صفر است.

متای کاربر

wppc_public_key برای E2E.

حذف افزونه

فایل uninstall.php با حذف کامل افزونه از پیشخوان، چهار جدول بالا و مجموعه‌ای از گزینه‌های wppc_* (طبق لیست داخل همان فایل) را حذف می‌کند؛ دادهٔ مکالمات از بین می‌رود — قبل از حذف حتماً پشتیبان بگیرید.

چت تمام‌صفحه در برگه

شورت‌کد چت تمام‌صفحه

همین یک خط را در محتوای برگه قرار دهید؛ رفتار برای کاربر واردشده و مهمان از تنظیمات افزونه قابل کنترل است.

Shortcode
[wppc_web_chat]

کاربر واردشده

قالب wppc-public-web-chat-display.php رندر می‌شود و رابط چت تمام‌صفحه نمایش داده می‌شود.

مهمان

خروجی از گزینهٔ محتوای جایگزین شورت‌کد با do_shortcode( wpautop( wp_kses_post( get_option('wppc_shortcode_fallback_content') ) ) ) — مناسب دکمهٔ ورود، تصویر یا شورت‌کدهای دیگر.

اگر برگه حاوی این شورت‌کد باشد، ویجت شناور نمایش داده نمی‌شود تا تداخلی پیش نیاید.