نمونه کارها⌄
نمونه‌کارها بر اساس دسته‌بندی
مشاهده همه نمونه‌کارها ←
اگر می‌خواهید برای پیام‌رسان بله یک بازو بسازید، مسیر کلی کار این است: ابتدا بازو را از طریق BotFather بله ایجاد می‌کنید، توکن اختصاصی می‌گیرید، اتصال به API را تست می‌کنید و در نهایت یکی از دو روش getUpdates یا Webhook را برای دریافت پیام‌ها و رویدادهای بازو انتخاب می‌کنید.
در این آموزش تمرکز اصلی روی ساخت بازو در بله و راه‌اندازی اولیه آن است. اگر هدف شما توسعه یک ربات اختصاصی متصل به سایت، ووکامرس، CRM، سیستم حسابداری یا سرویس‌های داخلی شرکت است، می‌توانید صفحه ساخت ربات و بازوی اختصاصی بله را ببینید.
بازو در بله یک حساب نرم‌افزاری است که می‌تواند از طریق API با کاربران، گروه‌ها یا سرویس‌های دیگر ارتباط برقرار کند. برخلاف یک حساب کاربری عادی، منطق بازو معمولاً در برنامه‌ای روی سرور شما اجرا می‌شود.
به زبان ساده، بله پیام یا رویداد را در اختیار برنامه شما قرار می‌دهد، برنامه آن را پردازش می‌کند و در صورت نیاز از طریق API پاسخ مناسب را ارسال می‌کند.
یک بازوی ساده ممکن است فقط به پیام کاربران پاسخ دهد؛ اما در پروژه‌های حرفه‌ای‌تر می‌تواند به ووکامرس، سامانه فروش، CRM، حسابداری، پایگاه داده یا APIهای خارجی متصل شود.
برای ساخت بازو ابتدا وارد پیام‌رسان بله شوید و بازوی مدیریت ربات‌ها یا BotFather را باز کنید. از طریق این بازو می‌توانید یک بازوی جدید ایجاد کنید و اطلاعات اولیه آن را مشخص کنید.
در این مرحله نام بازو را متناسب با کاربرد آن انتخاب کنید. برای مثال اگر قرار است بازو گزارش سفارش‌های فروشگاه را ارسال کند، نامی مرتبط با فروشگاه یا سیستم گزارش‌گیری انتخاب کنید.
نام نمایشی چیزی است که کاربر مشاهده می‌کند، در حالی که Username برای شناسایی بازو استفاده می‌شود. بهتر است Username کوتاه، قابل خواندن و تا حد امکان مرتبط با برند یا کاربرد اصلی بازو باشد.
بعد از ایجاد بازو، یک Token اختصاصی دریافت می‌کنید. این Token کلید احراز هویت بازوی شما در API بله است.
هر درخواست API که از طرف بازوی شما ارسال می‌شود، معمولاً با استفاده از همین Token شناسایی می‌شود؛ بنابراین باید آن را مانند رمز عبور نگهداری کنید.
YOUR_BALE_BOT_TOKEN استفاده کنید.
پس از دریافت Token بهتر است قبل از توسعه ربات، مطمئن شوید Token معتبر است و ارتباط شما با API برقرار می‌شود.
ساختار کلی درخواست‌های Bot API بله به این صورت است:
https://tapi.bale.ai/bot<TOKEN>/METHOD_NAMEبرای نمونه می‌توانید از متد getMe برای بررسی اطلاعات بازو استفاده کنید:
https://tapi.bale.ai/botYOUR_BALE_BOT_TOKEN/getMeدر صورت معتبر بودن Token، API یک پاسخ JSON برمی‌گرداند.
یکی از ساده‌ترین روش‌ها برای شروع کار با بازوی بله، استفاده از متد getUpdates است.
در این روش برنامه شما به‌صورت دوره‌ای از API سؤال می‌کند که آیا پیام یا Update جدیدی وجود دارد یا خیر.
نمونه درخواست:
https://tapi.bale.ai/botYOUR_BALE_BOT_TOKEN/getUpdatesابتدا از یک حساب دیگر برای بازوی خود پیام بفرستید و سپس درخواست بالا را اجرا کنید. در پاسخ می‌توانید اطلاعات مربوط به پیام، فرستنده، شناسه گفتگو و update_id را مشاهده کنید.
در یک برنامه واقعی بهتر است آخرین update_id پردازش‌شده را ذخیره کنید. سپس مقدار offset را طوری تنظیم کنید که پیام‌های قدیمی دوباره پردازش نشوند.
اگر این موضوع رعایت نشود ممکن است یک پیام چند بار توسط ربات پردازش شود.
روش دوم برای دریافت رویدادهای بازو استفاده از Webhook است.
در این روش، به جای اینکه سرور شما دائماً API را بررسی کند، بله هنگام ایجاد Update جدید آن را به URL مشخص‌شده روی سرور شما ارسال می‌کند.
به‌صورت مفهومی درخواست تنظیم Webhook شبیه نمونه زیر است:
curl -X POST "https://tapi.bale.ai/botYOUR_BALE_BOT_TOKEN/setWebhook" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/bale-webhook.php"}'آدرس Webhook باید از اینترنت قابل دسترس باشد و در محیط واقعی بهتر است از HTTPS استفاده شود.
| روش | مناسب برای | مزیت اصلی |
|---|---|---|
| getUpdates | تست، توسعه و پروژه‌های ساده | راه‌اندازی ساده |
| Webhook | پروژه‌های آنلاین و عملیاتی | دریافت خودکار رویدادها |
برای یادگیری و تست اولیه معمولاً getUpdates ساده‌تر است. اما زمانی که پروژه روی سرور قرار می‌گیرد و قرار است پیام‌ها به‌صورت خودکار پردازش شوند، Webhook ساختار مناسب‌تری ایجاد می‌کند.
بعد از اینکه دریافت پیام را تست کردید، می‌توانید ارسال پیام را نیز آزمایش کنید.
برای ارسال پیام معمولاً باید chat_id کاربر یا گفتگو را داشته باشید. این مقدار را می‌توانید از خروجی getUpdates استخراج کنید.
نمونه درخواست با متد sendMessage:
curl -X POST "https://tapi.bale.ai/botYOUR_BALE_BOT_TOKEN/sendMessage" \
-H "Content-Type: application/json" \
-d '{"chat_id":123456789,"text":"سلام؛ این اولین پیام آزمایشی بازوی بله است."}'
در این مقاله عمداً وارد تمام جزئیات API مثل Inline Keyboard، Callback Query، مدیریت فایل‌ها و معماری PHP نمی‌شویم؛ چون این موارد در مقاله مستقل API بله برای توسعه‌دهندگان PHP بهتر قابل بررسی هستند.
اگر بازوی شما قرار است علاوه بر پیام‌رسانی، کاربر را وارد یک فرایند پرداخت کند، ممکن است در معماری پرداخت پروژه با مفهومی به نام توکن پرداخت روبه‌رو شوید.
توکن پرداخت با Token اصلی بازو تفاوت دارد. Token بازو برای شناسایی و احراز هویت خود ربات در Bot API استفاده می‌شود، در حالی که توکن پرداخت معمولاً به یک تراکنش، سفارش یا درخواست پرداخت مشخص مربوط است.
در یک معماری رایج، روند کار می‌تواند به این صورت باشد:
| نوع Token | کاربرد |
|---|---|
| Token بازو | احراز هویت ربات هنگام استفاده از Bot API |
| Token پرداخت | شناسایی یک فرایند یا درخواست پرداخت مشخص |
اگر Token را ناقص کپی کرده باشید یا بخشی از آن تغییر کرده باشد، درخواست API با خطا مواجه می‌شود.
ابتدا مطمئن شوید یک کاربر واقعاً برای بازو پیام ارسال کرده است. همچنین اگر Webhook فعال باشد، وضعیت آن را بررسی کنید.
URL وب‌هوک باید از اینترنت قابل دسترس باشد. همچنین اسکریپت مقصد باید درخواست POST و JSON ورودی را به‌درستی پردازش کند.
در روش getUpdates معمولاً این مشکل زمانی رخ می‌دهد که offset بر اساس آخرین update_id مدیریت نشده باشد.
برای ارسال پیام باید شناسه صحیح گفتگو را از Update دریافتی استخراج کنید. استفاده از شناسه اشتباه باعث می‌شود پیام به مقصد موردنظر ارسال نشود.
اگر تنها هدف شما پاسخ دادن به چند پیام ساده باشد، یک بازوی سبک ممکن است کافی باشد.
اما در سناریوهای زیر معمولاً به توسعه Backend اختصاصی نیاز دارید:
برای این نوع پروژه‌ها می‌توانید از صفحه ساخت ربات تلگرام و بازوی بله جزئیات پروژه را ارسال کنید.
اگر هدف شما ساخت بازو برای انتقال خودکار پیام، عکس، فایل یا محتوا از تلگرام به بله است، مقاله انتقال فایل از تلگرام به بله را هم بخوانید.
در آن مقاله روش‌های انتقال دستی و خودکار محتوا و محدودیت‌های هر روش بررسی شده است.
بعد از ساخت بازو چه کنیم؟ برای اتصال بازو به سایت، راهنمای افزونه بله برای وردپرس و اتصال API را ببینید. اگر هدف شما پرداخت در ووکامرس است، نمونه عملی افزونه درگاه پرداخت بله برای ووکامرس مسیر پروژه‌ای این خوشه است.
پس از ایجاد بازو از طریق BotFather بله، Token اختصاصی بازو در اختیار شما قرار می‌گیرد. این Token برای احراز هویت درخواست‌های API استفاده می‌شود.
خیر. Token بازو برای شناسایی ربات در Bot API استفاده می‌شود، اما Token پرداخت به فرایند مالی یا درخواست پرداخت مربوط است.
Webhook یک URL روی سرور شماست که Updateهای جدید بازو می‌توانند به آن ارسال شوند.
getUpdates روشی برای دریافت Updateهای جدید بازو از طریق Polling است و برای تست و شروع توسعه گزینه ساده‌ای محسوب می‌شود.
ایجاد خود بازو از طریق BotFather امکان‌پذیر است، اما برای اجرای منطق اختصاصی، اتصال به سرویس‌ها، پردازش پیام‌ها یا ذخیره اطلاعات معمولاً به برنامه‌نویسی نیاز دارید.
Token افشاشده را دیگر امن در نظر نگیرید. دسترسی قبلی را از طریق ابزارهای مدیریت بازو تغییر دهید و Token جدید را در محیط امن ذخیره کنید.
ساخت بازو فقط هویت Bot و دسترسی API را ایجاد می‌کند. یک ربات اختصاصی علاوه بر این، شامل Backend، پایگاه داده، مدیریت خطا، منطق تجاری، اتصال به سرویس‌های دیگر و فرایندهای خودکار است.
برای ساخت بازو در بله ابتدا بازو را در BotFather ایجاد کنید، Token آن را دریافت کنید و سپس ارتباط با API را با متدهایی مانند getMe یا getUpdates بررسی کنید.
در مرحله توسعه می‌توانید بسته به معماری پروژه بین getUpdates و Webhook انتخاب کنید و سپس قابلیت‌هایی مانند ارسال پیام، اتصال به ووکامرس، پردازش اطلاعات یا پرداخت را به بازو اضافه کنید.
مهم‌ترین نکته این است که Token بازو را محرمانه نگه دارید و تمام عملیات حساس، به‌خصوص پرداخت و ارتباط با API، را در سمت سرور انجام دهید.
منبع فنی: مستندات رسمی بله
برای طراحی سایت، توسعه وردپرس یا اتصال نرم‌افزارها، شرح نیازتان را با من در میان بگذارید.
برای آشنایی با خدمات و مشاهده نمونه‌کارهای واقعی، مسیر زیر را دنبال کنید.
