Rich integration
Integration
With the SDK it's three lines: declare formats on inject(). Use the HTTP rich-delivery guide for ephemeral messages in groups.
bot.ts
// Use in place of the ordinary handler; bot and sk are initialized.bot.use(sk.callbacks({onError: () => console.error("Ad interaction failed"),}));bot.on("message:text", async (ctx) => {if (ctx.chat.type !== "private") return;const reply = await getLlmResponse(ctx.message.text); // Return plain text.const result = await sk.inject({userId: ctx.from.id,message: reply,languageCode: ctx.from.language_code || "en",acceptFormats: ["text", "response", "card", "consent", "quiz"],capabilities: {richMessages: true,callbacks: true,customEmoji: false,},});if (result.send) {await ctx.reply(reply);// If rich delivery fails, send only the ad as text.const adOnly = {...result,message: "Ad\n" + (result.ad?.text ?? ""),};const raw = ctx.api.raw as unknown as Record<string, (params: Record<string, unknown>) => Promise<unknown>>;const delivered = await sk.send((method, params) => raw[method](params),ctx.chat.id,adOnly,);if (delivered === null) {console.error("Ad delivery failed");}} else {await ctx.reply(result.message, {reply_markup: result.keyboard ?? undefined,});}});
Client requirements
- •Rich blocks render on Telegram clients released 25.08.2026 or later. Older clients degrade softly: some blocks disappear, but the text and the classic
reply_markupCTA button (always duplicated by the server) stay visible. - •Custom-emoji brand logos render only when your bot owner has Telegram Premium — declare
capabilities.custom_emojiaccordingly. Without it the logo degrades to a bold brand name. - •Groups: interactive scenes after a tap are always delivered ephemerally (visible only to the tapping user). Scene 1 itself is ephemeral only when your bot is a chat admin (
bot_is_admin: true); otherwise it's a regular message — Telegram allows unprompted ephemeral sends to admin bots only.