Transport Fetch API reference

Runtime backstop for the compile-time {@link MediaGroupItems} tuple: a value that reaches `sendMediaGroup` via a cast or an `unknown`-typed JSON decode is length-checked here. Returns a `badRequest` `DeliveryResult` when out of the 2-10 range, or `null` when the size is valid.

albumSizeError(items: readonly MediaGroupItem[]): DeliveryResult<never> | null

Build a {@link BotClient} bound to a token + `fetch`.

createBotClient(config: BotClientConfig): BotClient

Map the success value of a {@link DeliveryResult} while preserving every error variant unchanged. Used to adapt one method's result type to another (e.g. an `EditMessageResult` down to a `TelegramMessage`) without a cast and without dropping the typed-error branches.

<A, B>(result: DeliveryResult<A>, transform: (value: A) => B): DeliveryResult<B>

Project a whole rendered entity list to wire objects.

toWireEntities(entities: readonly MessageEntity[]): readonly WireEntity[]

Project one rendered {@link MessageEntity} to its Bot API wire object.

toWireEntity(entity: MessageEntity): WireEntity

Brand a raw string as an {@link InlineMessageId}.

toInlineMessageId(value: string): InlineMessageId

Brand a raw seconds number as a {@link RetryAfter}. Called only on a value already zod-parsed from the wire `parameters.retry_after` field.

toRetryAfter(seconds: number): RetryAfter

Construct a {@link LiveMessage} over an injected {@link LiveMessagePort}. Uses the ambient `setTimeout`/`clearTimeout`/`Date.now` (mockable by fake timers in tests); it never sleeps on a 429.

createLiveMessage(port: LiveMessagePort, options: LiveMessageOptions): LiveMessage

The single, tested predicate for Telegram's "message is not modified" reply. There is no dedicated error code, so this matches the `description` wording (isolated here so a future Bot API rewording is a one-line fix).

isMessageNotModified(result: DeliveryResult<unknown>): boolean

THE wire boundary: read a `Response`'s JSON, `safeParse` the Bot API envelope, then `safeParse` the success `result` against `dataSchema`. A `res.json()` rejection becomes `networkError`; an unrecognized 200 body becomes `serverError`; an `ok: false` body maps to its typed error variant. Never throws, never returns unparsed data.

<T>(res: Response, dataSchema: WireSchema<T>): Promise<DeliveryResult<T>>

The `fetch` implementation a client calls — global `fetch` by default.

type FetchLike = { (input: RequestInfo | URL, init?: RequestInit): Promise<Response>; (input: string | URL | Request, init?: RequestInit): Promise<Response>; }

A 2-to-10-item album, enforced at COMPILE TIME by an explicit tuple-length union: 0/1 items and 11+ items fail to type-check (spec `bot-api-transport`, "Album size out of range is a compile-time error"). A runtime guard in `sendMediaGroup` backstops values that arrive via a cast.

type MediaGroupItems = | readonly [MediaGroupItem, MediaGroupItem]
  | readonly [MediaGroupItem, MediaGroupItem, MediaGroupItem]
  | readonly [MediaGroupItem, MediaGroupItem, MediaGroupItem, MediaGroupItem]
  | readonly [MediaGroupItem, MediaGroupItem, MediaGroupItem, MediaGroupItem, MediaGroupItem]
  | readonly [
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
    ]
  | readonly [
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
    ]
  | readonly [
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
    ]
  | readonly [
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
    ]
  | readonly [
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
      MediaGroupItem,
    ]

How a media item's file is referenced (no raw multipart upload here).

type MediaSource = | { readonly kind: "fileId"; readonly fileId: string }
  | { readonly kind: "url"; readonly url: string }

The inline result passed to `answerWebAppQuery`.

type WebAppInlineResult = WebAppInlineResultArticle

Outcome of a single Bot API call. `ok` carries the method's parsed result; every other variant is a typed, non-throwing failure.

type DeliveryResult = DeliveryResult<T>

A Bot API `MessageEntity` object as it appears on the wire.

type WireEntity = {
  readonly type: string;
  readonly offset: number;
  readonly length: number;
  readonly url?: string;
  readonly language?: string;
  readonly user?: { readonly id: number };
}

The opaque id of an inline message (from an inline query / web-app result).

type InlineMessageId = Brand<string, "InlineMessageId">

Seconds a caller must wait before retrying, from a 429 `retry_after`.

type RetryAfter = Brand<number, "RetryAfter">

Which message an `editMessageText` targets.

type EditTarget = | { readonly kind: "chatMessage"; readonly chatId: ChatId; readonly messageId: MessageId }
  | { readonly kind: "inlineMessage"; readonly inlineMessageId: InlineMessageId }

Presence of a value, modeled as a DU rather than `T | undefined`.

type KnownOrUnknown = KnownOrUnknown<T>

Result of an `editMessageText` call. A chat-message edit returns the updated `Message`; an inline-message edit returns the wire literal `true` (there is no message object) — modeled as an explicit DU, never `Message | undefined`.

type EditMessageResult = | { readonly kind: "edited"; readonly message: TelegramMessage }
  | { readonly kind: "inlineEdited" }

Arguments for `answerCallbackQuery`.

interface AnswerCallbackQueryArgs

callbackQueryId: string

text: string

showAlert: boolean

Arguments for `answerWebAppQuery`.

interface AnswerWebAppQueryArgs

webAppQueryId: string

result: WebAppInlineResultArticle

The raw Bot API client surface.

interface BotClient

sendMessage(args: SendMessageArgs): Promise<DeliveryResult<TelegramMessage>>

sendPhoto(args: SendPhotoArgs): Promise<DeliveryResult<TelegramMessage>>

editMessageText(args: EditMessageTextArgs): Promise<DeliveryResult<EditMessageResult>>

sendMediaGroup(args: SendMediaGroupArgs): Promise<DeliveryResult<readonly TelegramMessage[]>>

answerCallbackQuery(args: AnswerCallbackQueryArgs): Promise<DeliveryResult<true>>

answerWebAppQuery(args: AnswerWebAppQueryArgs): Promise<DeliveryResult<SentWebAppMessage>>

liveMessage(args: LiveMessageArgs): LiveMessage

Configuration for {@link createBotClient}.

interface BotClientConfig

token: string

fetch: { (input: RequestInfo | URL, init?: RequestInit): Promise<Response>; (input: string | URL | Request, init?: RequestInit): Promise<Response>; }

baseUrl: string

Arguments for `editMessageText` (chat-message or inline-message target).

interface EditMessageTextArgs

target: EditTarget

message: MessageText

replyMarkup: InlineKeyboardMarkup

Arguments for {@link BotClient.liveMessage}.

interface LiveMessageArgs

chatId: ChatId

minEditIntervalMs: number

A single album item. Its caption presence is a DU, never `undefined`.

interface MediaGroupItem

type: "photo" | "video" | "document" | "audio"

source: MediaSource

caption: { readonly kind: "known"; readonly value: CaptionText; } | { readonly kind: "unknown"; }

Arguments for `sendMediaGroup`.

interface SendMediaGroupArgs

chatId: ChatId

items: MediaGroupItems

Arguments for `sendMessage`.

interface SendMessageArgs

chatId: ChatId

message: MessageText

replyMarkup: InlineKeyboardMarkup

Arguments for `sendPhoto` — a single photo (by `file_id` or public URL) with an optional {@link CaptionText}. Telegram fetches a `url` photo itself, so it must be a publicly reachable absolute URL (not a relative path).

interface SendPhotoArgs

chatId: ChatId

photo: MediaSource

caption: CaptionText

replyMarkup: InlineKeyboardMarkup

The `answerWebAppQuery` inline-result subset this change ships (design Open Question, resolved): only an `article` result whose body is a rendered `MessageText` — the shape the mini-app "send to a chat" composer flow needs. Photo/video/other `InlineQueryResult` variants are added when `miniapp` lands as new DU members (non-breaking).

interface WebAppInlineResultArticle

kind: "article"

id: string

title: string

message: MessageText

A live-progress message handle.

interface LiveMessage

update(text: string): void

flush(): Promise<DeliveryResult<TelegramMessage>>

finish(finalText: string): Promise<DeliveryResult<TelegramMessage>>

Options for {@link createLiveMessage}.

interface LiveMessageOptions

minEditIntervalMs: number

The transport seam `LiveMessage` drives: a `send` that establishes the target message and an `edit` that updates it, both returning a {@link DeliveryResult}. `transport-fetch` and `transport-grammy` each supply their own implementation.

interface LiveMessagePort

send(text: string): Promise<DeliveryResult<TelegramMessage>>

edit(target: EditTarget, text: string): Promise<DeliveryResult<TelegramMessage>>

The confirmation returned by `answerWebAppQuery`: a `SentWebAppMessage` whose `inline_message_id` is present only when the message can later be edited.

interface SentWebAppMessage

inlineMessageId: { readonly kind: "known"; readonly value: string; } | { readonly kind: "unknown"; }

A Telegram `Message`, projected to the branded ids the transport exposes.

interface TelegramMessage

messageId: MessageId

chatId: ChatId

date: number

{@link EditMessageResult} response schema.

const EditMessageResultSchema: WireSchema<EditMessageResult>

{@link SentWebAppMessage} response schema.

const SentWebAppMessageSchema: WireSchema<SentWebAppMessage>

An array of {@link TelegramMessage}s, as `sendMediaGroup` returns.

const TelegramMessageArraySchema: WireSchema<readonly TelegramMessage[]>

{@link TelegramMessage} response schema.

const TelegramMessageSchema: WireSchema<TelegramMessage>

The `answerCallbackQuery` result — the Bot API returns the literal `true`.

const TrueResultSchema: WireSchema<true>