آموزش جامع طراحی افزونه وردپرس برای پیام‌ رسان بله + (اتصال API و بازو)

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

چرا اتصال وردپرس به بله اهمیت دارد؟

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

گام اول: آشنایی با مفاهیم و API پیام رسان بله برای توسعه‌دهندگان

قبل از شروع کدنویسی، باید بدانید که بله از ساختاری مشابه تلگرام برای ربات‌های خود استفاده می‌کند که به آن‌ها «بازو» (Bazoo) گفته می‌شود. استفاده از API پیام رسان بله برای توسعه‌دهندگان بسیار ساده است. تمام درخواست‌ها به پروتکل HTTPS ارسال می‌شوند و فرمت پاسخ‌ها به صورت JSON است.

برای شروع ساخت ربات بله، باید ابتدا به بازوی @BotFather در اپلیکیشن بله مراجعه کرده و یک توکن اختصاصی (API Token) دریافت کنید. این توکن هویت افزونه شما در شبکه بله خواهد بود و تمام خدمات پلاگین نویسی اختصاصی وردپرس شما حول محور این کد می‌چرخد.

ساختار درخواستی API بله

آدرس پایه برای ارسال درخواست‌ها به صورت زیر است:

https://tapi.bale.ai/bot{token}/{method}

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

گام دوم: شروع آموزش پلاگین نویسی اختصاصی وردپرس

برای شروع، یک پوشه جدید در مسیر wp-content/plugins با نام wp-bale-connector ایجاد کنید. داخل این پوشه، فایلی به نام wp-bale-connector.php بسازید. این فایل قلب افزونه ما در فرآیند آموزش ساخت افزونه وردپرس برای پیام‌رسان بله است.

</wp-p>

<pre dir="ltr"><code><?php
/**
 * Plugin Name: اتصال اختصاصی وردپرس به بله
 * Description: افزونه‌ای برای ارسال خودکار مطالب به پیام‌رسان بله.
 * Version: 1.0.0
 * Author: حامد فرح آبادی
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit; // جلوگیری از دسترسی مستقیم
}

// تعریف ثابت‌های افزونه
define( 'BALE_API_URL', 'https://tapi.bale.ai/bot' );

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

گام سوم: ساخت بازو در بله با PHP و کلاس اختصاصی

برای اینکه کدهای تمیزی داشته باشیم، بهتر است یک کلاس PHP برای مدیریت ارتباط با API طراحی کنیم. ساخت بازو در بله با PHP نیازمند استفاده از توابع وردپرس مانند wp_remote_post است که جایگزین بهتری برای cURL خام محسوب می‌شود.

</wp-p>

<pre dir="ltr"><code>class Bale_Messenger_Handler {
    private $token;

    public function __construct($token) {
        $this->token = $token;
    }

    public function send_message($chat_id, $text) {
        $url = BALE_API_URL . $this->token . '/sendMessage';
        $args = array(
            'body' => array(
                'chat_id' => $chat_id,
                'text'    => $text,
            ),
        );

        $response = wp_remote_post($url, $args);

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

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

این متد پایه، سنگ بنای آموزش ساخت بازو در بله است. شما می‌توانید این کلاس را در بخش‌های مختلف پروژه خود استفاده کنید.

گام چهارم: هوک کردن به سیستم انتشار وردپرس

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

</wp-p>

<pre dir="ltr"><code>add_action('publish_post', 'send_post_to_bale', 10, 2);

function send_post_to_bale($ID, $post) {
    $token = 'YOUR_BALE_TOKEN'; // از تنظیمات دریافت شود
    $chat_id = 'YOUR_CHAT_ID';
    
    $message = "مطلب جدید در سایت منتشر شد:\n";
    $message .= $post->post_title . "\n";
    $message .= get_permalink($ID);

    $bale = new Bale_Messenger_Handler($token);
    $bale->send_message($chat_id, $message);
}

در طراحی افزونه وردپرس به صورت حرفه‌ای، ما نباید توکن و Chat ID را به صورت دستی (Hard-coded) وارد کنیم. در مرحله بعد، یاد می‌گیریم چگونه یک صفحه تنظیمات برای افزونه بسازیم.

گام پنجم: طراحی پنل تنظیمات و مدیریت متغیرها

برای اینکه کاربران بتوانند بدون تغییر کد، از افزونه استفاده کنند، نیاز به یک صفحه تنظیمات داریم. این بخش از آموزش ساخت افزونه وردپرس برای پیام‌رسان بله به شما یاد می‌دهد چگونه از API تنظیمات وردپرس (Settings API) استفاده کنید.

• ایجاد منو در پیشخوان وردپرس
• ثبت فیلدهای توکن بله و شناسه چت
• ذخیره امن داده‌ها در دیتابیس

</wp-p>

<pre dir="ltr"><code>add_action('admin_menu', 'bale_plugin_menu');

function bale_plugin_menu() {
    add_options_page(
        'تنظیمات اتصال بله',
        'اتصال به بله',
        'manage_options',
        'bale-settings',
        'bale_settings_page_html'
    );
}

function bale_settings_page_html() {
    ?>
    <div class="wrap">
        <h1>تنظیمات بازوی بله</h1>
        <form action="options.php" method="post">
            <?php
            settings_fields('bale_settings_group');
            do_settings_sections('bale-settings');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

نمونه کد جدید اتصال وردپرس به نسخه جدید API پیام‌رسان بله

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

<pre><code class="language-php">// تابع اختصاصی ارسال پیام به API بله
function hfa_send_bale_message($bot_token, $chat_id, $message_text) {
    $url = 'https://tapi.bale.ai/bot' . $bot_token . '/sendMessage';
    
    $body = array(
        'chat_id' =&gt; $chat_id,
        'text'    =&gt; $message_text
    );

    $args = array(
        'body'        =&gt; json_encode($body),
        'headers'     =&gt; array('Content-Type' =&gt; 'application/json'),
        'timeout'     =&gt; 15,
        'sslverify'   =&gt; true
    );

    $response = wp_remote_post($url, $args);

    if (is_wp_error($response)) {
        return array(
            'success' =&gt; false,
            'error'   =&gt; $response-&gt;get_error_message()
        );
    }

    $body_response = json_decode(wp_remote_retrieve_body($response), true);
    
    if (isset($body_response['ok']) &amp;&amp; $body_response['ok'] === true) {
        return array('success' =&gt; true);
    } else {
        return array(
            'success' =&gt; false,
            'error'   =&gt; isset($body_response['description']) ? $body_response['description'] : 'خطای نامشخص'
        );
    }
}

رفع خطاهای رایج در اتصال افزونه وردپرس به API بله

• خطای HTTP Timeout (تایم‌اوت شبکه): در صورتی که پاسخ سرور بله بیش از حد طول بکشد، مقدار timeout در wp_remote_post را روی ۱۵ تا ۳۰ ثانیه تنظیم کنید.
• خطای 401 Unauthorized (توکن نامعتبر): مطمئن شوید توکن دریافتی از BotFather بله را بدون فاصله اضافه در پیشخوان افزونه ذخیره کرده‌اید.
• خطای JSON Parsing: همواره هدر Content-Type: application/json را در آرگومان‌های درخواست قرار دهید تا دیتای خروجی به درستی پردازش شود.

بهینه‌سازی و نکات پیشرفته در توسعه افزونه

در پروژه‌های بزرگ، ممکن است بخواهید ارسال پیام‌ها را به صورت ناهمگام (Asynchronous) انجام دهید تا روی سرعت لود مدیریت سایت تاثیر نگذارد. اگر به دنبال بهبود سرعت سایت و رفع خطای webfont load هستید، بهتر است از سیستم WP_Cron برای صف‌بندی ارسال پیام‌ها استفاده کنید.

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

نتیجه‌گیری

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

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

• آیا برای استفاده از API بله نیاز به سرور خارج از کشور داریم؟ خیر، بله یک پیام‌رسان داخلی است و برخلاف تلگرام، سرورهای آن در داخل ایران در دسترس هستند و نیازی به پروکسی یا سرور خارج نیست.
• چگونه می‌توان Chat ID را در بله پیدا کرد؟ کافیست به بازوی @userinfobot در بله پیام دهید تا شناسه عددی شما را ارسال کند.
• آیا امکان ارسال تصویر و فایل هم با این افزونه وجود دارد؟ بله، شما می‌توانید به جای متد sendMessage از متدهایی مثل sendPhoto یا sendDocument در کلاس PHP خود استفاده کنید.
• آیا این روش باعث کندی پیشخوان وردپرس می‌شود؟ اگر تعداد ارسال‌ها زیاد باشد، بله. راهکار آن استفاده از کتابخانه‌های پردازش پس‌زمینه یا کرون‌جاب‌های وردپرس است تا تجربه کاربری مختل نشود.
• تفاوت بازوی بله با ربات تلگرام در چیست؟ پروتکل ارتباطی بسیار مشابه است، اما بله قابلیت‌های پرداخت بومی و ویجت‌های بانکی بیشتری را در اختیار توسعه‌دهندگان ایرانی قرار می‌دهد.