افزونه وردپرس

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

این صفحه ابتدا نصب و اتصال افزونه را توضیح می‌دهد و سپس مرجع فنی هوک‌های عمومی نسخه 1.4.0 را برای شخصی‌سازی‌های پیشرفته ارائه می‌کند.

نصب افزونه

روش پیشنهادی: نصب از مخزن وردپرس

1. در پیشخوان وردپرس به «افزونه‌ها ← افزودن افزونه تازه» بروید.
2. عبارت «ایلاچت» را بدون فاصله جست‌وجو کنید.
3. افزونه «ایلاچت – چت بات پشتیبانی هوش مصنوعی» را پیدا کنید و روی «هم‌اکنون نصب نمایید» بزنید.
4. پس از پایان نصب، افزونه را فعال کنید.

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

نصب با فایل ZIP

اگر فایل ZIP افزونه را در اختیار دارید، در پیشخوان وردپرس به «افزونه‌ها ← افزودن افزونه تازه ← بارگذاری افزونه» بروید، فایل را انتخاب و نصب کنید؛ سپس افزونه را فعال کنید. فایل‌های افزونه پس از نصب باید در مسیر /wp-content/plugins/ilachat قرار گرفته باشند.

اتصال افزونه به ایلاچت

پس از فعال‌سازی، مراحل زیر را انجام دهید:

1. در پیشخوان وردپرس، وارد منوی «ایلاچت» و سپس «تنظیمات» شوید.
2. روی «اتصال ایلاچت به وب‌سایت من» کلیک کنید.
3. وارد حساب ایلاچت شوید، چت‌بات موردنظر را انتخاب کنید و اتصال را تأیید نمایید.
4. پس از نمایش پیام موفقیت، یک صفحه از سایت را در حالت ناشناس باز کنید و نمایش ویجت و امکان ارسال پیام را بررسی کنید.

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

اگر ووکامرس فعال است، از تنظیمات افزونه می‌توانید یکپارچه‌سازی ووکامرس، همگام‌سازی محصولات، پیگیری سفارش، داده‌های مجاز سفارش و یادداشت ویژه ایلاچت را پیکربندی کنید. فقط داده‌هایی را فعال کنید که واقعاً برای پاسخ‌گویی به مشتری لازم‌اند.

پیش از شخصی‌سازی با کد

افزونه در نقاط مشخصی از اجرای خود «هوک» در اختیار توسعه‌دهنده قرار می‌دهد. فیلتر مقداری را دریافت می‌کند و باید مقدار نهایی را برگرداند؛ اکشن وقوع یک رویداد را اعلام می‌کند و مقدار بازگشتی ندارد. اگر با این مفاهیم آشنا نیستید، ابتدا مستندات رسمی وردپرس درباره Hooks، Actions و Filters را بخوانید.

کدهای شخصی‌سازی را در یکی از این محل‌ها قرار دهید:

• یک افزونه اختصاصی کوچک برای سایت؛
• یک افزونه اجباری یا mu-plugin؛
• فایل functions.php قالب فرزند، اگر تغییر فقط به همان قالب وابسته است.

فایل‌های خود افزونه ایلاچت را ویرایش نکنید، چون تغییرات شما با به‌روزرسانی بعدی از بین می‌رود. الگوی پایه یک افزونه اختصاصی به این شکل است:

<?php
/**
 * Plugin Name: My Ilachat Customizations
 */

add_filter( 'hook_name', 'my_ilachat_callback', 10, 2 );
function my_ilachat_callback( $value, $context ) {
	return $value;
}

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

انتخاب هوک مناسب

همیشه محدودترین هوکی را انتخاب کنید که نیازتان را برطرف می‌کند. برای مثال، اگر فقط قیمت باید تغییر کند، ilachat_woocommerce_sync_product_variation_price امن‌تر از بازسازی کامل داده محصول با ilachat_woocommerce_sync_product_data است.

فیلترهای عمومی و ویجت

این فیلترها نمایش ویجت، حالت بارگذاری کد ذخیره‌شده و اطلاعات کاربر واردشده را کنترل می‌کنند. فیلترهای لید فقط زمانی اجرا می‌شوند که جمع‌آوری لید فعال و کاربر وارد سایت شده باشد؛ برای قانونی که کاربران مهمان را هم شامل می‌شود از ilachat_show_widget استفاده کنید.

// مخفی‌کردن ویجت در یک قالب برگه مشخص.
add_filter( 'ilachat_show_widget', function( $enabled ) {
	return is_page_template( 'templates/no-chat.php' ) ? false : $enabled;
} );

// افزودن شناسه CRM به داده لید سمت مرورگر.
add_filter( 'ilachat_lead_data', function( $data, $user_id ) {
	$data['crm_contact_id'] = (string) get_user_meta( $user_id, 'crm_contact_id', true );
	return $data;
}, 10, 2 );

توجه کنید داده لید در جاوااسکریپت مرورگر بازدیدکننده قرار می‌گیرد؛ بنابراین فقط اطلاعاتی را اضافه کنید که همان کاربر مجاز به دیدن آن است.

فیلترهای همگام‌سازی محتوای وردپرس

با این فیلترها می‌توانید نوع نوشته و طبقه‌بندی‌های قابل استفاده را تعیین کنید، یک نوشته را از همگام‌سازی کنار بگذارید یا متن ارسالی را با متادیتا و اطلاعات اختصاصی غنی کنید. در ilachat_sync_post_markdown محتوا قبلاً به Markdown تبدیل شده است؛ HTML اضافه‌شده در این مرحله به‌صورت متن خام ارسال می‌شود.

// حذف یک نوع نوشته سفارشی از رابط و فرایندهای همگام‌سازی.
add_filter( 'ilachat_post_types', function( $types ) {
	return array_values( array_diff( $types, array( 'portfolio' ) ) );
} );

// همگام‌نکردن نوشته‌هایی که متای مشخصی دارند.
add_filter( 'ilachat_should_sync_post', function( $should_sync, $post ) {
	return $should_sync && ! get_post_meta( $post->ID, '_exclude_from_ilachat', true );
}, 10, 2 );

// افزودن شناسه محتوا به Markdown ارسالی.
add_filter( 'ilachat_sync_post_markdown', function( $markdown, $post ) {
	return $markdown . "\n\n---\nContent ID: " . (int) $post->ID;
}, 10, 2 );

فیلترهای همگام‌سازی محصول ووکامرس

این فیلترها فقط در جریان همگام‌سازی محصول اجرا می‌شوند. محصول باید به ایلاچت متصل و منتشرشده باشد و از ilachat_should_sync_product عبور کند. محصولات ناموجود نیز فقط در صورت فعال‌بودن تنظیم مربوطه همگام می‌شوند. ورودی محصول یا متغیر از نوع WC_Product است.

// افزایش اولویت محصولات ویژه.
add_filter( 'ilachat_woocommerce_sync_product_priority', function( $priority, $product ) {
	return $product->is_featured() ? 100000 + (int) $priority : $priority;
}, 10, 2 );

// افزودن برند به داده نهایی محصول.
add_filter( 'ilachat_woocommerce_sync_product_data', function( $body, $product ) {
	$body['brand'] = sanitize_text_field( (string) $product->get_meta( 'brand' ) );
	return $body;
}, 10, 2 );

در فیلتر داده نهایی، آرایه دریافت‌شده را تغییر دهید و از بازسازی کامل آن خودداری کنید. اگر variations حذف یا خالی شود، محصول ارسال نخواهد شد. فیلترهای پرس‌وجوی گروهی فقط دسته‌های مدیریت را تغییر می‌دهند و روی هر همگام‌سازی خودکار تکی اعمال نمی‌شوند.

فیلترهای پیگیری سفارش ووکامرس

این فیلترها هنگام ساخت پاسخ نقطه پایانی احراز هویت‌شده سفارش اجرا می‌شوند. ورودی سفارش از نوع WC_Order است و مقدارهای خالی پس از اجرای ilachat_woocommerce_order_data به‌صورت بازگشتی حذف می‌شوند.

نکته مهم درباره ilachat_woocommerce_order_note_data

این نام در دو عملیات متفاوت اجرا می‌شود؛ بنابراین تابع شما باید شکل ورودی را تشخیص دهد:

// حذف ایمیل صورتحساب و افزودن شناسه عمومی فروشگاه.
add_filter( 'ilachat_woocommerce_order_data', function( $data, $order ) {
	if ( isset( $data['billing'] ) ) {
		unset( $data['billing']['email'] );
	}
	$data['store_order_reference'] = 'WEB-' . $order->get_order_number();
	return $data;
}, 10, 2 );

فقط داده‌ای را در پاسخ سفارش قرار دهید که دیدن آن برای همان مشتری امن است. توکن پرداخت، یادداشت داخلی، اطلاعات محرمانه انبار یا داده شخصی غیرضروری نباید به پاسخ افزوده شود.

نمونه‌های کاربردی شخصی‌سازی

هر نمونه را فقط یک بار و در افزونه اختصاصی، mu-plugin یا functions.php قالب فرزند قرار دهید. نامک‌ها و کلیدهای متا را با مقدار واقعی سایت خود جایگزین کنید.

نمایش ویجت فقط در چند برگه

add_filter( 'ilachat_show_widget', function( $enabled ) {
	return $enabled && is_page( array( 'contact', 'support' ) );
} );

وجود $enabled && باعث می‌شود تنظیم اصلی «نمایش ویجت» افزونه همچنان محترم بماند.

مخفی‌کردن ویجت از کاربران مهمان

add_filter( 'ilachat_show_widget', function( $enabled ) {
	return $enabled && is_user_logged_in();
} );

خواندن شماره همراه از متای اختصاصی کاربر

add_filter( 'ilachat_lead_mobile', function( $mobile, $user_id ) {
	$custom_mobile = get_user_meta( $user_id, 'customer_mobile', true );
	return '' !== $custom_mobile ? (string) $custom_mobile : $mobile;
}, 10, 2 );

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

همگام‌نکردن نوشته‌های یک دسته

add_filter( 'ilachat_should_sync_post', function( $should_sync, $post ) {
	return $should_sync && ! has_category( 'members-only', $post );
}, 10, 2 );

این کد فقط ارسال محتوا به ایلاچت را متوقف می‌کند و وضعیت انتشار نوشته در وردپرس را تغییر نمی‌دهد.

افزودن post meta به محتوای ارسالی

add_filter( 'ilachat_sync_post_markdown', function( $markdown, $post ) {
	$extra_context = get_post_meta( $post->ID, 'ilachat_extra_context', true );
	if ( '' === trim( (string) $extra_context ) ) {
		return $markdown;
	}

	return $markdown . "\n\n---\n" . wp_strip_all_tags( (string) $extra_context );
}, 10, 2 );

همگام‌نکردن محصولات یک دسته

add_filter( 'ilachat_should_sync_product', function( $should_sync, $product ) {
	return $should_sync && ! has_term( 'wholesale-only', 'product_cat', $product->get_id() );
}, 10, 2 );

افزودن توضیح ارسال اختصاصی به محصول

add_filter( 'ilachat_woocommerce_sync_product_description', function( $description, $product ) {
	$delivery_note = get_post_meta( $product->get_id(), 'product_delivery_note', true );
	if ( '' === trim( (string) $delivery_note ) ) {
		return $description;
	}

	return '<p><strong>Delivery:</strong> ' . esc_html( $delivery_note ) . '</p>' . $description;
}, 10, 2 );

این فیلتر پیش از تبدیل HTML به Markdown اجرا می‌شود؛ بنابراین HTML امن اضافه‌شده نیز به Markdown تبدیل خواهد شد.

جایگزینی قیمت با متن

add_filter( 'ilachat_woocommerce_sync_product_variation_price', function( $price, $product ) {
	return __( 'See price on the website', 'my-text-domain' );
}, 10, 2 );

این تغییر برای محصولات ساده و متغیر اعمال می‌شود.

افزودن اطلاعات امن به پیگیری سفارش

add_filter( 'ilachat_woocommerce_order_data', function( $data, $order ) {
	$instruction = $order->get_meta( 'delivery_instruction', true );
	if ( '' !== trim( (string) $instruction ) ) {
		$data['delivery_instruction'] = sanitize_text_field( (string) $instruction );
	}

	$data['tracking_help'] = __( 'For delivery support, contact us through the website.', 'my-text-domain' );
	return $data;
}, 10, 2 );

سازگاری، امنیت و عیب‌یابی

• ilachat_sync_post_plain_text فقط برای سازگاری با نسخه‌های قدیمی نگه داشته شده است؛ در کد جدید از ilachat_sync_post_markdown استفاده کنید.
• هوک‌ها سطح دسترسی وردپرس یا ووکامرس را دور نمی‌زنند. فیلتر ilachat_woocommerce_check_permissions فقط پس از اعتبارسنجی کلید مخفی درخواست اجرا می‌شود.
• حذف کلیدهای ضروری از آرایه پرس‌وجو یا داده نهایی می‌تواند همگام‌سازی را متوقف کند؛ آرایه دریافت‌شده را به‌اندازه نیاز تغییر دهید.
• پس از افزودن هر شخصی‌سازی، اتصال، نمایش ویجت، همگام‌سازی یک نوشته یا محصول آزمایشی و پاسخ پیگیری سفارش را دوباره بررسی کنید.
• اگر ویجت نمایش داده نمی‌شود، ابتدا فعال‌بودن افزونه، وضعیت اتصال، گزینه نمایش ویجت، کش سایت/CDN و خروجی ilachat_show_widget را بررسی کنید.
• اگر داده‌ای همگام نمی‌شود، منتشرشده‌بودن محتوا یا محصول، تنظیمات انتخاب محتوا، موجودی محصول و فیلترهای ilachat_should_sync_post یا ilachat_should_sync_product را بررسی کنید.

برای آموزش کار با اکشن و فیلتر خارج از محدوده ایلاچت، مرجع رسمی توسعه افزونه‌های وردپرس بهترین نقطه شروع است.