Skip to content
Documentation menu
SDKTelegramNode.js SDK

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_markup CTA button (always duplicated by the server) stay visible.
  • •Custom-emoji brand logos render only when your bot owner has Telegram Premium — declare capabilities.custom_emoji accordingly. 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.