Telegram Bot API

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

· 8 dk okuma

Telegram inline bot, doğrudan mesaj alanına yazılan sorgulara yanıt verir: kullanıcı herhangi bir sohbette @your_bot ve bir metin yazar, botunuz inline_query güncellemesi alıp answerInlineQuery ile sonuç listesi döndürür, kullanıcı da sonuçlardan birine dokunarak onu gönderir. Bunun için inline modu açmanız (@BotFather'da /setinline veya Bot API 10.5'ten beri setMySettings), inline_query güncellemelerini işlemeniz ve en fazla 50 sonuç döndürmeniz yeterli. Aşağıda her adım ve eksiksiz bir Python/JavaScript örneği var.

Inline mod nasıl çalışır?

Inline mod, botun üye olmadığı sohbetler de dahil her sohbette çalışır. Akış şöyledir:

  1. Kullanıcı giriş alanına botun kullanıcı adını ve sorguyu yazar, ör. @your_bot merhaba. Sohbete henüz bir şey gönderilmez.
  2. Bot bir inline_query güncellemesi alır.
  3. Bot, answerInlineQuery ile sonuç listesi döndürür: makaleler, fotoğraflar, GIF'ler, videolar, çıkartmalar, konumlar vb.
  4. Kullanıcı bir sonuca dokunur. Mesajı kullanıcı gönderir, gönderen adının yanında botun kullanıcı adı görünür; Bot API'de bu mesajda via_bot alanı bulunur.
  5. İsteğe bağlı olarak bot, hangi sonucun gönderildiğini bildiren bir chosen_inline_result güncellemesi alır.

Telegram botunda inline modu açma

Yeni botlarda inline mod kapalıdır. Henüz botunuz yoksa Telegram bot oluşturma rehberiyle başlayın. Ardından iki yoldan birini seçin.

1. yol: @BotFather

  1. @BotFather'a /setinline gönderin ve botunuzu seçin.
  2. Kullanıcının botun adını yazdıktan sonra giriş alanında göreceği placeholder metnini girin, ör. Biçimlendirilecek metni yazın…
  3. İsteğe bağlı: /setinlinegeo her sorguyla birlikte kullanıcının konumunu ister; /setinlinefeedback chosen_inline_result güncellemelerini açar.

2. yol: setMySettings (Bot API 10.5)

Bot API 10.5'ten itibaren bot kendi ayarlarını setMySettings ile değiştirebilir. Göndermediğiniz ayarlar olduğu gibi kalır:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMySettings" \
  -H "Content-Type: application/json" \
  -d '{"supports_inline_queries": true, "inline_query_placeholder": "Biçimlendirilecek metni yazın…", "inline_feedback_share_denominator": 1}'

Inline modla ilgili parametreler:

Sonucu kod yazmadan kontrol etmek için Bot API Tester'da setMySettings metodunu açın, token'ınızı yapıştırıp çalıştırın, ardından getMe çağırın: dönen BotFullInfo nesnesinde supports_inline_queries ve özel bir değer verdiyseniz inline_query_placeholder bulunur.

inline_query güncellemesi

Kullanıcı yazarken bot şu alanlara sahip InlineQuery nesneleri alır:

AlanAnlamı
idSorgunun benzersiz kimliği; answerInlineQuery'ye inline_query_id olarak verilir
fromSorguyu yazan kullanıcı
querySorgu metni, en fazla 256 karakter; boş olabilir — bu durumda varsayılan veya popüler sonuçları döndürün
offsetDöndürülecek sonuçların başlangıç noktası; botunuz next_offset ile belirler
chat_typeİsteğe bağlı: sender (sorguyu gönderenle özel sohbet), private, group, supergroup veya channel; gizli sohbetlerde genellikle bilinmez
locationİsteğe bağlı; yalnızca bot konum istiyorsa gelir

getUpdates veya setWebhook'a allowed_updates veriyorsanız listeye inline_query (gerekiyorsa chosen_inline_result) ekleyin, aksi halde bu güncellemeler gelmez.

answerInlineQuery parametreleri

answerInlineQuery başarılı olduğunda True döndürür. Sorgu başına en fazla 50 sonuç gönderilebilir.

ParametreAçıklama
inline_query_idZorunlu. Sorgunun id değeri
resultsZorunlu. InlineQueryResult nesneleri dizisi (≤ 50)
cache_timeSonucun sunucuda önbellekte tutulabileceği en uzun süre (saniye); varsayılan 300
is_personaltrue ise sonuçlar yalnızca bu kullanıcı için önbelleğe alınır; varsayılan olarak aynı sorguyu yazan herkes aynı sonuçları alabilir
next_offsetİstemcinin aynı metinli bir sonraki sorguda göndereceği offset; başka sonuç yoksa boş metin; en fazla 64 bayt
buttonSonuçların üstünde gösterilen InlineQueryResultsButton

Inline sonuç türleri

Telegram istemcileri 20 sonuç türünü destekler. On ikisi yeni içerik tanımlar (article, photo, gif, mpeg4_gif, video, audio, voice, document, location, venue, contact, game), sekiz InlineQueryResultCached… türü ise Telegram sunucularında zaten bulunan dosyaları file_id ile yeniden kullanır. Her sonucun bir type değeri ve 1–64 baytlık bir id değeri olmalıdır. En sık kullanılanlar:

Inline sonuçlardaki tüm URL'ler son kullanıcıya görünür hale gelir, bu yüzden onları herkese açık kabul edin. parse_mode biçimlendirme kuralları Bot API ile mesaj gönderme rehberindekiyle aynıdır.

Örnek: Python ve JavaScript ile inline bot

Bu bot sorgu metnini kalın, italik veya eş aralıklı (monospace) olarak biçimlendirir. Boş sorguya özel sohbeti açan bir buton gösterilir; orada /start komutu, inline moda geri dönen butonlarla yanıtlanır. Çalıştırmadan önce BOT_TOKEN ortam değişkenini ayarlayın.

import html
import os
import requests

TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"


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 article(result_id, title, text, message_html):
    return {
        "type": "article",
        "id": result_id,  # 1-64 bayt, bir yanıt içinde benzersiz
        "title": title,
        "description": text[:100],
        "input_message_content": {"message_text": message_html, "parse_mode": "HTML"},
    }


def on_inline_query(query):
    text = query["query"].strip()
    if not text:  # boş sorgu: sonuç yok, yalnızca özel sohbeti açan buton
        call("answerInlineQuery", inline_query_id=query["id"], results=[], cache_time=5,
             button={"text": "Bot nasıl kullanılır", "start_parameter": "help"})
        return
    safe = html.escape(text)
    results = [
        article("bold", "Kalın", text, f"<b>{safe}</b>"),
        article("italic", "İtalik", text, f"<i>{safe}</i>"),
        article("mono", "Eş aralıklı", text, f"<code>{safe}</code>"),
    ]
    call("answerInlineQuery", inline_query_id=query["id"], results=results, cache_time=5)


def on_message(msg):
    if msg.get("text", "").startswith("/start"):  # butondan gelen "/start help" dahil
        call("sendMessage", chat_id=msg["chat"]["id"],
             text="Herhangi bir sohbette kullanıcı adımı ve bir metin yazın, biçimlendireyim.",
             reply_markup={"inline_keyboard": [[
                 {"text": "Burada dene", "switch_inline_query_current_chat": "Merhaba"},
                 {"text": "Sohbet seç", "switch_inline_query": "Merhaba"},
             ]]})


offset = 0
while True:
    updates = call("getUpdates", offset=offset, timeout=30,
                   allowed_updates=["message", "inline_query", "chosen_inline_result"])
    for update in updates:
        offset = update["update_id"] + 1
        try:
            if "inline_query" in update:
                on_inline_query(update["inline_query"])
            elif "chosen_inline_result" in update:
                chosen = update["chosen_inline_result"]
                print("seçilen:", chosen["result_id"], "sorgu:", chosen["query"])
            elif "message" in update:
                on_message(update["message"])
        except RuntimeError as err:
            print(err)
const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;

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;
}

const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");

function article(id, title, text, messageHtml) {
  return {
    type: "article",
    id, // 1-64 bayt, bir yanıt içinde benzersiz
    title,
    description: text.slice(0, 100),
    input_message_content: { message_text: messageHtml, parse_mode: "HTML" },
  };
}

async function onInlineQuery(query) {
  const text = query.query.trim();
  if (!text) { // boş sorgu: sonuç yok, yalnızca özel sohbeti açan buton
    await call("answerInlineQuery", {
      inline_query_id: query.id, results: [], cache_time: 5,
      button: { text: "Bot nasıl kullanılır", start_parameter: "help" },
    });
    return;
  }
  const safe = escapeHtml(text);
  const results = [
    article("bold", "Kalın", text, `<b>${safe}</b>`),
    article("italic", "İtalik", text, `<i>${safe}</i>`),
    article("mono", "Eş aralıklı", text, `<code>${safe}</code>`),
  ];
  await call("answerInlineQuery", { inline_query_id: query.id, results, cache_time: 5 });
}

async function onMessage(msg) {
  if (msg.text?.startsWith("/start")) { // butondan gelen "/start help" dahil
    await call("sendMessage", {
      chat_id: msg.chat.id,
      text: "Herhangi bir sohbette kullanıcı adımı ve bir metin yazın, biçimlendireyim.",
      reply_markup: { inline_keyboard: [[
        { text: "Burada dene", switch_inline_query_current_chat: "Merhaba" },
        { text: "Sohbet seç", switch_inline_query: "Merhaba" },
      ]] },
    });
  }
}

let offset = 0;
while (true) {
  const updates = await call("getUpdates", {
    offset, timeout: 30, allowed_updates: ["message", "inline_query", "chosen_inline_result"],
  });
  for (const update of updates) {
    offset = update.update_id + 1;
    try {
      if (update.inline_query) await onInlineQuery(update.inline_query);
      else if (update.chosen_inline_result) {
        const chosen = update.chosen_inline_result;
        console.log("seçilen:", chosen.result_id, "sorgu:", chosen.query);
      } else if (update.message) await onMessage(update.message);
    } catch (err) {
      console.error(err.message);
    }
  }
}

JavaScript sürümünü bot.mjs adıyla Node.js 18+ ile çalıştırın, sonra herhangi bir sohbette @your_bot merhaba yazın. Aynı handler'lar webhook ile de çalışır — bkz. Telegram bot webhook kurulumu.

next_offset ile sayfalama

50'den fazla eşleşme mi var? Sonuçları sayfa sayfa döndürün: ilk istekte offset boştur, kullanıcı aşağı kaydırdığında sizin verdiğiniz next_offset geri gelir:

PAGE_SIZE = 20  # answerInlineQuery en fazla 50 sonuç kabul eder


def answer_page(query, items):
    start = int(query["offset"] or 0)  # ilk istekte offset ""
    page = items[start:start + PAGE_SIZE]
    more = start + PAGE_SIZE < len(items)
    call("answerInlineQuery", inline_query_id=query["id"], results=page,
         next_offset=str(start + PAGE_SIZE) if more else "")  # "" = başka sonuç yok
const PAGE_SIZE = 20; // answerInlineQuery en fazla 50 sonuç kabul eder

async function answerPage(query, items) {
  const start = Number(query.offset || 0); // ilk istekte offset ""
  const page = items.slice(start, start + PAGE_SIZE);
  const more = start + PAGE_SIZE < items.length;
  await call("answerInlineQuery", {
    inline_query_id: query.id, results: page,
    next_offset: more ? String(start + PAGE_SIZE) : "", // "" = başka sonuç yok
  });
}

chosen_inline_result ve inline geri bildirim

Geri bildirim açıksa bot result_id, from, query, isteğe bağlı location ve isteğe bağlı inline_message_id içeren bir ChosenInlineResult nesnesi alır. Önbellek nedeniyle popüler botlar gerçek sorgulardan daha fazla seçim bildirimi alabilir; yük yüksekse bunların yalnızca 1/10, 1/100 veya 1/1000'ini alın.

inline_message_id yalnızca gönderilen mesajda inline klavye varsa gelir. Mesajı sonradan editMessageText ile düzenlemek için saklayın (chat_id ve message_id yerine inline_message_id verin); bu mesajdaki buton basışları da aynı inline_message_id ile callback_query olarak gelir.

Sonuç butonu ve sohbete geri dönüş

button parametresi sonuçların üstünde (veya onların yerine) bir InlineQueryResultsButton gösterir. Bir text değeri ve aşağıdakilerden tam olarak biri olmalıdır:

Tipik kullanım: kullanıcıdan önce hesabını bağlamasını isteyin, ardından switch_inline_query (kullanıcı sohbet seçer), switch_inline_query_current_chat (mevcut sohbete @your_bot sorgu ekler) veya switch_inline_query_chosen_chat (seçimi kullanıcılar, botlar, gruplar ya da kanallarla sınırlar) içeren bir inline klavye butonu gönderin.

Sorun giderme

BelirtiOlası neden ve çözüm
@your_bot yazınca hiçbir şey olmuyorInline mod açık değil: /setinline veya setMySettings kullanın.
inline_query güncellemesi gelmiyorDaha önce inline_query olmadan allowed_updates ayarlanmış (liste hatırlanır) ya da webhook kurulu ve getUpdates 409 Conflict döndürüyor.
Eski sonuçlar görünmeye devam ediyorSunucu tarafı önbellek: cache_time değerini düşürün (varsayılan 300 sn), kullanıcıya özel sonuçlar için is_personal kullanın.
400 Bad Request: query is too old and response timeout expired or query ID is invalidYanıt çok geç ya da yanlış ID ile gönderildi. Hemen yanıt verin, yavaş işleri arka planda yapın.
chosen_inline_result gelmiyorInline geri bildirim kapalı: /setinlinefeedback veya inline_feedback_share_denominator.
Fotoğraf sonuçları görünmüyorphoto_url herkese açık, en fazla 5 MB bir JPEG olmalı; thumbnail_url zorunludur.

Yoğun inline botlar Telegram Bot API limitlerine de dikkat etmelidir.

Sık sorulan sorular

Telegram botunda inline mod nasıl açılır?

@BotFather'a /setinline gönderin, botu seçin ve placeholder metnini yazın. Bot API 10.5'ten beri bot bunu kendisi de yapabilir: setMySettings ile supports_inline_queries: true (isteğe bağlı olarak inline_query_placeholder).

answerInlineQuery en fazla kaç sonuç döndürebilir?

Çağrı başına en fazla 50 sonuç. Daha uzun listelerde bir sayfa döndürüp next_offset (en fazla 64 bayt) verin; kullanıcı aşağı kaydırdığında istemci bu değeri offset alanında geri gönderir.

Kodu değiştirdim, inline sonuçlar neden değişmiyor?

Sonuçlar Telegram sunucularında cache_time saniye (varsayılan 300) önbelleğe alınabilir. Geliştirme sırasında küçük bir cache_time kullanın; sonuçlar kullanıcıya göre değişiyorsa is_personal: true verin.

Inline botun sohbete eklenmesi gerekir mi?

Hayır. Kullanıcı herhangi bir sohbette giriş alanına botun kullanıcı adını ve sorguyu yazar; bot inline_query güncellemesi alır, seçilen sonucu ise kullanıcı gönderir ve mesaj botun kullanıcı adıyla (via_bot) işaretlenir.

Kullanıcının hangi inline sonucu gönderdiğini nasıl öğrenirim?

@BotFather'da /setinlinefeedback ile veya setMySettings'te inline_feedback_share_denominator (1, 10, 100 ya da 1000) ile inline geri bildirimi açın. Bot bundan sonra result_id ve query içeren chosen_inline_result güncellemeleri alır.

chosen_inline_result içinde inline_message_id neden yok?

Bu alan yalnızca gönderilen mesajda inline klavye varsa gelir. Mesajı sonradan düzenlemek veya ondan callback query almak istiyorsanız sonuca reply_markup ekleyin.

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 10.0–10.5: bot ayarları, widget'lar, rich mesajlar, ephemeral mesajlar, misafir modu ve dahası

Telegram Bot API 10.0–10.5'teki yenilikler: setMySettings ve BotFullInfo, HTML widget'lar, rich ve ephemeral mesajlar, misafir modu; JSON örnekleriyle.

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 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.