بات‌های خودتان را برای یوز بسازید

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

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

۱. شروع سریع

در برنامه یوز گفتگو با @botfather («مدیریت بات‌ها») را باز کنید و دستور /newbot را بفرستید.
نام و نام کاربری بات را بدهید (نام کاربری باید به bot ختم شود).
توکن بات را بگیرید؛ چیزی شبیه 123456:AbCdEf…. توکن را محرمانه نگه دارید.
یکی از کتابخانه‌ها را دانلود کنید و نمونه را اجرا کنید:

curl -O https://developer.yooz-app.ir/sdk/yooz_bot.py
curl -O https://developer.yooz-app.ir/examples/echo_bot.py
YOOZ_BOT_TOKEN='123456:AbCdEf...' python3 echo_bot.py

۲. Bot API

هر درخواست یک فراخوانی HTTPS است:

https://yooz-app.ir/bot<TOKEN>/<METHOD>

پارامترها را به صورت query string، application/json، x-www-form-urlencoded یا multipart/form-data (برای فایل) بفرستید.
پاسخ همیشه JSON است: {"ok": true, "result": …} یا {"ok": false, "error_code": 400, "description": "…"}.
نام متدها به بزرگی و کوچکی حروف حساس نیست.
دانلود فایل: بعد از getFile از https://yooz-app.ir/file/bot<TOKEN>/<file_path>.

curl https://yooz-app.ir/bot123456:AbCdEf/getMe

curl -X POST https://yooz-app.ir/bot123456:AbCdEf/sendMessage \
  -H 'Content-Type: application/json' \
  -d '{"chat_id": 42, "text": "سلام <b>دنیا</b>", "parse_mode": "HTML"}'

دریافت پیام‌ها

Long polling: getUpdates با offset و timeout (تا ۵۰ ثانیه). Webhook: با setWebhook یک آدرس HTTPS عمومی بدهید؛ اگر secret_token بدهید، در سرآیند X-Telegram-Bot-Api-Secret-Token برمی‌گردد. هر دو روش هم‌زمان کار نمی‌کنند.

نوع به‌روزرسانی‌ها: message، edited_message، channel_post، edited_channel_post و callback_query.

قالب‌بندی متن

parse_mode می‌تواند HTML، Markdown یا MarkdownV2 باشد، یا entities را مستقیم بفرستید. تگ‌های HTML: <b> <i> <u> <s> <code> <pre> <a href> <tg-spoiler> <blockquote>.

دکمه‌های شیشه‌ای

"reply_markup": {"inline_keyboard": [[
  {"text": "👍", "callback_data": "like"},
  {"text": "سایت یوز", "url": "https://yooz-app.ir"}
]]}

بعد از زدن دکمه، callback_query می‌رسد؛ با answerCallbackQuery جواب بدهید (حداکثر ۶۴ بایت داده برای هر دکمه، حداکثر ۱۰۰ دکمه).

۳. متدها

دسته	متدها
بات	getMe · logOut · close · setMyCommands · getMyCommands · deleteMyCommands · setMyName · getMyName · setMyDescription · getMyDescription · setMyShortDescription · getMyShortDescription
به‌روزرسانی‌ها	getUpdates · setWebhook · deleteWebhook · getWebhookInfo
ارسال	sendMessage · sendPhoto · sendVideo · sendAnimation · sendVoice · sendAudio · sendDocument · sendChatAction
ویرایش و حذف	editMessageText · editMessageCaption · editMessageReplyMarkup · deleteMessage · deleteMessages
دکمه‌ها	answerCallbackQuery
گفتگوها	getChat · getChatMemberCount · getChatMember · leaveChat
فایل‌ها	getFile

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

۴. کتابخانه‌های رسمی

Python

پایتون ۳.۸ به بالا، فقط کتابخانهٔ استاندارد، یک فایل. پشتیبانی از polling و webhook.

yooz_bot.py

from yooz_bot import Bot

bot = Bot("123456:AbCdEf...")

@bot.command("start")
def start(msg):
    msg.reply(f"سلام {msg.sender_name}!")

bot.run_polling()

Node.js

Node 18 به بالا، بدون وابستگی، یک فایل ES module.

yooz_bot.mjs

import { Bot } from './yooz_bot.mjs';

const bot = new Bot(process.env.YOOZ_BOT_TOKEN);
bot.command('start', (msg) => msg.reply('سلام!'));
await bot.startPolling();

آدرس سرور پیش‌فرض https://yooz-app.ir است؛ با متغیر محیطی YOOZ_API عوضش کنید (مثلاً https://193.93.169.100 اگر دامنه در شبکهٔ شما باز نمی‌شود).

۵. نمونه‌ها

echo_bot.py — بات تکرارکننده با دکمهٔ لایک (پایتون)
echo_bot.mjs — همان بات با Node.js