Telegram Bot API

Telegram Bot API 10.0–10.5: bot ayarları, widget'lar, rich mesajlar, ephemeral mesajlar, misafir modu ve dahası

· 8 dk okuma

22 Kasım 2026'da yayımlanan Telegram Bot API 10.5, 194 metotla Bot API'nin güncel sürümüdür. 8 Mayıs 2026'da Bot API 10.0 ile başlayan 10.x serisi misafir modu, live photo'lar, akış halinde taslaklarla rich mesajlar, ephemeral mesajlar, topluluklar (communities), katılma isteği sorguları, mesaj içinde etkileşimli HTML widget'lar (10.4) ve 10.5'te setMySettings metodu ile getMe'nin döndürdüğü yeni BotFullInfo nesnesini getirdi. Aşağıda her sürümdeki yenilikleri kısa JSON örnekleriyle ve mevcut bir botu bozabilecek değişikliklerle birlikte bulacaksınız.

Telegram Bot API 10'a genel bakış

SürümTarihÖne çıkanlar
10.08 Mayıs 2026Misafir modu, live photo'lar, anketlerde medya, tepki kaldırma
10.111 Haziran 2026Rich mesajlar ve rich taslaklar, katılma isteği sorguları
10.214 Temmuz 2026Ephemeral mesajlar, topluluklar, subscription güncellemesi, Mini App origin koruması
10.324 Ağustos 2026EphemeralMessageParameters, durdurulabilir taslaklar, DisabledButton, rich mesajlarda butonlar
10.49 Kasım 2026HTML widget'lar, her sohbette callback query'lere ephemeral yanıt, rich mesajlardan alıntı, TON cüzdan kartı, sohbet paylaşım temaları
10.522 Kasım 2026setMySettings, getMe'de BotFullInfo, callback_query_mode, bot davet linkleri, genişletilebilir alıntılarda bloklar

Bot API 10.0: misafir modu, live photo'lar ve anketler

Misafir modu. @BotFather Mini App'inde Guest Mode'u açtıktan sonra kullanıcılar botunuzu üyesi olmadığı sohbetlerde anabilir. Bot bir guest_message güncellemesi alır ve mesajdaki guest_query_id ile bir InlineQueryResult göndererek answerGuestQuery ile tek bir yanıt verebilir:

{
  "guest_query_id": "<message.guest_query_id>",
  "result": {
    "type": "article",
    "id": "1",
    "title": "Çeviri",
    "input_message_content": {"message_text": "Bonjour tout le monde"}
  }
}

Misafir bot sohbet geçmişine veya üye listesine erişemez ve tekrar anılmadıkça ya da yanıtlanmadıkça sonraki mesajları görmez.

Bot API 10.1: Telegram rich mesajlar ve katılma isteği sorguları

Rich mesajlar raporlar, dokümantasyon ve yapay zekâ yanıtları gibi yapılandırılmış çıktılar içindir. sendRichMessage, içeriği html veya markdown olarak taşıyan bir rich_message nesnesi alır (10.2 açık blocks ve bir media listesi ekledi). Desteklenenler: başlıklar, listeler ve görev listeleri, tablolar, alıntılar, katlanabilir ayrıntılar, dipnotlar, LaTeX formülleri, haritalar, kolajlar, slayt gösterileri ve medya blokları. Limitler: 32768 UTF-8 karakter, 500 blok, 16 iç içe geçme seviyesi, 50 medya ve 20 tablo sütunu.

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendRichMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "rich_message": {
      "markdown": "# Haftalık rapor\n\n| Metrik | Değer |\n|:-------|------:|\n| Kullanıcılar | **1204** |\n| Hatalar | 3 |\n\n- [x] v2.1 yayına alındı\n- [ ] Dokümantasyonu güncelle\n\n$$E = mc^2$$"
    }
  }'

sendRichMessageDraft, üretilmekte olan bir rich mesajı özel sohbete parça parça akıtır. Taslak 30 saniyelik geçici bir önizlemedir, bu yüzden sonunda sendRichMessage ile gönderin. editMessageText de artık rich_message kabul ediyor.

Katılma isteği sorguları. Botunuz bir sohbetin koruma botu (guard bot) olarak ayarlandığında chat_join_request güncellemesi bir query_id taşır. Hemen answerChatJoinRequestQuery ile karar verin (approve, decline veya kararı diğer yöneticilere bırakmak için queue) ya da önce sendChatJoinRequestWebApp ile bir Mini App gösterin; Mini App init verisinde chat_join_request_query_id alır.

{"chat_join_request_query_id": "<chat_join_request.query_id>", "result": "approve"}

Anketlere 10.1'de link medyası da eklendi.

Bot API 10.2: Telegram ephemeral mesajlar, topluluklar ve Mini App güvenliği

Ephemeral mesajlar, gruptaki yalnızca bir kullanıcının ve botun görebildiği mesajlardır; ipuçlarını, karşılama metinlerini ve kişisel sonuçları ortak akıştan uzak tutar. Kullanıcılar da kimsenin görmediği ephemeral komutlar (BotCommand.is_ephemeral) gönderebilir. Teslimat kuralları:

Ephemeral mesajların kendi metotları vardır: editEphemeralMessageText, editEphemeralMessageMedia, editEphemeralMessageCaption, editEphemeralMessageReplyMarkup ve deleteEphemeralMessage:

{"chat_id": -1001234567890, "receiver_user_id": 123456789, "ephemeral_message_id": 15}

Bot API 10.3: EphemeralMessageParameters, durdurulabilir taslaklar ve DisabledButton

Ephemeral mesajlarda geriye uyumsuz değişiklik. 10.2'deki receiver_user_id ve callback_query_id parametreleri 13 gönderim metodunda (sendMessage, sendPhoto, sendVideo, sendAnimation, sendAudio, sendDocument, sendLivePhoto, sendSticker, sendVideoNote, sendVoice, sendContact, sendLocation, sendVenue) tek bir nesneyle, ephemeral_message_parameters ile değiştirildi. sendRichMessage da bunu kabul eder; yeni replace_callback_query_message ise ephemeral mesajı, butona basılan mesajın yerinde gösterir:

{
  "chat_id": -1001234567890,
  "text": "Bunu yalnızca siz görebilirsiniz.",
  "ephemeral_message_parameters": {
    "receiver_user_id": 123456789,
    "callback_query_id": "<callback_query.id>",
    "replace_callback_query_message": true
  }
}

Durdurulabilir taslaklar. Stop butonu göstermek için sendMessageDraft veya sendRichMessageDraft'a can_stop gönderin. Kullanıcı butona bastığında botunuz chat ve draft_id içeren bir stopped_message_generation güncellemesi alır; böylece modeli durdurabilirsiniz. keep_on_stop yarım kalan taslağı bir süre görünür bırakır; kalıcı olması gerekiyorsa normal mesaj olarak gönderin.

import time
import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
text, last = "", 0.0
for chunk in generate_reply():          # LLM token akışınız
    text += chunk
    if time.monotonic() - last > 0.5:   # her token için taslak göndermeyin
        requests.post(f"{API}/sendMessageDraft", json={"chat_id": 123456789,
                      "draft_id": 1, "text": text, "can_stop": True}, timeout=10)
        last = time.monotonic()
requests.post(f"{API}/sendMessage", json={"chat_id": 123456789, "text": text}, timeout=10)
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const post = (method, body) => fetch(`${API}/${method}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(10_000),
});

let text = "", last = 0;
for await (const chunk of generateReply()) {  // LLM token akışınız
  text += chunk;
  if (Date.now() - last > 500) {               // her token için taslak göndermeyin
    await post("sendMessageDraft", { chat_id: 123456789,
      draft_id: 1, text, can_stop: true });
    last = Date.now();
  }
}
await post("sendMessage", { chat_id: 123456789, text });

Bot API 10.4: Telegram widget'lar, her sohbette ephemeral yanıtlar ve TON cüzdan

Widget'lar. Botlar artık mesajların içinde küçük, etkileşimli HTML blokları gönderebilir. Bir widget, uygulamanın ağ erişimi olmayan bir sandbox'ta çalıştırdığı tek bir HTML dokümanı (en fazla 32768 bayt, zlib sıkıştırmasından sonra 4096 bayt) ve yalnızca botun değiştirdiği bir durumdan (state) oluşur: tek mesaja ait chat_data ve widget nerede gösterilirse orada paylaşılan public_data. Yeni metotlar: sendWidget, sendSharedWidget, answerWidgetQuery, editMessageWidgetData ve editSharedWidgetData; yeni güncellemeler: widget_query ve shared_widget_query; inline mod için InputWidgetMessageContent ve InputSharedWidgetMessageContent (şimdilik yalnızca test sunucusunda).

{
  "chat_id": 123456789,
  "html": "<h3>Sipariş #1042</h3><p>2 × Margherita, 1 × Limonata</p><p><strong>Toplam: $23.50</strong></p>",
  "caption": "Sipariş #1042: $23.50"
}

Üretimde widget'lar şimdilik yalnızca özel sohbetlerde çalışır ve korumalı içerik olarak gönderilir, yani iletilemez; gruplar, inline mod ve iletme test sunucusunda çalışır. Widget mesajları copyMessage / copyMessages ile kopyalanamaz ve can_send_other_messages izni artık widget'ları da kapsar. Ayrıntılar: Telegram widget'ları rehberi.

Her sohbette callback query'lere ephemeral yanıtlar (kanal DM sohbetleri hariç). ephemeral_message_parameters içinde receiver_user_id olmadan callback_query_id gönderin; mesaj yalnızca butona basan kullanıcıya gösterilir. receiver_user_id ve gönderim metotlarının chat_id parametresi artık isteğe bağlıdır. answerCallbackQuery'yi yine de çağırmanız gerekir.

{
  "text": "Bu yanıtı yalnızca siz görebilirsiniz.",
  "ephemeral_message_parameters": {"callback_query_id": "<callback_query.id>"}
}

Bot API 10.5: setMySettings, BotFullInfo ve bot davet linkleri

Bot ayarları koddan. Yeni setMySettings metodu, eskiden yalnızca @BotFather'da olan ayarları değiştirir. Tüm parametreler isteğe bağlıdır, yalnızca değiştirmek istediklerinizi gönderin; metot True döndürür:

{
  "supports_inline_queries": true,
  "inline_query_placeholder": "Tarif ara...",
  "can_join_groups": false,
  "has_topics_enabled": true,
  "callback_query_mode": "auto"
}

Bunu https://api.telegram.org/bot<token>/setMySettings adresine gönderin veya kendi token'ınızla Bot API Tester'da deneyin, ardından sonucu görmek için getMe çağırın.

BotFullInfo (geriye uyumsuz değişiklik). getMe artık User yerine yeni BotFullInfo nesnesini döndürüyor ve yalnızca getMe'nin döndürdüğü alanlar User'dan kaldırıldı. BotFullInfo ayrıca active_usernames, inline_query_placeholder, needs_inline_query_location ve has_topic_sidebar ekler. getMe sonucundan can_join_groups, can_read_all_group_messages veya supports_inline_queries gibi alanları okuyan kod çalışmaya devam eder, çünkü bu alanlar BotFullInfo'da var. Bozulan, bu alanları diğer User nesnelerinde bekleyen kod ve getMe sonucunu User olarak tanımlayan tipli koddur.

Bir botu Bot API 10.5'e yükseltme

  1. Kütüphanenizi (python-telegram-bot, aiogram, grammY, Telegraf ve diğerleri) changelog'unda Bot API 10.5 desteği yazan bir sürüme güncelleyin.
  2. 10.2 tarzı receiver_user_id ve callback_query_id'yi ephemeral_message_parameters içine taşıyın.
  3. Açık bir allowed_updates listesi gönderiyorsanız işlediğiniz yeni türleri ekleyin: guest_message, subscription, stopped_message_generation, widget_query, shared_widget_query.
  4. Anket doğrulamasını gevşetin: artık tek seçenekli ankete izin var.
  5. Mini App'lerde her Telegram.WebApp çağrısının kayıtlı alan adında çalıştığından emin olun.
  6. Kodunuz türe adıyla başvuruyorsa StoryAreaPosition'ı AreaPosition olarak yeniden adlandırın.
  7. getMe sonucunu BotFullInfo olarak ele alın ve can_join_groups gibi yalnızca getMe'ye ait alanları diğer User nesnelerinden okumayı bırakın.
  8. Rich mesajlarda genişletilebilir alıntıları text yerine blocks ile oluşturun.
  9. callback_query_mode'u "auto" veya "inline" yaparsanız callback handler'ınızın message yokken inline_message_id kabul etmesini sağlayın.
  10. Yeni metotları kendi token'ınızla Bot API Tester'da deneyin: setMySettings, sendWidget, sendRichMessage, deleteEphemeralMessage ve answerChatJoinRequestQuery.

Ephemeral ve normal mesajların temeli aynıdır; bu yüzden Bot API ile mesaj gönderme iyi bir tekrar olur. Telegram Bot API limitleri ise rich mesaj limitlerini klasik limitlerin yanında listeler. Tüm geçmiş resmi Bot API changelog sayfasında.

Sık sorulan sorular

Telegram Bot API'nin en son sürümü hangisi?

22 Kasım 2026'da yayımlanan, 194 metotlu Bot API 10.5. 8 Mayıs 2026'da Bot API 10.0 ile başlayan 10.x serisinin altıncı sürümüdür. Botun kendi ayarlarını değiştirmesini sağlayan setMySettings'i ekledi ve getMe artık BotFullInfo döndürüyor. Önceki sürüm 10.4 (9 Kasım 2026) mesajlara HTML widget'ları getirmişti.

Telegram'da rich mesaj nedir?

Rich mesajlar (Bot API 10.1) sendRichMessage ile gönderilen yapılandırılmış mesajlardır: başlıklar, listeler, tablolar, LaTeX formülleri, medya blokları, haritalar ve 10.3'ten beri butonlar. İçeriği rich_message içinde HTML, Markdown veya blok olarak, en fazla 32768 UTF-8 karakter halinde verirsiniz.

Telegram botlarında ephemeral mesaj nedir?

Ephemeral mesajlar (Bot API 10.2), bir grup veya süper grupta yalnızca tek bir kullanıcının ve botun görebildiği mesajlardır. 10.3'ten beri sendMessage ve diğer gönderim metotlarında ephemeral_message_parameters ile gönderilir; 10.4'ten beri bot, kanal DM sohbetleri hariç her sohbette callback query'ye ephemeral yanıt verebilir. Teslimat garanti değildir, özellikle kullanıcı çevrimdışıysa.

Telegram botunda yapay zekâ yanıtları nasıl akış (stream) halinde gösterilir?

Özel sohbette aynı draft_id ile sendMessageDraft veya sendRichMessageDraft'ı tekrar tekrar çağırın, ardından son metni sendMessage veya sendRichMessage ile gönderin; taslak yalnızca 30 saniyelik geçici bir önizlemedir. can_stop ile kullanıcı bir Stop butonu görür ve botunuz stopped_message_generation alır.

Telegram Bot API 10.5'teki setMySettings nedir?

setMySettings, botun kendi ayarlarını @BotFather olmadan değiştirmesini sağlar: inline mod, privacy mode, gruplara katılma, business bağlantıları, misafir ve katılma isteği sorguları, özel sohbetlerde konular, botlar arası iletişim ve callback_query_mode. Yalnızca değiştirmek istediğiniz alanları gönderin; True döner. Güncel değerler artık BotFullInfo döndüren getMe'den okunur.

Telegram Bot API 10.0'daki misafir modu (guest mode) nedir?

Misafir modu, botun üyesi olmadığı bir sohbette anıldığında yanıt vermesini sağlar. Bot bir guest_message güncellemesi alır ve sohbet geçmişine erişmeden answerGuestQuery ile bir kez yanıt verir. @BotFather Mini App'inden açılır.

Telegram bot nasıl yapılır? BotFather ile adım adım bot oluşturma

Telegram bot yapma rehberi: BotFather'da /newbot ile bot oluşturun, token'ı getMe ile test edin, chat ID'yi bulun ve Python ile ilk mesajı gönderin.

Telegram botu nasıl deploy edilir: VPS, Docker ve serverless hosting

Telegram botu sunucuya kurma: polling mi webhook mu, VPS'te systemd servisi, Docker, secret_token ile Cloudflare Workers ve yayın öncesi kontrol listesi.

Telegram Bot API hataları: her hata ne anlama gelir ve nasıl çözülür

Telegram Bot API hataları: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nedenleri, çözümleri ve hata yönetimi kodu.

Telegram Bot API limitleri: mesaj gönderme hızı, 429 hatası, dosya boyutu ve mesaj uzunluğu

Telegram Bot API limitleri: saniyede 30 mesaj, sohbet başına 1 mesaj/sn, grupta dakikada 20, 429 retry_after yönetimi, dosya boyutu ve mesaj uzunluğu.

Telegram bot komutları: setMyCommands, komut kapsamları ve /start deep link

Telegram bot komutları nasıl eklenir: @BotFather /setcommands, kapsam ve dil destekli setMyCommands, /start deep link parametresi, gruplarda /komut@bot.

Telegram bot klavyeleri: inline klavye, callback butonları ve reply klavye

Telegram bot butonu ekleme: callback_data ile inline klavye, answerCallbackQuery, basıştan sonra mesajı düzenleme, reply klavye ve ForceReply örnekleri.

n8n Telegram entegrasyonu: botu bağlama, workflow tetikleme ve mesaj gönderme

n8n'i Telegram'a bağlayın: bot token'ı Access Token olarak girin, Telegram Trigger webhook'u için HTTPS kurun, chat id ile mesaj gönderin, hataları çözün.

Telegram Bot API ile mesaj gönderme (send message): curl, Python ve JavaScript

Telegram Bot API send message rehberi: curl, Python ve JavaScript ile sendMessage, HTML ve MarkdownV2 biçimlendirme, inline butonlar ve sık hatalar.

Telegram bot token nasıl alınır, nerede bulunur ve nasıl iptal edilir?

Telegram bot token nedir, BotFather'dan nasıl alınır, mevcut botun token'ı nerede bulunur? getMe ile test, 401 hatası ve sızan token'ı iptal etme.

Telegram bot webhook kurulumu: URL, secret token, getWebhookInfo ve sorun giderme

Telegram bot webhook kurulumu: setWebhook ile HTTPS URL ve secret_token ayarlayın, getWebhookInfo ile hataları görün; 409 Conflict ve n8n localhost çözümü.

Telegram chat ID nasıl bulunur: kullanıcı, grup, kanal ve konu için adım adım

Telegram chat ID nasıl bulunur? getUpdates ile kullanıcı, grup, süper grup ve kanal ID'sini öğrenin; -100 ön eki, konu ID'si ve boş result sorunu.

Telegram inline bot: inline modu açma ve inline sorguları yanıtlama

Telegram inline bot nasıl yapılır: inline modu @BotFather veya setMySettings ile açın, inline_query güncellemelerini answerInlineQuery ile yanıtlayın.

Telegram botlarında Stars ile ödeme: fatura, ön onay, iade ve abonelikler

Telegram botunuzda Stars ile ödeme alın: XTR ile sendInvoice, pre_checkout_query, successful_payment, iade ve abonelikler; Python ve JS kodu.

Telegram test sunucusu: Telegram botunu test ortamında nasıl test edersiniz?

Telegram test sunucusu nedir? Test ortamına giriş, test botu oluşturma, Bot API'yi /test/ ile çağırma ve Bot API Tester'da TEST modu adım adım.

Web siteniz için Telegram widget'ları: Telegram ile giriş, gönderi gömme, yorumlar ve paylaş butonu

Sitenize Telegram ile giriş ekleyin: yeni Telegram Login (OIDC), eski Login Widget ve hash kontrolü, gönderi gömme, yorumlar ve paylaş butonu.

TelegramWidget JavaScript API: özellikler, olaylar, hata kodları ve sınırlar

Telegram widget API başvurusu: TelegramWidget özellikleri, request(), olaylar, hata kodları, CSS değişkenleri, widget_query, answerWidgetQuery ve sınırlar.

Telegram widget örnekleri: eksiksiz HTML ve Python bot kodu

Çalışan Telegram widget örnekleri: statik sipariş kartı, widget_query ile sayaç, paylaşılan canlı anket ve yerel önizleme; HTML ve Python bot kodu.

Telegram widget: bot mesajının içinde çalışan etkileşimli HTML

Telegram widget nedir: Bot API 10.4'teki sendWidget, chat_data ve public_data nasıl çalışır, bugün nerede kullanılabilir, Mini App'ten farkı nedir?

Telegram Mini App nasıl test edilir: tarayıcıdaki mock'tan gerçek Telegram'a

Telegram Mini App test rehberi: tarayıcıda mock mod, HTTPS tünelle localhost, test ortamı, platformlara göre DevTools ve sunucuda initData doğrulama.