افزونه بله برای وردپرس؛ اتصال API و توسعه امکانات اختصاصی

افزونه بله برای وردپرس زمانی کاربردی است که بخواهید بین سایت وردپرسی یا فروشگاه ووکامرسی و پیام‌رسان بله یک ارتباط خودکار ایجاد کنید؛ از ارسال اعلان انتشار مطلب و وضعیت سفارش گرفته تا ساخت پنل تنظیمات، اتصال به API، Webhook و سناریوهای پرداخت.

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

افزونه بله برای وردپرس چه کاربردهایی دارد؟

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

• ارسال خودکار اعلان انتشار نوشته یا محصول جدید
• ارسال وضعیت سفارش‌های ووکامرس برای مدیر یا مشتری
• ارسال هشدار ثبت فرم، تیکت یا درخواست جدید
• اتصال فرایندهای داخلی سایت به یک بازوی بله
• ساخت پنل تنظیمات برای Token، Chat ID و گزینه‌های ارسال
• اتصال فروشگاه ووکامرس به فرایندهای پرداخت یا اعلان مالی بله

اگر هدف شما صرفاً ساخت خود بازو و دریافت Token است، مقاله آموزش ساخت بازو در بله و دریافت توکن نقطه شروع مناسب‌تری است.

اتصال وردپرس به API بله چگونه انجام می‌شود؟

برای اتصال وردپرس به بله ابتدا یک بازو ایجاد می‌کنید و Token آن را دریافت می‌کنید. سپس درخواست‌های Bot API از سمت سرور وردپرس به آدرس پایه زیر ارسال می‌شوند:

https://tapi.bale.ai/bot<TOKEN>/METHOD_NAME

در وردپرس بهتر است به‌جای cURL خام از HTTP API خود وردپرس مثل wp_remote_post() استفاده شود؛ چون مدیریت خطا، SSL و سازگاری با محیط وردپرس ساده‌تر می‌شود.

function hfa_send_bale_message( $token, $chat_id, $text ) {
    $url = 'https://tapi.bale.ai/bot' . $token . '/sendMessage';

    $response = wp_remote_post(
        $url,
        array(
            'timeout' => 15,
            'headers' => array(
                'Content-Type' => 'application/json',
            ),
            'body' => wp_json_encode(
                array(
                    'chat_id' => $chat_id,
                    'text'    => $text,
                )
            ),
        )
    );

    if ( is_wp_error( $response ) ) {
        return $response;
    }

    return json_decode( wp_remote_retrieve_body( $response ), true );
}

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

ساخت صفحه تنظیمات برای Token و Chat ID

Hard-code کردن Token داخل فایل افزونه برای پروژه واقعی مناسب نیست. بهتر است با Settings API وردپرس یک صفحه تنظیمات بسازید و داده‌ها را با دسترسی مدیریتی مناسب ذخیره کنید. ورودی‌ها باید sanitize شوند و فقط کاربر دارای مجوز لازم امکان تغییر آن‌ها را داشته باشد.

ارسال اعلان سفارش و پیام

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

add_action( 'woocommerce_order_status_changed', 'hfa_bale_order_notice', 10, 4 );

function hfa_bale_order_notice( $order_id, $old_status, $new_status, $order ) {
    $token   = get_option( 'hfa_bale_token' );
    $chat_id = get_option( 'hfa_bale_chat_id' );

    $message = sprintf(
        'وضعیت سفارش #%d از %s به %s تغییر کرد.',
        $order_id,
        $old_status,
        $new_status
    );

    hfa_send_bale_message( $token, $chat_id, $message );
}

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

درگاه پرداخت بله و ووکامرس

پرداخت با بله یک سناریوی متفاوت از ارسال پیام ساده است. Token ربات برای احراز هویت Bot API استفاده می‌شود، اما فرایند پرداخت ممکن است شناسه‌ها و مراحل جداگانه‌ای داشته باشد و باید مطابق مستندات سرویس پرداخت مورد استفاده پیاده‌سازی شود.

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

چه زمانی افزونه اختصاصی لازم است؟

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

• ارسال پیام متفاوت بر اساس وضعیت سفارش یا نوع محصول
• ارسال گزارش فروش یا اعلان مدیریتی دوره‌ای
• ذخیره ارتباط بین کاربر وردپرس و شناسه کاربر بله
• ساخت Webhook و پردازش پیام‌های ورودی
• اتصال بله به ووکامرس، CRM یا سیستم حسابداری
• مدیریت پرداخت، Callback و وضعیت تراکنش
• تعریف سطح دسترسی و پنل تنظیمات برای مدیر سایت

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

امنیت Token و Webhook

Token بازو عملاً کلید دسترسی به ربات است و نباید در JavaScript، GitHub عمومی، اسکرین‌شات یا HTML صفحه قرار بگیرد. درخواست‌های API باید از سمت سرور اجرا شوند و دسترسی به تنظیمات افزونه فقط برای کاربران مجاز فراهم باشد.

• Token را در کد عمومی یا مخزن Git قرار ندهید.
• ورودی‌های تنظیمات را sanitize و خروجی‌ها را escape کنید.
• برای عملیات مدیریتی از Capability Check و Nonce استفاده کنید.
• Webhook باید روی HTTPS قرار داشته باشد و ورودی آن قبل از پردازش اعتبارسنجی شود.
• برای خطاهای API و Timeout سیستم Log و Retry محدود در نظر بگیرید.
• اگر Token افشا شد، آن را امن در نظر نگیرید و دسترسی قبلی را جایگزین کنید.

سوالات متداول

آیا افزونه آماده برای اتصال وردپرس به بله وجود دارد؟

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

آیا می‌توان سفارشات ووکامرس را در بله ارسال کرد؟

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

امکان ساخت درگاه پرداخت بله برای ووکامرس وجود دارد؟

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

آیا Token بله را می‌توان داخل کد افزونه قرار داد؟

برای نمونه آزمایشی ممکن است، اما در پروژه واقعی بهتر است Token از تنظیمات امن سمت سرور دریافت شود و در کد عمومی یا Frontend قرار نگیرد.

Webhook چه زمانی لازم می‌شود؟

وقتی بازو باید پیام یا رویداد ورودی را به‌صورت خودکار دریافت و پردازش کند، Webhook انتخاب مناسب‌تری از Polling مداوم است.

جمع‌بندی

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

اگر در مرحله تحقیق هستید، ابتدا بازو و API را آزمایش کنید؛ اگر پروژه وارد منطق واقعی کسب‌وکار، ووکامرس یا پرداخت می‌شود، ساختار اختصاصی و قابل نگهداری اهمیت بیشتری پیدا می‌کند.