Telegram机器人内联查询用法详解：从入门到实战

内联查询（Inline Query）是Telegram机器人最强大的交互功能之一。它允许用户在任何聊天窗口中直接输入 @你的机器人关键词，机器人即可实时返回自定义结果，供用户选择并发送。无论是实现搜索工具、快捷回复、还是内容预览，内联查询都能大幅提升机器人的实用性和用户体验。本文将带你从入门到实战，全面掌握Telegram机器人内联查询的用法。

什么是内联查询？

内联查询是一种由用户主动触发的查询模式。用户在聊天输入框中输入机器人用户名及关键词时，Telegram客户端会向机器人发送一个特殊的更新（InlineQuery），机器人需要在限定时间内（通常为10秒）返回一组结果。用户可以选择其中一个结果直接发送到当前聊天，整个过程无需离开聊天窗口。

与普通命令（如 /start）不同，内联查询是上下文相关的，可以在任意会话中使用，非常适合构建“即开即用”的工具型机器人。

内联查询的工作原理

内联查询的完整工作流程如下：

用户输入 @机器人用户名查询词。
Telegram客户端向机器人发送一个 inline_query 更新，包含查询文本、用户ID、聊天类型等信息。
机器人解析查询内容，调用业务逻辑生成结果列表。
机器人通过 answerInlineQuery 方法返回结果（最多50条）。
用户点击某条结果，Telegram将其以消息形式发送到当前聊天。

整个过程是无状态的，机器人不需要记住用户状态，每次查询都是独立的。

如何启用内联模式

要让机器人支持内联查询，必须先在BotFather中启用内联模式。步骤如下：

打开Telegram，找到 @BotFather。
发送 /mybots，选择你的机器人。
点击 Bot Settings，然后选择 Inline Mode。
点击 Turn On，即可开启内联模式。
你还可以通过 /setinlineplaceholder 设置占位提示语，例如“搜索文章或链接”。

启用后，用户即可在内联模式下调用你的机器人。

处理内联查询的代码示例

下面分别使用Python（python-telegram-bot库）和Node.js（node-telegram-bot-api库）演示如何处理内联查询。

Python 示例（python-telegram-bot v20+）

from telegram import InlineQueryResultArticle, InputTextMessageContent, Update
from telegram.ext import Application, InlineQueryHandler, ContextTypes

async def inline_query_handler(update: Update, context: ContextTypes.DEFAULT_TYPE):
    query = update.inline_query.query
    results = []
    if query:
        results.append(InlineQueryResultArticle(
            id="1",
            title="你搜索的是: " + query,
            input_message_content=InputTextMessageContent("你输入了: " + query)
        ))
    else:
        results.append(InlineQueryResultArticle(
            id="2",
            title="请输入关键词",
            input_message_content=InputTextMessageContent("请先输入关键词")
        ))
    await update.inline_query.answer(results, cache_time=1)

def main():
    app = Application.builder().token("YOUR_TOKEN").build()
    app.add_handler(InlineQueryHandler(inline_query_handler))
    app.run_polling()

if __name__ == "__main__":
    main()

Node.js 示例（node-telegram-bot-api）

const TelegramBot = require('node-telegram-bot-api');
const bot = new TelegramBot('YOUR_TOKEN', {polling: true});

bot.on('inline_query', (query) => {
    const text = query.query;
    const results = [];
    if (text) {
        results.push({
            type: 'article',
            id: '1',
            title: '你搜索的是: ' + text,
            input_message_content: {
                message_text: '你输入了: ' + text
            }
        });
    } else {
        results.push({
            type: 'article',
            id: '2',
            title: '请输入关键词',
            input_message_content: {
                message_text: '请先输入关键词'
            }
        });
    }
    bot.answerInlineQuery(query.id, results, {cache_time: 1});
});

以上代码实现了最基础的内联查询响应：用户输入关键词后，机器人返回一个包含该关键词的文字结果。

内联查询结果类型与构造

Telegram支持多种内联查询结果类型，例如：

Article：纯文字消息，支持Markdown或HTML格式。
Photo：返回图片，可附带说明文字。
Video：返回视频。
Gif：返回GIF动画。
Document：返回文件。
Location：返回地理位置。
Venue：返回地点信息。

每种结果都有自己的参数，例如 id、title、input_message_content 等。你可以根据业务需求自由组合，为用户提供丰富的选择。

构造示例：链接搜索结果

假设你要实现一个“按关键词返回相关链接”的内联查询，可以使用 InlineQueryResultArticle 并设置 url 属性（仅用于展示，不会自动跳转），但真正的发送内容由 input_message_content 控制：

results.append(InlineQueryResultArticle(
    id="link_1",
    title="搜索: " + query,
    description="点击发送对应链接",
    input_message_content=InputTextMessageContent(f"你搜索了: \n相关链接: https://example.com/search?q=")
))

实用技巧与避坑建议

在开发内联查询时，以下几点非常重要：

缓存与性能：使用 cache_time 参数控制结果缓存时间（秒），避免频繁处理相同查询。
响应超时：必须在10秒内调用 answerInlineQuery，超时会被忽略，请确保处理逻辑高效。
结果数量：每次最多返回50个结果，超出部分会被截断。
占位符：通过BotFather设置占位提示语，引导用户正确使用。
兜底结果：当用户未输入关键词时，返回一些推荐内容或引导语，避免空结果。
事件上报：用户点击内联查询结果时，机器人会收到 chosen_inline_result 更新，可用于统计用户行为，但需要先在BotFather中开启“Inline Feedback”相关设置。

总结

内联查询是Telegram机器人开发中的高级功能，掌握它能让你的机器人在任意聊天中“即问即答”。本文从原理、配置到代码实现，完整讲解了内联查询的用法。无论你是初学者还是进阶开发者，都可以根据这些示例快速上手。记得在实践中多测试不同结果类型，并结合实际业务场景优化用户体验。现在就去为你的机器人开启内联模式吧！