کاربردهای عملی

اعلان‌های محصول

برای پیام‌هایی مثل تایید سفارش، هشدار وضعیت، یادآوری پرداخت یا اطلاع‌رسانی داخلی، از sendMessage استفاده کنید. در کد backend، کلید API را در secret manager نگه دارید و مقصد را با chat_id ذخیره‌شده بفرستید.

curl -X POST "https://api.uniom.ir/bot<API_KEY>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"@username","text":"سفارش شما ثبت شد."}'

برای محیط production، retry محدود، timeout مشخص و لاگ درخواست‌ها را در برنامه خود داشته باشید.

صندوق پشتیبانی

برای ساخت inbox یا اتصال پیام‌ها به CRM، معمولاً webhook مناسب‌تر از polling است. update را سریع دریافت کنید، در queue یا دیتابیس خود ذخیره کنید و پاسخ 2xx بدهید.

curl -X POST "https://api.uniom.ir/bot<API_KEY>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/support/uniom","secret_token":"change-me"}'

برای پاسخ اپراتور یا سیستم، همان chat.id یا شناسه ذخیره‌شده را با sendMessage استفاده کنید.

اتوماسیون و workflow

در ابزارهایی مثل n8n، Zapier یا jobهای داخلی، یونیوم را مثل یک HTTP API ساده صدا بزنید. رایج‌ترین الگو این است که event داخلی برنامه به یک درخواست sendMessage، sendPhoto یا sendDocument تبدیل شود.

curl -X POST "https://api.uniom.ir/bot<API_KEY>/sendDocument" \
  -F "chat_id=@username" \
  -F "document=@./invoice.pdf"

اگر ابزار شما Telegram Bot API را پشتیبانی می‌کند و اجازه تغییر base URL می‌دهد، معمولاً می‌توانید token را برابر کلید API یونیوم بگذارید.

مهاجرت از Bot API تلگرام

اگر قبلاً با Telegram Bot API کار کرده‌اید، مسیر پایه را به یونیوم تغییر دهید و token را با کلید API جایگزین کنید:

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

در سناریوهای رایج این مهاجرت عملاً 1:1 compatible است، اما قابلیت نهایی هر متد به پلتفرم مقصد و حساب متصل‌شده وابسته است. برای مسیرهای حساس مثل فایل، مدیریت گروه یا ویرایش پیام، ابتدا روی همان پلتفرم هدف تست بگیرید. راهنمای قدم‌به‌قدم و نمونه‌های python-telegram-bot و n8n در مهاجرت از تلگرام به یونیوم آمده است.

مانیتورینگ ساده

برای health check برنامه، ابتدا getMe را با همان کلید بزنید. برای دریافت وضعیت webhook از getWebhookInfo و برای بررسی مصرف یا خطا از APIهای مدیریتی استفاده کنید.

curl "https://api.uniom.ir/bot<API_KEY>/getMe"

curl "https://api.uniom.ir/user/usage" \
  -H "Authorization: Bearer <JWT>"