import * as grammy from "grammy";

import { type ApiClientOptions, Bot, HttpError } from "grammy";

import type { ReactionType, ReactionTypeEmoji } from "grammy/types";

import { recordChannelActivity } from "openclaw/plugin-sdk/channel-activity-runtime";

import { isDiagnosticFlagEnabled } from "openclaw/plugin-sdk/diagnostic-runtime";

import { formatUncaughtError } from "openclaw/plugin-sdk/error-runtime";

import { redactSensitiveText } from "openclaw/plugin-sdk/logging-core";

import { createTelegramRetryRunner, type RetryConfig } from "openclaw/plugin-sdk/retry-runtime";

import { createSubsystemLogger, logVerbose } from "openclaw/plugin-sdk/runtime-env";

import { formatErrorMessage } from "openclaw/plugin-sdk/ssrf-runtime";

import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";

import { getOrCreateAccountThrottler } from "./account-throttler.js";

import { type ResolvedTelegramAccount, resolveTelegramAccount } from "./accounts.js";

import { withTelegramApiErrorLogging } from "./api-logging.js";

import { normalizeTelegramApiRoot } from "./api-root.js";

import { buildTypingThreadParams } from "./bot/helpers.js";

import type { TelegramInlineButtons } from "./button-types.js";

import { splitTelegramCaption } from "./caption.js";

import { asTelegramClientFetch, createTelegramClientFetch } from "./client-fetch.js";

import { resolveTelegramTransport } from "./fetch.js";

import {

renderTelegramHtmlText,

splitTelegramHtmlChunks,

telegramHtmlToPlainTextFallback,

} from "./format.js";

import { buildInlineKeyboard } from "./inline-keyboard.js";

import {

isRecoverableTelegramNetworkError,

isSafeToRetrySendError,

isTelegramRateLimitError,

isTelegramServerError,

} from "./network-errors.js";

import { makeProxyFetch } from "./proxy.js";

import {

buildTelegramThreadReplyParams,

resolveTelegramSendThreadSpec,

} from "./reply-parameters.js";

import {

buildOutboundMediaLoadOptions,

getImageMetadata,

isGifMedia,

kindFromMime,

loadWebMedia,

type MediaKind,

normalizePollInput,

probeVideoDimensions,

type OpenClawConfig,

type PollInput,

requireRuntimeConfig,

resolveMarkdownTableMode,

} from "./send.runtime.js";

import { recordSentMessage } from "./sent-message-cache.js";

import { maybePersistResolvedTelegramTarget } from "./target-writeback.js";

import {

normalizeTelegramChatId,

normalizeTelegramLookupTarget,

parseTelegramTarget,

} from "./targets.js";

import { resolveTelegramVoiceSend } from "./voice.js";

export { buildInlineKeyboard } from "./inline-keyboard.js";

type TelegramApi = Bot["api"];

export type TelegramApiOverride = Partial<TelegramApi>;

type TelegramSendMessageParams = Parameters<TelegramApi["sendMessage"]>[2];

type TelegramSendPollParams = Parameters<TelegramApi["sendPoll"]>[3];

type TelegramEditMessageTextParams = Parameters<TelegramApi["editMessageText"]>[3];

type TelegramCreateForumTopicParams = NonNullable<Parameters<TelegramApi["createForumTopic"]>[2]>;

type TelegramThreadScopedParams = {

message_thread_id?: number;

};

const InputFileCtor = grammy.InputFile;

const MAX_TELEGRAM_PHOTO_DIMENSION_SUM = 10_000;

const MAX_TELEGRAM_PHOTO_ASPECT_RATIO = 20;

type TelegramSendOpts = {

cfg: OpenClawConfig;

token?: string;

accountId?: string;

verbose?: boolean;

mediaUrl?: string;

mediaLocalRoots?: readonly string[];

mediaReadFile?: (filePath: string) => Promise<Buffer>;

gatewayClientScopes?: readonly string[];

maxBytes?: number;

api?: TelegramApiOverride;

retry?: RetryConfig;

textMode?: "markdown" | "html";

plainText?: string;

/** Send audio as voice message instead of audio file. Defaults to false. */

asVoice?: boolean;

/** Send video as video note instead of regular video. Defaults to false. */

asVideoNote?: boolean;

/** Send message silently (no notification). Defaults to false. */

silent?: boolean;

/** Message ID to reply to (for threading) */

replyToMessageId?: number;

/** Quote text for Telegram reply_parameters. */

quoteText?: string;

/** Forum topic thread ID (for forum supergroups) */

messageThreadId?: number;

/** Inline keyboard buttons (reply markup). */

buttons?: TelegramInlineButtons;

/** Send image as document to avoid Telegram compression. Defaults to false. */

forceDocument?: boolean;

};

type TelegramSendResult = {

messageId: string;

chatId: string;

};

type TelegramMessageLike = {

message_id?: number;

chat?: { id?: string | number };

};

type TelegramOutboundSuccessLogParams = {

accountId: string;

chatId: string;

messageId: string;

operation: string;

deliveryKind?: string;

messageThreadId?: number;

replyToMessageId?: number;

silent?: boolean;

chunkCount?: number;

};

type TelegramReactionOpts = {

cfg: OpenClawConfig;

token?: string;

accountId?: string;

api?: TelegramApiOverride;

remove?: boolean;

verbose?: boolean;

retry?: RetryConfig;

gatewayClientScopes?: readonly string[];

};

type TelegramTypingOpts = {

cfg: OpenClawConfig;

token?: string;

accountId?: string;

verbose?: boolean;

api?: TelegramApiOverride;

retry?: RetryConfig;

messageThreadId?: number;

};

function resolveTelegramMessageIdOrThrow(

result: TelegramMessageLike | null | undefined,

context: string,

): number {

if (typeof result?.message_id === "number" && Number.isFinite(result.message_id)) {

return Math.trunc(result.message_id);

}

throw new Error(`Telegram ${context} returned no message_id`);

}

function splitTelegramPlainTextChunks(text: string, limit: number): string[] {

if (!text) {

return [];

}

const normalizedLimit = Math.max(1, Math.floor(limit));

const chunks: string[] = [];

for (let start = 0; start < text.length; start += normalizedLimit) {

chunks.push(text.slice(start, start + normalizedLimit));

}

return chunks;

}

function splitTelegramPlainTextFallback(text: string, chunkCount: number, limit: number): string[] {

if (!text) {

return [];

}

const normalizedLimit = Math.max(1, Math.floor(limit));

const fixedChunks = splitTelegramPlainTextChunks(text, normalizedLimit);

if (chunkCount <= 1 || fixedChunks.length >= chunkCount) {

return fixedChunks;

}

const chunks: string[] = [];

let offset = 0;

for (let index = 0; index < chunkCount; index += 1) {

const remainingChars = text.length - offset;

const remainingChunks = chunkCount - index;

const nextChunkLength =

remainingChunks === 1

? remainingChars

: Math.min(normalizedLimit, Math.ceil(remainingChars / remainingChunks));

chunks.push(text.slice(offset, offset + nextChunkLength));

offset += nextChunkLength;

}

return chunks;

}

function logTelegramOutboundSendOk(params: TelegramOutboundSuccessLogParams): void {

const parts = [

"telegram outbound send ok",

`accountId=${params.accountId}`,

`chatId=${params.chatId}`,

`messageId=${params.messageId}`,

`operation=${params.operation}`,

];

if (params.deliveryKind) {

parts.push(`deliveryKind=${params.deliveryKind}`);

}

if (typeof params.messageThreadId === "number") {

parts.push(`threadId=${params.messageThreadId}`);

}

if (typeof params.replyToMessageId === "number") {

parts.push(`replyToMessageId=${params.replyToMessageId}`);

}

if (params.silent === true) {

parts.push("silent=true");

}

if (typeof params.chunkCount === "number") {

parts.push(`chunkCount=${params.chunkCount}`);

}

sendLogger.info(parts.join(" "));

}

const PARSE_ERR_RE = /can't parse entities|parse entities|find end of the entity/i;

const THREAD_NOT_FOUND_RE = /400:\s*Bad Request:\s*message thread not found/i;

const MESSAGE_NOT_MODIFIED_RE =

/400:\s*Bad Request:\s*message is not modified|MESSAGE_NOT_MODIFIED/i;

const MESSAGE_DELETE_NOOP_RE =

/message to delete not found|message can't be deleted|MESSAGE_ID_INVALID|MESSAGE_DELETE_FORBIDDEN/i;

const CHAT_NOT_FOUND_RE = /400: Bad Request: chat not found/i;

const sendLogger = createSubsystemLogger("telegram/send");

const diagLogger = createSubsystemLogger("telegram/diagnostic");

const telegramClientOptionsCache = new Map<string, ApiClientOptions | undefined>();

const MAX_TELEGRAM_CLIENT_OPTIONS_CACHE_SIZE = 64;

export function resetTelegramClientOptionsCacheForTests(): void {

telegramClientOptionsCache.clear();

}

function createTelegramHttpLogger(cfg: OpenClawConfig) {

const enabled = isDiagnosticFlagEnabled("telegram.http", cfg);

if (!enabled) {

return () => {};

}

return (label: string, err: unknown) => {

if (!(err instanceof HttpError)) {

return;

}

const detail = redactSensitiveText(formatUncaughtError(err.error ?? err));

diagLogger.warn(`telegram http error (${label}): ${detail}`);

};

}

function shouldUseTelegramClientOptionsCache(): boolean {

return !process.env.VITEST && process.env.NODE_ENV !== "test";

}

function buildTelegramClientOptionsCacheKey(params: {

account: ResolvedTelegramAccount;

timeoutSeconds?: number;

}): string {

const proxyKey = params.account.config.proxy?.trim() ?? "";

const autoSelectFamily = params.account.config.network?.autoSelectFamily;

const autoSelectFamilyKey =

typeof autoSelectFamily === "boolean" ? String(autoSelectFamily) : "default";

const dnsResultOrderKey = params.account.config.network?.dnsResultOrder ?? "default";

const apiRootKey = params.account.config.apiRoot?.trim() ?? "";

const timeoutSecondsKey =

typeof params.timeoutSeconds === "number" ? String(params.timeoutSeconds) : "default";

return `${params.account.accountId}::${proxyKey}::${autoSelectFamilyKey}::${dnsResultOrderKey}::${apiRootKey}::${timeoutSecondsKey}`;

}

function setCachedTelegramClientOptions(

cacheKey: string,

clientOptions: ApiClientOptions | undefined,

): ApiClientOptions | undefined {

telegramClientOptionsCache.set(cacheKey, clientOptions);

if (telegramClientOptionsCache.size > MAX_TELEGRAM_CLIENT_OPTIONS_CACHE_SIZE) {

const oldestKey = telegramClientOptionsCache.keys().next().value;

if (oldestKey !== undefined) {

telegramClientOptionsCache.delete(oldestKey);

}

}

return clientOptions;

}

function resolveTelegramClientOptions(

account: ResolvedTelegramAccount,

): ApiClientOptions | undefined {

const timeoutSeconds =

typeof account.config.timeoutSeconds === "number" &&

Number.isFinite(account.config.timeoutSeconds)

? Math.max(1, Math.floor(account.config.timeoutSeconds))

: undefined;

const cacheEnabled = shouldUseTelegramClientOptionsCache();

const cacheKey = cacheEnabled

? buildTelegramClientOptionsCacheKey({

account,

timeoutSeconds,

})

: null;

if (cacheKey && telegramClientOptionsCache.has(cacheKey)) {

return telegramClientOptionsCache.get(cacheKey);

}

const proxyUrl = normalizeOptionalString(account.config.proxy);

const proxyFetch = proxyUrl ? makeProxyFetch(proxyUrl) : undefined;

const apiRoot = normalizeOptionalString(account.config.apiRoot);

const normalizedApiRoot = apiRoot ? normalizeTelegramApiRoot(apiRoot) : undefined;

const transport = resolveTelegramTransport(proxyFetch, {

network: account.config.network,

});

const fetchImpl = createTelegramClientFetch({

fetchImpl: asTelegramClientFetch(transport.fetch),

timeoutSeconds,

transport,

});

const clientOptions =

fetchImpl || timeoutSeconds || normalizedApiRoot

? {

...(fetchImpl ? { fetch: asTelegramClientFetch(fetchImpl) } : {}),

...(timeoutSeconds ? { timeoutSeconds } : {}),

...(normalizedApiRoot ? { apiRoot: normalizedApiRoot } : {}),

}

: undefined;

if (cacheKey) {

return setCachedTelegramClientOptions(cacheKey, clientOptions);

}

return clientOptions;

}

function resolveToken(explicit: string | undefined, params: { accountId: string; token: string }) {

if (explicit?.trim()) {

return explicit.trim();

}

if (!params.token) {

throw new Error(

`Telegram bot token missing for account "${params.accountId}" (set channels.telegram.accounts.${params.accountId}.botToken/tokenFile or TELEGRAM_BOT_TOKEN for default).`,

);

}

return params.token.trim();

}

async function resolveChatId(

to: string,

params: { api: TelegramApiOverride; verbose?: boolean },

): Promise<string> {

const numericChatId = normalizeTelegramChatId(to);

if (numericChatId) {

return numericChatId;

}

const lookupTarget = normalizeTelegramLookupTarget(to);

const getChat = params.api.getChat;

if (!lookupTarget || typeof getChat !== "function") {

throw new Error("Telegram recipient must be a numeric chat ID");

}

try {

const chat = await getChat.call(params.api, lookupTarget);

const resolved = normalizeTelegramChatId(String(chat?.id ?? ""));

if (!resolved) {

throw new Error(`resolved chat id is not numeric (${String(chat?.id ?? "")})`);

}

if (params.verbose) {

sendLogger.warn(`telegram recipient ${lookupTarget} resolved to numeric chat id ${resolved}`);

}

return resolved;

} catch (err) {

const detail = formatErrorMessage(err);

throw new Error(

`Telegram recipient ${lookupTarget} could not be resolved to a numeric chat ID (${detail})`,

{ cause: err },

);

}

}

async function resolveAndPersistChatId(params: {

cfg: OpenClawConfig;

api: TelegramApiOverride;

lookupTarget: string;

persistTarget: string;

verbose?: boolean;

gatewayClientScopes?: readonly string[];

}): Promise<string> {

const chatId = await resolveChatId(params.lookupTarget, {

api: params.api,

verbose: params.verbose,

});

await maybePersistResolvedTelegramTarget({

cfg: params.cfg,

rawTarget: params.persistTarget,

resolvedChatId: chatId,

verbose: params.verbose,

gatewayClientScopes: params.gatewayClientScopes,

});

return chatId;

}

function normalizeMessageId(raw: string | number): number {

if (typeof raw === "number" && Number.isFinite(raw)) {

return Math.trunc(raw);

}

if (typeof raw === "string") {

const value = raw.trim();

if (!value) {

throw new Error("Message id is required for Telegram actions");

}

const parsed = Number.parseInt(value, 10);

if (Number.isFinite(parsed)) {

return parsed;

}

}

throw new Error("Message id is required for Telegram actions");

}

function isTelegramThreadNotFoundError(err: unknown): boolean {

return THREAD_NOT_FOUND_RE.test(formatErrorMessage(err));

}

function isTelegramMessageNotModifiedError(err: unknown): boolean {

return MESSAGE_NOT_MODIFIED_RE.test(formatErrorMessage(err));

}

function isTelegramMessageDeleteNoopError(err: unknown): boolean {

return MESSAGE_DELETE_NOOP_RE.test(formatErrorMessage(err));

}

function hasMessageThreadIdParam(params?: TelegramThreadScopedParams): boolean {

if (!params) {

return false;

}

const value = params.message_thread_id;

if (typeof value === "number") {

return Number.isFinite(value);

}

return false;

}

function removeMessageThreadIdParam<TParams extends TelegramThreadScopedParams | undefined>(

params: TParams,

): TParams {

if (!params || !hasMessageThreadIdParam(params)) {

return params;

}

const next = { ...params };

delete next.message_thread_id;

return (Object.keys(next).length > 0 ? next : undefined) as TParams;

}

function isTelegramHtmlParseError(err: unknown): boolean {

return PARSE_ERR_RE.test(formatErrorMessage(err));

}

async function withTelegramHtmlParseFallback<T>(params: {

label: string;

verbose?: boolean;

requestHtml: (label: string) => Promise<T>;

requestPlain: (label: string) => Promise<T>;

}): Promise<T> {

try {

return await params.requestHtml(params.label);

} catch (err) {

if (!isTelegramHtmlParseError(err)) {

throw err;

}

if (params.verbose) {

sendLogger.warn(

`telegram ${params.label} failed with HTML parse error, retrying as plain text: ${formatErrorMessage(

err,

)}`,

);

}

return await params.requestPlain(`${params.label}-plain`);

}

}

type TelegramApiContext = {

cfg: OpenClawConfig;

account: ResolvedTelegramAccount;

api: TelegramApi;

};

function resolveTelegramApiContext(opts: {

token?: string;

accountId?: string;

api?: TelegramApiOverride;

cfg: OpenClawConfig;

}): TelegramApiContext {

const cfg = requireRuntimeConfig(opts.cfg, "Telegram API context");

const account = resolveTelegramAccount({

cfg,

accountId: opts.accountId,

});

const token = resolveToken(opts.token, account);

const client = resolveTelegramClientOptions(account);

let api: TelegramApi;

if (opts.api) {

api = opts.api as TelegramApi;

} else {

const bot = new Bot(token, client ? { client } : undefined);

bot.api.config.use(getOrCreateAccountThrottler(token));

api = bot.api;

}

return { cfg, account, api };

}

type TelegramRequestWithDiag = <T>(

fn: () => Promise<T>,

label?: string,

options?: { shouldLog?: (err: unknown) => boolean },

) => Promise<T>;

function createTelegramRequestWithDiag(params: {

cfg: OpenClawConfig;

account: ResolvedTelegramAccount;

retry?: RetryConfig;

verbose?: boolean;

shouldRetry?: (err: unknown) => boolean;

/** When true, the shouldRetry predicate is used exclusively without the TELEGRAM_RETRY_RE fallback. */

strictShouldRetry?: boolean;

useApiErrorLogging?: boolean;

}): TelegramRequestWithDiag {

const request = createTelegramRetryRunner({

retry: params.retry,

configRetry: params.account.config.retry,

verbose: params.verbose,

...(params.shouldRetry ? { shouldRetry: params.shouldRetry } : {}),

...(params.strictShouldRetry ? { strictShouldRetry: true } : {}),

});

const logHttpError = createTelegramHttpLogger(params.cfg);

return <T>(

fn: () => Promise<T>,

label?: string,

options?: { shouldLog?: (err: unknown) => boolean },

) => {

const runRequest = () => request(fn, label);

const call =

params.useApiErrorLogging === false

? runRequest()

: withTelegramApiErrorLogging({

operation: label ?? "request",

fn: runRequest,

...(options?.shouldLog ? { shouldLog: options.shouldLog } : {}),

});

return call.catch((err) => {

logHttpError(label ?? "request", err);

throw err;

});

};

}

function wrapTelegramChatNotFoundError(err: unknown, params: { chatId: string; input: string }) {

const errorMsg = formatErrorMessage(err);

// Check for 403 "bot is not a member" or "bot was blocked" errors

if (/403.*(bot.*not.*member|bot.*blocked|bot.*kicked)/i.test(errorMsg)) {

return new Error(

[

`Telegram send failed: bot is not a member of the chat, was blocked, or was kicked (chat_id=${params.chatId}).`,

`Telegram API said: ${errorMsg}.`,

"Fix: Add the bot to the channel/group, or ensure it has not been removed/blocked/kicked by the user.",

`Input was: ${JSON.stringify(params.input)}.`,

].join(" "),

);

}

if (!CHAT_NOT_FOUND_RE.test(errorMsg)) {

return err;

}

return new Error(

[

`Telegram send failed: chat not found (chat_id=${params.chatId}).`,

"Likely: bot not started in DM, bot removed from group/channel, group migrated (new -100… id), or wrong bot token.",

`Input was: ${JSON.stringify(params.input)}.`,

].join(" "),

);

}

async function withTelegramThreadFallback<

T,

TParams extends TelegramThreadScopedParams | undefined,

>(

params: TParams,

label: string,

verbose: boolean | undefined,

allowThreadlessRetry: boolean,

attempt: (effectiveParams: TParams, effectiveLabel: string) => Promise<T>,

): Promise<T> {

try {

return await attempt(params, label);

} catch (err) {

// Do not widen this fallback to cover "chat not found".

// chat-not-found is routing/auth/membership/token; stripping thread IDs hides root cause.

if (

!allowThreadlessRetry ||

!hasMessageThreadIdParam(params) ||

!isTelegramThreadNotFoundError(err)

) {

throw err;

}

if (verbose) {

sendLogger.warn(

`telegram ${label} failed with message_thread_id, retrying without thread: ${formatErrorMessage(err)}`,

);

}

const retriedParams = removeMessageThreadIdParam(params);

return await attempt(retriedParams, `${label}-threadless`);

}

}

function createRequestWithChatNotFound(params: {

requestWithDiag: TelegramRequestWithDiag;

chatId: string;

input: string;

}) {

return async <T>(fn: () => Promise<T>, label: string) =>

params.requestWithDiag(fn, label).catch((err) => {

throw wrapTelegramChatNotFoundError(err, {

chatId: params.chatId,

input: params.input,

});

});

}

function createTelegramNonIdempotentRequestWithDiag(params: {

cfg: OpenClawConfig;

account: ResolvedTelegramAccount;

retry?: RetryConfig;

verbose?: boolean;

useApiErrorLogging?: boolean;

}): TelegramRequestWithDiag {

return createTelegramRequestWithDiag({

cfg: params.cfg,

account: params.account,

retry: params.retry,

verbose: params.verbose,

useApiErrorLogging: params.useApiErrorLogging,

shouldRetry: (err) => isSafeToRetrySendError(err) || isTelegramRateLimitError(err),

strictShouldRetry: true,

});

}

export async function sendMessageTelegram(

to: string,

text: string,

opts: TelegramSendOpts,

): Promise<TelegramSendResult> {

const { cfg, account, api } = resolveTelegramApiContext(opts);

const target = parseTelegramTarget(to);

const chatId = await resolveAndPersistChatId({

cfg,

api,

lookupTarget: target.chatId,

persistTarget: to,

verbose: opts.verbose,

gatewayClientScopes: opts.gatewayClientScopes,

});

const mediaUrl = opts.mediaUrl?.trim();

const mediaMaxBytes =

opts.maxBytes ??

(typeof account.config.mediaMaxMb === "number" ? account.config.mediaMaxMb : 100) * 1024 * 1024;

const replyMarkup = buildInlineKeyboard(opts.buttons);

const threadParams = buildTelegramThreadReplyParams({

thread: resolveTelegramSendThreadSpec({

targetMessageThreadId: target.messageThreadId,

messageThreadId: opts.messageThreadId,

chatType: target.chatType,

}),

replyToMessageId: opts.replyToMessageId,

replyQuoteText: opts.quoteText,

useReplyIdAsQuoteSource: true,

});

const hasThreadParams = Object.keys(threadParams).length > 0;

const requestWithDiag = createTelegramNonIdempotentRequestWithDiag({

cfg,

account,

retry: opts.retry,

verbose: opts.verbose,

});

const requestWithChatNotFound = createRequestWithChatNotFound({

requestWithDiag,

chatId,

input: to,

});

const textMode = opts.textMode ?? "markdown";

const tableMode = resolveMarkdownTableMode({

cfg,

channel: "telegram",

accountId: account.accountId,

});

const renderHtmlText = (value: string) => renderTelegramHtmlText(value, { textMode, tableMode });

// Resolve link preview setting from config (default: enabled).

const linkPreviewEnabled = account.config.linkPreview ?? true;

const linkPreviewOptions = linkPreviewEnabled ? undefined : { is_disabled: true };

type TelegramTextChunk = {

plainText: string;

htmlText?: string;

};

const sendTelegramTextChunk = async (

chunk: TelegramTextChunk,

params?: TelegramSendMessageParams,

) => {

return await withTelegramThreadFallback(

params,

"message",

opts.verbose,

target.chatType !== "direct",

async (effectiveParams, label) => {

const baseParams = effectiveParams ? { ...effectiveParams } : {};

if (linkPreviewOptions) {

baseParams.link_preview_options = linkPreviewOptions;

}

const plainParams: TelegramSendMessageParams = {

...baseParams,

...(opts.silent === true ? { disable_notification: true } : {}),

};

const hasPlainParams = Object.keys(plainParams).length > 0;

const requestPlain = (retryLabel: string) =>

requestWithChatNotFound(

() =>

hasPlainParams

? api.sendMessage(chatId, chunk.plainText, plainParams)

: api.sendMessage(chatId, chunk.plainText),

retryLabel,

);

if (!chunk.htmlText) {

return await requestPlain(label);

}

const htmlText = chunk.htmlText;

const htmlParams: TelegramSendMessageParams = {

parse_mode: "HTML" as const,

...plainParams,

};

return await withTelegramHtmlParseFallback({

label,

verbose: opts.verbose,

requestHtml: (retryLabel) =>

requestWithChatNotFound(

() => api.sendMessage(chatId, htmlText, htmlParams),

retryLabel,

),

requestPlain,

});

},

);

};

const buildTextParams = (isLastChunk: boolean) =>

hasThreadParams || (isLastChunk && replyMarkup)

? {

...threadParams,

...(isLastChunk && replyMarkup ? { reply_markup: replyMarkup } : {}),

}

: undefined;

const sendTelegramTextChunks = async (

chunks: TelegramTextChunk[],

context: string,

): Promise<{ messageId: string; chatId: string }> => {

let lastMessageId = "";

let lastChatId = chatId;

let sentChunkCount = 0;

for (let index = 0; index < chunks.length; index += 1) {

const chunk = chunks[index];

if (!chunk) {

continue;

}

const res = await sendTelegramTextChunk(chunk, buildTextParams(index === chunks.length - 1));

const messageId = resolveTelegramMessageIdOrThrow(res, context);

recordSentMessage(chatId, messageId, cfg);

lastMessageId = String(messageId);

lastChatId = String(res?.chat?.id ?? chatId);

sentChunkCount += 1;

}

if (lastMessageId) {

logTelegramOutboundSendOk({

accountId: account.accountId,

chatId: lastChatId,

messageId: lastMessageId,

operation: "sendMessage",

deliveryKind: "text",

messageThreadId: threadParams.message_thread_id,

replyToMessageId: opts.replyToMessageId,

silent: opts.silent,

chunkCount: sentChunkCount,

});

}

return { messageId: lastMessageId, chatId: lastChatId };

};

const buildChunkedTextPlan = (rawText: string, context: string): TelegramTextChunk[] => {

const htmlText = renderHtmlText(rawText);

const fallbackText =

opts.plainText ?? (textMode === "html" ? telegramHtmlToPlainTextFallback(htmlText) : rawText);

let htmlChunks: string[];

try {

htmlChunks = splitTelegramHtmlChunks(htmlText, 4000);

} catch (error) {

logVerbose(

`telegram ${context} failed HTML chunk planning, retrying as plain text: ${formatErrorMessage(

error,

)}`,

);

return splitTelegramPlainTextChunks(fallbackText, 4000).map((plainText) => ({ plainText }));

}

const fixedPlainTextChunks = splitTelegramPlainTextChunks(fallbackText, 4000);

if (fixedPlainTextChunks.length > htmlChunks.length) {

logVerbose(

`telegram ${context} plain-text fallback needs more chunks than HTML; sending plain text`,

);

return fixedPlainTextChunks.map((plainText) => ({ plainText }));

}

const plainTextChunks = splitTelegramPlainTextFallback(fallbackText, htmlChunks.length, 4000);

return htmlChunks.map((htmlText, index) => ({

htmlText,

plainText: plainTextChunks[index] ?? htmlText,

}));

};

const sendChunkedText = async (rawText: string, context: string) =>

await sendTelegramTextChunks(buildChunkedTextPlan(rawText, context), context);

async function shouldSendTelegramImageAsPhoto(buffer: Buffer): Promise<boolean> {

try {

const metadata = await getImageMetadata(buffer);

const width = metadata?.width;

const height = metadata?.height;

if (typeof width !== "number" || typeof height !== "number") {

sendLogger.warn("Photo dimensions are unavailable. Sending as document instead.");

return false;

}

const shorterSide = Math.min(width, height);

const longerSide = Math.max(width, height);

const isValidPhoto =

width + height <= MAX_TELEGRAM_PHOTO_DIMENSION_SUM &&

shorterSide > 0 &&

longerSide <= shorterSide * MAX_TELEGRAM_PHOTO_ASPECT_RATIO;

if (!isValidPhoto) {

sendLogger.warn(

`Photo dimensions (${width}x${height}) are not valid for Telegram photos. Sending as document instead.`,

);

return false;

}

return true;

} catch (err) {

sendLogger.warn(

`Failed to validate photo dimensions: ${formatErrorMessage(err)}. Sending as document instead.`,

);

return false;

}

}

if (mediaUrl) {

const media = await loadWebMedia(

mediaUrl,

buildOutboundMediaLoadOptions({

maxBytes: mediaMaxBytes,

mediaLocalRoots: opts.mediaLocalRoots,

mediaReadFile: opts.mediaReadFile,

optimizeImages: opts.forceDocument ? false : undefined,

}),

);

const kind = kindFromMime(media.contentType ?? undefined);

const isGif = isGifMedia({

contentType: media.contentType,

fileName: media.fileName,

});

let sendImageAsPhoto = true;

const deliveryKind =

opts.forceDocument === true && (kind === "image" || kind === "video") ? "document" : kind;

if (deliveryKind === "image" && !isGif) {

sendImageAsPhoto = await shouldSendTelegramImageAsPhoto(media.buffer);

}

const isVideoNote = deliveryKind === "video" && opts.asVideoNote === true;

const fileName =

media.fileName ?? (isGif ? "animation.gif" : inferFilename(kind ?? "document")) ?? "file";

const file = new InputFileCtor(media.buffer, fileName);

let caption: string | undefined;

let followUpText: string | undefined;

if (isVideoNote) {

caption = undefined;

followUpText = text.trim() ? text : undefined;

} else {

const split = splitTelegramCaption(text);

caption = split.caption;

followUpText = split.followUpText;

}

const htmlCaption = caption ? renderHtmlText(caption) : undefined;

// If text exceeds Telegram's caption limit, send media without caption

// then send text as a separate follow-up message.

const needsSeparateText = Boolean(followUpText);

// When splitting, put reply_markup only on the follow-up text (the "main" content),

// not on the media message.

const baseMediaParams = {

...(hasThreadParams ? threadParams : {}),

...(!needsSeparateText && replyMarkup ? { reply_markup: replyMarkup } : {}),

};

const videoDimensions =

deliveryKind === "video" && !isVideoNote

? await probeVideoDimensions(media.buffer)

: undefined;

const mediaParams = {

...(htmlCaption ? { caption: htmlCaption, parse_mode: "HTML" as const } : {}),

...baseMediaParams,

...(opts.silent === true ? { disable_notification: true } : {}),

...(videoDimensions ? { width: videoDimensions.width, height: videoDimensions.height } : {}),

};

const sendMedia = async (

label: string,

sender: (

effectiveParams: TelegramThreadScopedParams | undefined,

) => Promise<TelegramMessageLike>,

) =>

await withTelegramThreadFallback(

mediaParams,

label,

opts.verbose,

target.chatType !== "direct",

async (effectiveParams, retryLabel) =>

requestWithChatNotFound(() => sender(effectiveParams), retryLabel),

);

const mediaSender = (() => {

if (isGif && deliveryKind !== "document") {

return {

label: "animation",

sender: (effectiveParams: TelegramThreadScopedParams | undefined) =>

api.sendAnimation(

chatId,

file,

effectiveParams as Parameters<typeof api.sendAnimation>[2],

) as Promise<TelegramMessageLike>,

};

}

if (deliveryKind === "image" && !isGif && sendImageAsPhoto) {

return {

label: "photo",

sender: (effectiveParams: TelegramThreadScopedParams | undefined) =>

api.sendPhoto(

chatId,

file,

effectiveParams as Parameters<typeof api.sendPhoto>[2],

) as Promise<TelegramMessageLike>,

};

}

if (deliveryKind === "video") {

if (isVideoNote) {

return {

label: "video_note",

sender: (effectiveParams: TelegramThreadScopedParams | undefined) =>

api.sendVideoNote(

chatId,

file,

effectiveParams as Parameters<typeof api.sendVideoNote>[2],

) as Promise<TelegramMessageLike>,

};

}

return {

label: "video",

sender: (effectiveParams: TelegramThreadScopedParams | undefined) =>

api.sendVideo(

chatId,

file,

effectiveParams as Parameters<typeof api.sendVideo>[2],

) as Promise<TelegramMessageLike>,

};

}

if (kind === "audio") {

const { useVoice } = resolveTelegramVoiceSend({

wantsVoice: opts.asVoice === true, // default false (backward compatible)

contentType: media.contentType,

fileName,

logFallback: logVerbose,

});

if (useVoice) {

return {

label: "voice",

sender: (effectiveParams: TelegramThreadScopedParams | undefined) =>

api.sendVoice(

chatId,

file,

effectiveParams as Parameters<typeof api.sendVoice>[2],

) as Promise<TelegramMessageLike>,

};

}

return {

label: "audio",

sender: (effectiveParams: TelegramThreadScopedParams | undefined) =>

api.sendAudio(

chatId,

file,