مهاجرت از تلگرام به یونیوم

اصل مهاجرت

اگر کد، bot یا workflow شما بر اساس Telegram Bot API نوشته شده و امکان تغییر base URL را دارد، در بیشتر سناریوهای رایج برای مهاجرت به یونیوم لازم نیست منطق اصلی را بازنویسی کنید. APIهای یونیوم عمداً منطبق بر APIهای تلگرام طراحی شده‌اند و برای الگوهای متداول عملاً 1:1 compatible هستند:

• همان نام متدها مثل sendMessage، getUpdates و setWebhook
• همان wrapper پاسخ با ok و result
• همان الگوی polling و webhook
• همان SDKها و automationهایی که فقط به token و base URL وابسته‌اند

آنچه عوض می‌شود، خود token و endpoint است.

آنچه دقیقاً عوض می‌شود

در یونیوم، همان API key نقش bot token را در کتابخانه یا workflow شما بازی می‌کند.

مراحل مهاجرت

1. در پنل یونیوم وارد شوید.
2. حساب پیام‌رسان مقصد را از بخش حساب‌ها متصل کنید.
3. از بخش کلیدهای API یک API key بسازید.
4. در کد یا workflow فعلی، token را با API key یونیوم جایگزین کنید.
5. base URL را به https://api.uniom.ir/bot تغییر دهید.
6. اگر فایل دانلود می‌کنید، base file URL را به https://api.uniom.ir/file/bot تغییر دهید.
7. با getMe یا sendMessage اولین تست را بگیرید.

تفاوت با الگوی مستقیم بله

اگر قبلاً مستندات بله را دیده باشید، الگوی آن شبیه این است که bot token را از @BotFather بگیرید و endpoint را به https://tapi.bale.ai تغییر دهید تا از همان کتابخانه‌های تلگرامی استفاده کنید.

در یونیوم، همان ایده را یک لایه بالاتر می‌برید:

• به‌جای token مستقیم یک پلتفرم، از API key یونیوم استفاده می‌کنید.
• به‌جای endpoint اختصاصی یک پلتفرم، از https://api.uniom.ir/bot استفاده می‌کنید.
• همان منطق برنامه را برای چند پیام‌رسان نگه می‌دارید، نه فقط یک مقصد.

مثل همان هشدار رایج در مهاجرت‌های منطبق بر تلگرام، پشتیبانی نهایی هر متد به credential و پلتفرم مقصد بستگی دارد. قبل از rollout روی متدهای حساس مثل فایل، ویرایش پیام، مدیریت گروه یا webhook، روی همان پلتفرم واقعی تست بگیرید.

ساخت API key یونیوم

بعد از اتصال credential، یک API key بسازید و آن را مثل secret نگه دارید. این مقدار در کد شما دقیقاً جای token فعلی می‌نشیند:

https://api.uniom.ir/bot<API_KEY>/METHOD_NAME

اگر workflow داخلی، cron job یا integration مدیریتی هم دارید، می‌توانید برای مسیرهای غیر Bot API از PAT یا JWT استفاده کنید؛ اما برای متدهای /bot... همان API key کافی است.

نمونه با python-telegram-bot

نمونه زیر یک ربات ساده python-telegram-bot را بدون تغییر در منطق handlerها روی یونیوم اجرا می‌کند:

from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes, MessageHandler, filters

API_KEY = "<UNIOM_API_KEY>"

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    if update.message:
        await update.message.reply_text("سلام، این ربات از طریق یونیوم اجرا می‌شود.")

async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    if update.message and update.message.text:
        await update.message.reply_text(f"دریافت شد: {update.message.text}")

application = (
    ApplicationBuilder()
    .token(API_KEY)
    .base_url("https://api.uniom.ir/bot")
    .base_file_url("https://api.uniom.ir/file/bot")
    .build()
)

application.add_handler(CommandHandler("start", start))
application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
application.run_polling()

اگر قبلاً همین پروژه را برای تلگرام داشته‌اید، handlerها، CommandHandler و MessageHandler همان می‌مانند. فقط token و base URL عوض می‌شوند.

مهاجرت با n8n

برای workflowهای n8n دو مسیر رایج دارید:

1. اگر node شما endpoint سفارشی می‌پذیرد، token را با API key یونیوم و base URL را با https://api.uniom.ir/bot جایگزین کنید.
2. اگر node این امکان را نمی‌دهد، از HTTP Request استفاده کنید و همان payload قبلی را مستقیم به یونیوم بفرستید.

نمونه تنظیم برای sendMessage:

اگر workflow شما قبلاً برای تلگرام آماده است و payload را خودش می‌سازد، معمولاً فقط همین سه چیز عوض می‌شوند: token، base URL و در صورت نیاز مسیر فایل.

webhook و polling بدون بازنویسی

اگر در تلگرام از webhook استفاده می‌کردید:

https://api.telegram.org/bot<TOKEN>/setWebhook

در یونیوم همان منطق را با این endpoint ادامه می‌دهید:

https://api.uniom.ir/bot<API_KEY>/setWebhook

برای polling هم همین قاعده برقرار است:

https://api.uniom.ir/bot<API_KEY>/getUpdates

offset، limit، timeout و allowed_updates همان رفتار قبلی را نگه می‌دارند.

چک‌لیست قبل از production

• getMe و sendMessage را با API key نهایی تست کنید.
• اگر فایل دارید، getFile و مسیر /file/bot<API_KEY>/... را هم تست کنید.
• اگر از webhook استفاده می‌کنید، getWebhookInfo را بعد از ثبت webhook ببینید.
• chat_idهای production را از updateهای واقعی ذخیره کنید و فقط به resolve با username یا شماره وابسته نمانید.
• برای متدهای پلتفرم‌محور، قبل از rollout روی همان credential مقصد تست بگیرید.

مسیرهای مرتبط

• شروع سریع
• نمونه‌های آماده
• مفاهیم اصلی
• وب‌هوک‌ها
• مرجع متدها