Справочник

* Обязательные поля.

Единственный метод, который нужно вызывать. Асинхронный, не выбрасывает исключений: при любой ошибке возвращает исходное сообщение и клавиатуру без изменений.

* Обязательные поля.

Возвращаемое значение

Получает объявление без отправки текста вашего сообщения. Возвращает отдельные поля, из которых вы сами собираете ответ бота. Асинхронный, не выбрасывает исключений: при любой ошибке возвращает { hasAd: false } (или { has_ad: False } в Python).

import { Sidekick } from "sidekick-sdk";

const sk = new Sidekick({ apiKey: "sk_live_xxx", platformId: "plt_xxx" });

const result = await sk.fetch({
  userId: ctx.from.id,
  languageCode: ctx.from.language_code || "en",
  parseMode: "HTML", // Match the parse mode used when sending.
});

if (result.hasAd && result.ad) {
  await ctx.reply(`${llmReply}\n\n${result.ad.adTextFormatted}`, {
    parse_mode: "HTML",
    reply_markup: {
      inline_keyboard: [[
        { text: result.ad.buttonText, url: result.ad.buttonUrl },
      ]],
    },
  });
} else {
  await ctx.reply(llmReply);
}

Параметры

* Обязательные поля.

Возвращаемое значение (FetchAnyResult)

fetch() или inject() — используйте inject() для добавления рекламы в сообщение и объединения клавиатуры средствами SDK. Выберите fetch() если ответы LLM могут содержать пользовательские данные (имена, фрагменты запросов), которые вы не хотите передавать на серверы Sidekick.

Получает рекламу с изображением (фото или анимацией) для отправки отдельно от ответа LLM. Вызывает метод /api/v1/ad/fetch-image . Асинхронный, не выбрасывает исключений: при любой ошибке возвращает { hasAd: false }.

import { Sidekick } from "sidekick-sdk";
import { InputFile } from "grammy";

const sk = new Sidekick({ apiKey: "sk_live_xxxxx", platformId: "plt_xxxxx" });

const r = await sk.fetchImage({
  userId: ctx.from.id,
  languageCode: "en",
  parseMode: "HTML",
});
if (r.hasAd && r.ad) {
  // SDK already downloaded the bytes — hand straight to InputFile.
  const media = new InputFile(r.ad.imageData, r.ad.imageFileName);
  const options = {
    caption: r.ad.adTextFormatted ?? r.ad.adText,
    parse_mode: "HTML" as const,
    reply_markup: {
      inline_keyboard: [[{ text: r.ad.buttonText, url: r.ad.buttonUrl }]],
    },
  };
  if (r.ad.mediaType === "animation") {
    await ctx.replyWithAnimation(media, options);
  } else {
    await ctx.replyWithPhoto(media, options);
  }
}

Параметры

* Обязательные поля.

Возвращаемое значение (FetchImageResult)

inject() не выбрасывает исключений. При любой ошибке — тайм-ауте, сбое сети, 5xx или некорректном JSON — возвращает исходное сообщение и клавиатуру без изменений. Ваш бот продолжает работать.

// On a handled Sidekick request error:
const result = await sk.inject({ userId: 123, message: "Hello world", languageCode: "en" });
// result.message === "Hello world" (unchanged)
// result.hasAd === false
// result.keyboard === null (or your original keyboard)

• •Рекламная кнопка добавляется отдельной строкой и не смешивается с вашими кнопками.
• •Положение задаётся параметром adButtonPosition: "bottom" (по умолчанию) или "top".
• •Telegram допускает не более 13 строк клавиатуры. Если их уже 13, рекламная кнопка не добавляется — остаётся только рекламный текст.
• •Ваши существующие кнопки не изменяются и не удаляются.
• •Если сообщение с рекламой превышает 4096 символов, рекламный текст убирается, но кнопка добавляется.