GramIO

Русский

English

Русский

English

Тема

guestQuery ​

Метод guestQuery обрабатывает гостевые сообщения — фичу из Telegram Bot API 10.0. Гостевое сообщение позволяет пользователю достучаться до бота без обычного чата и приходит как новый апдейт guest_message. GramIO маппит этот апдейт в MessageContext и даёт отдельный метод ответа ctx.answerGuestQuery().

NOTE

bot.guestQuery(...) требует gramio v0.10.0+ (Bot API 10.0). Это аналог inlineQuery для гостевых сообщений — та же форма триггера, другая семантика ответа.

Базовое использование ​

Форма повторяет inlineQuery: триггер (строка, RegExp, предикат или ничего), за которым идёт хендлер. Передай без триггера, чтобы ловить любое гостевое сообщение. Отвечай через context.answerGuestQuery(result) — result это один InlineQueryResult, ровно как элемент массива результатов в answerInlineQuery:

ts
import { InlineQueryResult, InputMessageContent } from "gramio";

// Ловим любое гостевое сообщение
bot.guestQuery(async (context) => {
    await context.answerGuestQuery(
        InlineQueryResult.article(
            "1",
            "Привет!",
            InputMessageContent.text("Привет, гость!"),
        ),
    );
});

Фильтруй по тексту гостевого запроса строкой, RegExp или функцией — захваты попадают в context.args (RegExpMatchArray | null), ровно как у остальных текстовых триггеров:

ts
// RegExp — захваты через context.args
bot.guestQuery(/^order (.+)/i, async (context) => {
    const orderId = context.args![1];
    await context.answerGuestQuery(
        InlineQueryResult.article(
            orderId,
            `Заказ ${orderId}`,
            InputMessageContent.text(`Открываю заказ ${orderId}…`),
        ),
    );
});

// Функция-матчер — возвращает boolean
bot.guestQuery(
    (context) => context.from?.is_premium === true,
    (context) =>
        context.answerGuestQuery(
            InlineQueryResult.article(
                "premium",
                "Премиум",
                InputMessageContent.text("Премиум-опции"),
            ),
        ),
);

Почему он отдельно от command / hears ​

У гостевых сообщений другая семантика ответа, чем у обычных: отвечаешь через ctx.answerGuestQuery(result), а не ctx.send() / ctx.reply(). Оставив guestQuery отдельным триггером (а не подмешав гостевые сообщения в command / hears / startParameter), мы делаем это различие явным и держим обработчики гостевого флоу в одном месте.

Хелперы контекста ​

На контексте гостевого сообщения доступны новые геттеры Bot API 10.0:

Геттер / методОписание
context.guestQueryIdid гостевого запроса, на который нужно ответить
context.guestBotCallerUserпользователь, инициировавший гостевое сообщение
context.guestBotCallerChatчат, из которого пришло гостевое сообщение
context.answerGuestQuery(result, params?)ответить на гостевой запрос. result — один InlineQueryResult (например, InlineQueryResult.article(…))

User.supportsGuestQueries() позволяет проверить, может ли конкретный пользователь принимать гостевые запросы, до старта флоу.

Включаем гостевые запросы ​

guest_message — один из типов апдейтов, которые Telegram доставляет только когда они перечислены в allowed_updates. AllowedUpdatesFilter в GramIO выводит его автоматически, когда ты регистрируешь хендлер guestQuery, так что дефолтный bot.start() опт-инит сам.

Смотрите также ​

  • inlineQuery — аналог для инлайн-режима с такой же формой триггера.
  • chosenInlineResult — обработка того, какой инлайн-результат выбрал пользователь.