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

به‌روزرسانی: ۷ آبان ۱۴۰۵ · 7 دقیقه مطالعه

برای ارسال پیام با ربات تلگرام، متد sendMessage را در آدرس https://api.telegram.org/bot<token>/sendMessage با دو پارامتر اجباری chat_id (گیرنده) و text (1 تا 4096 کاراکتر) صدا بزنید. در این راهنما نمونه‌های آماده curl، Python و JavaScript، قالب‌بندی HTML و MarkdownV2، دکمه‌های شیشه‌ای، ارسال به گروه و کانال و خطاهای رایج را می‌بینید.

ساختار درخواست در API تلگرام

همه متدهای Bot API به شکل https://api.telegram.org/bot<token>/METHOD_NAME صدا زده می‌شوند؛ کلمه bot بدون اسلش به توکن می‌چسبد. هم GET و هم POST کار می‌کند و پارامترها را می‌توانید به صورت query string، application/x-www-form-urlencoded، application/json یا multipart/form-data بفرستید. متن باید UTF-8 باشد، پس متن فارسی بدون مشکل ارسال می‌شود.

پاسخ همیشه JSON است: در صورت موفقیت ok برابر true و پیام در result؛ در صورت خطا ok برابر false همراه error_code و description. توکن یا چت آیدی ندارید؟ راهنمای توکن ربات و راهنمای چت آیدی را ببینید. یادتان باشد کاربر باید اول ربات را استارت کرده باشد.

ارسال پیام با curl

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage?chat_id=123456789&text=Hello"

برای پیام‌های پیچیده‌تر بدنه JSON بفرستید:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 123456789, "text": "Hello from curl"}'

ارسال پیام توسط ربات تلگرام با Python

import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"

def send_message(chat_id, text, **params):
    payload = {"chat_id": chat_id, "text": text, **params}
    data = requests.post(f"{API}/sendMessage", json=payload, timeout=10).json()
    if not data["ok"]:
        raise RuntimeError(f'{data["error_code"]}: {data["description"]}')
    return data["result"]

msg = send_message(123456789, "سلام از پایتون!")
print("message_id:", msg["message_id"])

message_id را نگه دارید تا بعداً بتوانید پیام را ویرایش یا حذف کنید.

ارسال پیام با JavaScript

در Node.js نسخه 18 به بالا (به صورت ES module)، روی سرور اجرا شود:

const TOKEN = process.env.TELEGRAM_BOT_TOKEN;

const res = await fetch(`https://api.telegram.org/bot${TOKEN}/sendMessage`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ chat_id: 123456789, text: "سلام از جاوااسکریپت!" }),
});
const data = await res.json();
if (!data.ok) throw new Error(`${data.error_code}: ${data.description}`);

این کد را در مرورگر یا اپ سمت کاربر اجرا نکنید؛ هر کس توکن را ببیند کنترل ربات را دارد.

قالب‌بندی با parse_mode HTML

با ‎"parse_mode": "HTML" فقط این تگ‌ها پشتیبانی می‌شوند:

<b> <strong> <i> <em> <u> <ins> <s> <strike> <del>
<span class="tg-spoiler"> <tg-spoiler> <a href="..."> <code> <pre>
<pre><code class="language-python"> <blockquote> <blockquote expandable>

هر کاراکتر <، > و & که جزو تگ نیست باید به <، > و & تبدیل شود؛ متن کاربران را قبل از ارسال escape کنید:

import html

name = html.escape("Tom & Jerry <3", quote=False)
send_message(123456789, f"<b>سفارش 1024</b> برای {name} <i>ارسال شد</i>",
             parse_mode="HTML")

قالب‌بندی با MarkdownV2

در MarkdownV2 از *bold*، _italic_، __underline__، ~strike~، ||spoiler|| و [text](https://example.com) استفاده می‌شود. نکته اصلی: خارج از entityها این کاراکترها باید با بک‌اسلش escape شوند:

_ * [ ] ( ) ~ ` > # + - = | { } . !

خود بک‌اسلش هم باید escape شود. علائم فارسی مثل «،» و «؟» در این لیست نیستند، اما نقطه و علامت تعجب هستند. نقطه یا خط تیره escape‌نشده رایج‌ترین علت خطای 400 با متن can't parse entities است. تابع کمکی:

import re

def escape_md2(text):
    return re.sub(r"([_*\[\]()~`>#+\-=|{}.!\\])", r"\\\1", text)

send_message(123456789, "*" + escape_md2("نسخه 2.1 منتشر شد!") + "*",
             parse_mode="MarkdownV2")

دکمه شیشه‌ای (inline keyboard) با reply_markup

دکمه‌های شیشه‌ای زیر پیام نمایش داده می‌شوند. دکمه url لینک باز می‌کند و دکمه callback_data رشته‌ای 1 تا 64 بایتی را در آپدیت callback_query به ربات برمی‌گرداند. هر حرف فارسی در UTF-8 دو بایت است، پس در callback_data شناسه‌های کوتاه لاتین بگذارید.

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "Choose:",
    "reply_markup": {"inline_keyboard": [[
      {"text": "Open site", "url": "https://example.com"},
      {"text": "Press", "callback_data": "pressed"}
    ]]}
  }'

بعد از زدن دکمه callback، متد answerCallbackQuery را صدا بزنید تا حالت انتظار روی دکمه برداشته شود.

ارسال پیام در گروه، کانال و تاپیک

• گروه: ربات را عضو گروه کنید و از آیدی منفی گروه استفاده کنید؛ سوپرگروه‌ها با ‎-100 شروع می‌شوند.
• کانال: ربات باید ادمین با اجازه ارسال پیام باشد. کانال عمومی ‎@channelusername را قبول می‌کند و کانال خصوصی آیدی عددی ‎-100… را.
• تاپیک: پارامتر message_thread_id را اضافه کنید.

پیام بی‌صدا و پیش‌نمایش لینک

{
  "chat_id": 123456789,
  "text": "تغییرات نسخه جدید: https://example.com/changelog",
  "disable_notification": true,
  "protect_content": true,
  "link_preview_options": {"is_disabled": true}
}

disable_notification اعلان را بدون صدا می‌فرستد، protect_content جلوی فوروارد و ذخیره را می‌گیرد و link_preview_options با is_disabled پیش‌نمایش لینک را حذف می‌کند.

خطاهای رایج ارسال پیام

import time

def send_with_retry(chat_id, text, **params):
    while True:
        payload = {"chat_id": chat_id, "text": text, **params}
        r = requests.post(f"{API}/sendMessage", json=payload, timeout=10).json()
        if r["ok"]:
            return r["result"]
        if r["error_code"] != 429:
            raise RuntimeError(r["description"])
        time.sleep(r.get("parameters", {}).get("retry_after", 1))

برای ارسال انبوه، حدود 1 پیام در ثانیه در هر چت، 20 پیام در دقیقه در هر گروه و حدود 30 پیام در ثانیه در مجموع را رعایت کنید.

تست sendMessage در مرورگر

1. متد sendMessage را در Bot API Tester باز کنید و توکن را وارد کنید (در localStorage مرورگر خودتان می‌ماند).
2. chat_id و text و در صورت نیاز parse_mode و reply_markup را پر کنید.
3. دکمه اجرا یا Ctrl+Enter را بزنید و پاسخ JSON را ببینید.

فهرست کامل پارامترها در مرجع متد sendMessage (انگلیسی) آمده است. اگر ربات باید به پیام‌های ورودی جواب بدهد، راه‌اندازی وب‌هوک ربات تلگرام را هم ببینید.