Telegram inline bot: inline modu açma ve inline sorguları yanıtlama
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:
- Kullanıcı giriş alanına botun kullanıcı adını ve sorguyu yazar, ör.
@your_bot merhaba. Sohbete henüz bir şey gönderilmez. - Bot bir
inline_querygüncellemesi alır. - Bot,
answerInlineQueryile sonuç listesi döndürür: makaleler, fotoğraflar, GIF'ler, videolar, çıkartmalar, konumlar vb. - 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_botalanı bulunur. - İsteğe bağlı olarak bot, hangi sonucun gönderildiğini bildiren bir
chosen_inline_resultgü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
- @BotFather'a
/setinlinegönderin ve botunuzu seçin. - 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…
- İsteğe bağlı:
/setinlinegeoher sorguyla birlikte kullanıcının konumunu ister;/setinlinefeedbackchosen_inline_resultgü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:
supports_inline_queries—trueinline modu açar,falsekapatır.inline_query_placeholder— placeholder metni; boş metin varsayılanı geri getirir.needs_inline_query_location— her inline sorguda kullanıcının konumunu ister.inline_feedback_share_denominator— seçilen sonuçların N'de 1'ini alırsınız; değer 1, 10, 100 veya 1000 olmalı,0isechosen_inline_resultgüncellemelerini durdurur.
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:
| Alan | Anlamı |
|---|---|
id | Sorgunun benzersiz kimliği; answerInlineQuery'ye inline_query_id olarak verilir |
from | Sorguyu yazan kullanıcı |
query | Sorgu metni, en fazla 256 karakter; boş olabilir — bu durumda varsayılan veya popüler sonuçları döndürün |
offset | Dö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.
| Parametre | Açıklama |
|---|---|
inline_query_id | Zorunlu. Sorgunun id değeri |
results | Zorunlu. InlineQueryResult nesneleri dizisi (≤ 50) |
cache_time | Sonucun sunucuda önbellekte tutulabileceği en uzun süre (saniye); varsayılan 300 |
is_personal | true 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 |
button | Sonuç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:
- article —
titleveinput_message_contentzorunlu;description,url,thumbnail_url,reply_markupisteğe bağlı. İçerik genelliklemessage_text(1–4096 karakter) ve isteğe bağlıparse_modeiçeren birInputTextMessageContentnesnesidir. - photo —
photo_url(JPEG, en fazla 5 MB) vethumbnail_urlzorunlu;caption(0–1024 karakter),title,descriptionisteğe bağlı.
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, "&").replace(/</g, "<").replace(/>/g, ">");
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ç yokconst 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:
start_parameter— botla özel sohbeti açar ve/start <parameter>gönderir; 1–64 karakter, yalnızcaA-Z,a-z,0-9,_ve-.web_app— bir Mini App başlatır; Mini AppswitchInlineQueryile inline moda geri dönebilir.
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
| Belirti | Olası neden ve çözüm |
|---|---|
@your_bot yazınca hiçbir şey olmuyor | Inline mod açık değil: /setinline veya setMySettings kullanın. |
inline_query güncellemesi gelmiyor | Daha ö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 ediyor | Sunucu 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 invalid | Yanıt çok geç ya da yanlış ID ile gönderildi. Hemen yanıt verin, yavaş işleri arka planda yapın. |
chosen_inline_result gelmiyor | Inline geri bildirim kapalı: /setinlinefeedback veya inline_feedback_share_denominator. |
| Fotoğraf sonuçları görünmüyor | photo_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.
İlgili rehberler
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.