Telegram Bot API

پرداخت با Telegram Stars در ربات: فاکتور، پیش‌پرداخت، بازپرداخت و اشتراک

· 9 دقیقه مطالعه

برای دریافت پرداخت با Telegram Stars در ربات، با sendInvoice فاکتوری با ارز XTR و provider_token خالی بفرستید، به آپدیت pre_checkout_query ظرف 10 ثانیه با answerPreCheckoutQuery جواب دهید و کالا را فقط بعد از رسیدن پیام successful_payment تحویل دهید. استارز تلگرام ارز اجباری برای فروش کالاها و خدمات دیجیتال در اپ‌های تلگرام است. در این راهنما کل روند را با یک ربات کامل پایتون و جاوااسکریپت می‌بینید و بعد سراغ بازپرداخت، تاریخچه‌ی تراکنش‌ها، اشتراک و رسانه‌ی پولی می‌رویم.

پرداخت با Telegram Stars در ربات چطور کار می‌کند

Telegram Stars یک آیتم مجازی درون‌برنامه‌ای است. کاربران آن را از طریق خرید درون‌برنامه‌ای Apple یا Google یا از @PremiumBot می‌خرند و در ربات شما خرج می‌کنند؛ فرم پرداخت هیچ اطلاعات شخصی نمی‌خواهد. روند کار:

  1. ربات فاکتور می‌فرستد: sendInvoice به یک چت، یا createInvoiceLink برای ساخت لینک.
  2. کاربر دکمه‌ی Pay را می‌زند (و در صورت نیاز اول استار می‌خرد).
  3. ربات آپدیتی با pre_checkout_query دریافت می‌کند.
  4. ربات ظرف 10 ثانیه سفارش را با answerPreCheckoutQuery تأیید یا رد می‌کند.
  5. تلگرام یک پیام سرویسی با successful_payment می‌فرستد.
  6. ربات telegram_payment_charge_id را ذخیره و کالا را تحویل می‌دهد.

کالای دیجیتال باید با Stars فروخته شود. تلگرام اعلام کرده که ربات یا Mini App برای فروش کالاها و خدمات دیجیتال داخل اپ‌های تلگرام باید از Telegram Stars استفاده کند، فارغ از اینکه سایت یا درگاه پرداختی جای دیگری دارید یا نه؛ در غیر این صورت تلگرام نمی‌تواند ربات شما را به کاربران موبایل نشان دهد. ارزها و درگاه‌های دیگر فقط برای کالای فیزیکی هستند که روند جداگانه‌ای با provider token دارد.

ارسال فاکتور با sendInvoice و XTR

یک فاکتور ساده‌ی Stars به مبلغ 50 استار:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendInvoice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "title": "بسته‌ی Pro",
    "description": "50 تولید تصویر اضافه برای حساب شما",
    "payload": "pro-pack-v1",
    "provider_token": "",
    "currency": "XTR",
    "prices": [{"label": "بسته‌ی Pro", "amount": 50}]
  }'

این متد Message ارسال‌شده را برمی‌گرداند. پارامترهای مهم برای Stars:

پارامترقانون برای Telegram Stars
titleنام محصول، 1 تا 32 کاراکتر.
descriptionتوضیح محصول، 1 تا 255 کاراکتر.
payload1 تا 128 بایت، به کاربر نمایش داده نمی‌شود. شناسه‌ی سفارش یا محصول را اینجا بگذارید؛ در pre-checkout query و پرداخت برمی‌گردد.
provider_tokenاختیاری؛ برای Stars رشته‌ی خالی بفرستید.
currencyXTR.
pricesآرایه‌ای از LabeledPrice که باید دقیقاً یک آیتم داشته باشد؛ amount قیمت به استار است (عدد صحیح).
start_parameterخالی: نسخه‌های فوروارد‌شده دکمه‌ی Pay را نگه می‌دارند. غیرخالی: نسخه‌های فوروارد‌شده به جای آن یک دکمه‌ی URL با دیپ‌لینک به ربات نشان می‌دهند.
photo_urlتصویر اختیاری محصول، همراه با photo_size، photo_width و photo_height.

انعام (max_tip_amount) برای Stars پشتیبانی نمی‌شود و فیلدهایی مثل need_name، need_email، need_shipping_address و is_flexible نادیده گرفته می‌شوند. اگر reply_markup دلخواه اضافه کنید، دکمه‌ی اول باید دکمه‌ی Pay باشد ("pay": true)؛ رشته‌های ⭐ و XTR در متن آن با آیکون استار جایگزین می‌شوند. فاکتور را می‌توان به چت خصوصی، گروه و کانال فرستاد. بدون کد امتحان کنید: sendInvoice را در Bot API Tester باز کنید، فیلدهای بالا را پر کنید و برای خودتان فاکتور بفرستید.

createInvoiceLink همان title، description، payload، currency و prices را می‌گیرد، اما به جای ارسال پیام، لینک فاکتور را به صورت رشته برمی‌گرداند. آن را در Mini App با Telegram.WebApp.openInvoice(url) باز کنید یا مثل یک لینک معمولی به اشتراک بگذارید. متد ساخت اشتراک هم همین است (پایین‌تر را ببینید).

پاسخ به pre_checkout_query ظرف 10 ثانیه

وقتی کاربر Pay را می‌زند، ربات یک PreCheckoutQuery با id، from، currency، total_amount و invoice_payload می‌گیرد. باید ظرف 10 ثانیه جواب دهید، وگرنه تراکنش لغو می‌شود:

این هندلر را سریع نگه دارید: payload و موجودی را بررسی کنید، جواب دهید و بقیه‌ی کارها را بعداً انجام دهید. تأیید این کوئری به معنی رسیدن پول نیست.

تحویل کالا بعد از successful_payment

پرداخت موفق به صورت یک message می‌رسد که فیلد successful_payment آن شامل currency، total_amount، invoice_payload و telegram_payment_charge_id است. قانون تلگرام صریح است: همیشه قبل از تحویل، مطمئن شوید successful_payment را دریافت کرده‌اید. telegram_payment_charge_id را همراه با user id خریدار ذخیره کنید، چون بازپرداخت به هر دو نیاز دارد.

مثال کامل: رباتی که با Telegram Stars می‌فروشد

این ربات long polling با /buy فاکتور می‌فرستد، pre-checkout query را اعتبارسنجی می‌کند، پرداخت را ثبت می‌کند و به /paysupport جواب می‌دهد. به allowed_updates دقت کنید: اگر نوع آپدیت‌ها را محدود می‌کنید، pre_checkout_query را هم بگذارید، وگرنه پرداخت‌ها هرگز به ربات نمی‌رسند.

import json
import os
import requests

TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
PAYLOAD = "pro-pack-v1"
PRICE = 50  # به Telegram Stars


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


def handle(update):
    query = update.get("pre_checkout_query")
    if query:
        ok = (query["invoice_payload"] == PAYLOAD and query["currency"] == "XTR"
              and query["total_amount"] == PRICE)
        answer = {"pre_checkout_query_id": query["id"], "ok": ok}
        if not ok:
            answer["error_message"] = "این پیشنهاد منقضی شده. برای فاکتور جدید /buy را بفرستید."
        call("answerPreCheckoutQuery", **answer)  # ظرف 10 ثانیه
        return

    msg = update.get("message")
    if not msg:
        return
    chat_id = msg["chat"]["id"]
    if "successful_payment" in msg:
        payment = msg["successful_payment"]
        with open("payments.jsonl", "a") as f:  # charge id را برای بازپرداخت نگه دارید
            f.write(json.dumps({"user_id": msg["from"]["id"],
                                "charge_id": payment["telegram_payment_charge_id"],
                                "payload": payment["invoice_payload"],
                                "amount": payment["total_amount"]}) + "\n")
        call("sendMessage", chat_id=chat_id, text="ممنون! بسته‌ی Pro شما فعال شد.")
    elif msg.get("text") == "/buy":
        call("sendInvoice", chat_id=chat_id, title="بسته‌ی Pro",
             description="50 تولید تصویر اضافه برای حساب شما",
             payload=PAYLOAD, provider_token="", currency="XTR",
             prices=[{"label": "بسته‌ی Pro", "amount": PRICE}])
    elif msg.get("text") == "/paysupport":
        call("sendMessage", chat_id=chat_id,
             text="مشکل پرداخت دارید؟ آن را در یک پیام شرح دهید، ظرف 24 ساعت جواب می‌دهیم.")


offset = 0
while True:
    updates = call("getUpdates", offset=offset, timeout=30,
                   allowed_updates=["message", "pre_checkout_query"])
    for update in updates:
        offset = update["update_id"] + 1
        handle(update)
import { appendFile } from "node:fs/promises";

const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const PAYLOAD = "pro-pack-v1";
const PRICE = 50; // به Telegram Stars

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

async function handle(update) {
  const query = update.pre_checkout_query;
  if (query) {
    const ok = query.invoice_payload === PAYLOAD && query.currency === "XTR"
      && query.total_amount === PRICE;
    const answer = { pre_checkout_query_id: query.id, ok };
    if (!ok) answer.error_message = "این پیشنهاد منقضی شده. برای فاکتور جدید /buy را بفرستید.";
    await call("answerPreCheckoutQuery", answer); // ظرف 10 ثانیه
    return;
  }

  const msg = update.message;
  if (!msg) return;
  const chatId = msg.chat.id;
  if (msg.successful_payment) {
    const payment = msg.successful_payment;
    await appendFile("payments.jsonl", JSON.stringify({ // charge id را برای بازپرداخت نگه دارید
      user_id: msg.from.id,
      charge_id: payment.telegram_payment_charge_id,
      payload: payment.invoice_payload,
      amount: payment.total_amount,
    }) + "\n");
    await call("sendMessage", { chat_id: chatId, text: "ممنون! بسته‌ی Pro شما فعال شد." });
  } else if (msg.text === "/buy") {
    await call("sendInvoice", {
      chat_id: chatId, title: "بسته‌ی Pro",
      description: "50 تولید تصویر اضافه برای حساب شما",
      payload: PAYLOAD, provider_token: "", currency: "XTR",
      prices: [{ label: "بسته‌ی Pro", amount: PRICE }],
    });
  } else if (msg.text === "/paysupport") {
    await call("sendMessage", {
      chat_id: chatId,
      text: "مشکل پرداخت دارید؟ آن را در یک پیام شرح دهید، ظرف 24 ساعت جواب می‌دهیم.",
    });
  }
}

let offset = 0;
while (true) {
  const updates = await call("getUpdates", {
    offset, timeout: 30, allowed_updates: ["message", "pre_checkout_query"],
  });
  for (const update of updates) {
    offset = update.update_id + 1;
    await handle(update);
  }
}

نسخه‌ی جاوااسکریپت را با نام bot.mjs ذخیره کنید (Node.js 18 به بالا). در production از یک دیتابیس واقعی استفاده کنید و تحویل را بر اساس telegram_payment_charge_id ایدمپوتنت (idempotent) کنید. با وب هوک هم هندلر همین است؛ برای راه‌اندازی و allowed_updates آن آموزش وب هوک ربات تلگرام را ببینید.

بازپرداخت با refundStarPayment

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/refundStarPayment" \
  -H "Content-Type: application/json" \
  -d '{"user_id": 123456789, "telegram_payment_charge_id": "CHARGE_ID_FROM_SUCCESSFUL_PAYMENT"}'

در صورت موفقیت true برمی‌گرداند، استارها به کاربر برمی‌گردند و یک پیام سرویسی با refunded_payment در چت ظاهر می‌شود. هر چیزی را که تحویل داده‌اید لغو کنید. توجه کنید اگر خریدار از طریق Apple یا Google درخواست chargeback بدهد، استارهای برگشتی از موجودی ربات کم می‌شوند؛ به گفته‌ی تلگرام این موضوع خارج از کنترل آن است.

موجودی و تراکنش‌ها: getMyStarBalance و getStarTransactions

اشتراک با Telegram Stars

برای دریافت هزینه از کاربر هر 30 روز یک بار، subscription_period را به createInvoiceLink بدهید:

برای دسترسی پولی به کانال، متد createChatSubscriptionInviteLink با subscription_period برابر 2592000 و subscription_price بین 1 تا 10000 استار وجود دارد؛ ربات به دسترسی ادمین can_invite_users نیاز دارد.

sendPaidMedia حداکثر 10 عکس یا ویدیو را پشت یک قیمت پنهان می‌فرستد: star_count بین 1 تا 25000 و یک payload اختیاری 0 تا 128 بایتی. در کانال، درآمد به موجودی کانال می‌رود و در جاهای دیگر به موجودی ربات. اگر payload خالی نباشد و چت کانال نباشد، ربات آپدیت purchased_paid_media با خریدار و payload دریافت می‌کند؛ پس اگر آپدیت‌ها را فیلتر می‌کنید، آن را به allowed_updates اضافه کنید.

تست پرداخت Stars در محیط تست

تلگرام اجازه می‌دهد پرداخت‌های Stars را در محیط تست اختصاصی خود رایگان تست کنید: آنجا یک حساب تست و یک ربات بسازید و درخواست‌های API را به https://api.telegram.org/bot<token>/test/METHOD_NAME بفرستید. تستر ما هم برای همین کار یک سوئیچ TEST دارد. آموزش قدم‌به‌قدم در سرور تست تلگرام آمده است. برای راه‌اندازی واقعی، ربات را به محیط production ببرید.

چک‌لیست راه‌اندازی و رفع مشکلات

تازه با ربات‌ها شروع کرده‌اید؟ از آموزش ساخت ربات تلگرام شروع کنید. مرجع رسمی در مستندات پرداخت با Telegram Stars و بخش Payments در Bot API است.

پرسش‌های متداول

چطور در ربات تلگرام پرداخت با Telegram Stars بگیرم؟

با sendInvoice (یا createInvoiceLink) فاکتوری با currency برابر XTR، provider_token خالی و دقیقاً یک آیتم در prices بفرستید. به آپدیت pre_checkout_query ظرف 10 ثانیه با answerPreCheckoutQuery جواب دهید و وقتی پیام حاوی successful_payment رسید، کالا را تحویل دهید.

آیا برای Telegram Stars به provider token نیاز دارم؟

خیر. provider_token فقط برای کالاها و خدمات فیزیکی لازم است. برای پرداخت با Telegram Stars رشته‌ی خالی بفرستید یا پارامتر را حذف کنید.

آیا می‌توانم کالای دیجیتال را در ربات با دلار، کارت یا رمزارز بفروشم؟

خیر. به گفته‌ی تلگرام، کالاها و خدمات دیجیتالی که داخل اپ‌های تلگرام فروخته می‌شوند به خاطر قوانین App Store و Google Play باید فقط با Telegram Stars پرداخت شوند. ارزها و درگاه‌های دیگر فقط برای کالاها و خدمات فیزیکی مجازند.

چطور یک پرداخت Telegram Stars را بازپرداخت کنم؟

متد refundStarPayment را با user_id خریدار و telegram_payment_charge_id از پیام successful_payment صدا بزنید. این شناسه را برای هر پرداخت ذخیره کنید، وگرنه بعداً نمی‌توانید بازپرداخت کنید.

اشتراک Telegram Stars در ربات‌ها چطور کار می‌کند؟

با createInvoiceLink و subscription_period برابر 2592000 (30 روز، فعلاً تنها مقدار مجاز) لینک فاکتور بسازید؛ قیمت نمی‌تواند از 10000 استار بیشتر باشد. تمدیدها به صورت successful_payment با is_recurring می‌رسند و editUserStarSubscription تمدید را لغو یا دوباره فعال می‌کند.

چطور پرداخت با Telegram Stars را رایگان تست کنم؟

از محیط تست اختصاصی تلگرام استفاده کنید: آنجا یک حساب تست و یک ربات بسازید و API را از طریق /bot<token>/test/METHOD_NAME صدا بزنید. طبق گفته‌ی تلگرام، پرداخت‌های Stars را آنجا می‌توان آزادانه تست کرد.

ساخت ربات تلگرام: آموزش قدم‌به‌قدم از BotFather تا اولین پیام با Python

ساخت ربات تلگرام قدم‌به‌قدم: ساخت ربات در BotFather، گرفتن توکن، تست با getMe، پیدا کردن chat id و ارسال اولین پیام با curl و Python.

دیپلوی ربات تلگرام: راه‌اندازی روی VPS، داکر و هاست Serverless

آموزش دیپلوی و هاست ربات تلگرام: polling یا وب هوک، سرویس systemd روی VPS، داکر، Cloudflare Workers با secret_token و چک‌لیست راه‌اندازی.

Telegram Bot API 10.0 تا 10.5: تنظیمات ربات، ویجت‌ها، پیام‌های rich و ephemeral، حالت مهمان و بیشتر

تغییرات Telegram Bot API 10.0 تا 10.5: متد setMySettings و BotFullInfo، ویجت‌های HTML، پیام‌های rich و ephemeral و حالت مهمان، همراه با مثال JSON.

خطاهای Telegram Bot API: معنی هر خطا و روش رفع آن

خطاهای ربات تلگرام به زبان ساده: 400 chat not found، 403 bot was blocked by the user، 409 Conflict و 429 retry_after؛ علت، راه حل و کد مدیریت خطا.

محدودیت‌های Telegram Bot API: نرخ ارسال، خطای 429، حجم فایل و طول پیام

محدودیت‌های Telegram Bot API به زبان ساده: 30 پیام در ثانیه، 1 پیام در ثانیه در هر چت، 20 در دقیقه در گروه، مدیریت خطای 429 و محدودیت حجم فایل.

دستورات ربات تلگرام: setMyCommands، اسکوپ دستورات و دیپ‌لینک /start

تنظیم دستورات ربات تلگرام: /setcommands در @BotFather، متد setMyCommands با اسکوپ و زبان، پارامتر دیپ‌لینک /start و دستور /cmd@bot در گروه‌ها.

کیبورد ربات تلگرام: دکمه شیشه‌ای (inline keyboard)، دکمه‌های callback و reply keyboard

ساخت دکمه شیشه‌ای ربات تلگرام: inline keyboard با callback_data، پاسخ با answerCallbackQuery، ویرایش پیام بعد از کلیک، reply keyboard و ForceReply.

اتصال n8n به تلگرام: وصل کردن ربات، اجرای ورک‌فلو و ارسال پیام

اتصال n8n به تلگرام: توکن ربات به عنوان Access Token، وب هوک Telegram Trigger روی HTTPS عمومی، ارسال پیام با چت آیدی و رفع خطاهای رایج.

ارسال پیام با ربات تلگرام از طریق API تلگرام (sendMessage)

آموزش ارسال پیام با ربات تلگرام از طریق API تلگرام: متد sendMessage با curl، Python و JavaScript، قالب‌بندی HTML و MarkdownV2، دکمه شیشه‌ای و رفع خطاها.

توکن ربات تلگرام: چیست، چطور بگیریم، بررسی و باطل کنیم

توکن ربات تلگرام چیست و از کجا بگیریم؟ گرفتن توکن از BotFather، پیدا کردن توکن ربات قبلی، تست با getMe، باطل کردن توکن لو رفته و نگهداری امن آن.

وب هوک ربات تلگرام: راه‌اندازی setWebhook، بررسی و رفع خطا

آموزش ست وب هوک تلگرام با setWebhook: پیش‌نیازهای HTTPS و پورت‌ها، secret_token، بررسی با getWebhookInfo، حذف وب هوک و رفع خطاهای رایج مثل 409.

چت آیدی تلگرام: چیست، کجاست و چطور chat id کاربر، گروه و کانال را پیدا کنیم

چت آیدی تلگرام کجاست؟ پیدا کردن chat_id کاربر، گروه، سوپرگروه، کانال و تاپیک با getUpdates، معنی آیدی‌های منفی و رفع مشکل نتیجه خالی و خطای 409.

ربات اینلاین تلگرام: فعال کردن حالت inline و پاسخ به کوئری‌ها

ساخت ربات اینلاین تلگرام: فعال کردن حالت inline با @BotFather یا setMySettings، دریافت آپدیت inline_query و پاسخ با answerInlineQuery.

سرور تست تلگرام: چطور ربات را در محیط تست تلگرام تست کنیم

سرور تست تلگرام برای ربات‌ها: ورود به محیط تست، ساخت ربات تست در BotFather، فراخوانی Bot API با مسیر /test/ و سوییچ TEST در تستر ما.

ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنت‌ها و دکمه اشتراک‌گذاری

ورود با تلگرام در سایت با Telegram Login (OIDC) و ویجت قدیمی همراه کد بررسی hash، جاسازی پست کانال، ویجت کامنت و دکمه اشتراک‌گذاری تلگرام.

مرجع API جاوااسکریپت TelegramWidget: رویدادها، کدهای خطا و محدودیت‌ها

مرجع API جاوااسکریپت ویجت تلگرام: ویژگی‌ها، request()، رویدادها، کدهای خطا، متغیرهای CSS، widget_query و answerWidgetQuery و همه محدودیت‌ها.

مثال ویجت تلگرام: کد کامل HTML و ربات پایتون

مثال‌های کامل ویجت تلگرام با کد: کارت سفارش ثابت، شمارنده با widget_query، نظرسنجی زنده با ویجت اشتراکی و پیش‌نمایش در مرورگر با ربات پایتون.

ویجت تلگرام چیست؟ HTML تعاملی داخل پیام‌های ربات

ویجت تلگرام در Bot API 10.4 چیست؟ ارسال با sendWidget، وضعیت chat_data و public_data، محدودیت‌ها، جاهایی که فعلاً کار می‌کند و تفاوت با مینی اپ.

تست مینی اپ تلگرام: از mock در مرورگر تا اجرای واقعی در تلگرام

تست مینی اپ تلگرام قدم به قدم: حالت mock در مرورگر، اجرای localhost با تونل HTTPS، محیط تست، DevTools در هر پلتفرم و اعتبارسنجی initData در سرور.