Telegram Schemas - TundraSoft/tundra-connect GitHub Wiki

Telegram Schemas

The @tundraconnect/telegram/schemas subpath exports Guardian validators and their TypeScript types. Every client method validates its request against the matching request schema before sending it, and validates the unwrapped result against a response schema.

import {
  type SendMessageRequestSchema,
  SendMessageRequestSchemaObject,
} from '@tundraconnect/telegram/schemas';

const payload: unknown = {
  chat_id: '@examplechannel',
  text: 'Hello!',
};

const [error, request] = SendMessageRequestSchemaObject.safeParse(payload);
if (error || !request) throw error;

const typedRequest: SendMessageRequestSchema = request;
console.log(typedRequest.text);

Two rules hold throughout:

  • Request schemas are strict. An unknown key is rejected ("Unknown property 'x' is not allowed in strict mode") instead of being dropped, and booleans and numbers must be real booleans and numbers ('true' and '40' are rejected, not coerced).
  • Response and update schemas pass unknown fields through. Telegram adds fields and update kinds over time; they stay reachable at runtime (through a Record<string, unknown> cast) and never fail the parse. A MessageEntity.type, ChatMember.status or Chat.type value this package doesn't know is accepted for the same reason; the documented values are exported as constants (CHAT_TYPES, …) to compare against.

Request Schemas

Schema Purpose
SendMessageRequestSchemaObject Body for POST /sendMessage
EditMessageTextRequestSchemaObject Body for POST /editMessageText
EditMessageReplyMarkupRequestSchemaObject Body for POST /editMessageReplyMarkup
DeleteMessageRequestSchemaObject Body for POST /deleteMessage
AnswerCallbackQueryRequestSchemaObject Body for POST /answerCallbackQuery (text 0-200 characters)
SetWebhookRequestSchemaObject Body for POST /setWebhook (secret_token required)
DeleteWebhookRequestSchemaObject Body for POST /deleteWebhook
SetMyCommandsRequestSchemaObject Body for POST /setMyCommands (at most 100 commands)
GetMyCommandsRequestSchemaObject Body for POST /getMyCommands
DeleteMyCommandsRequestSchemaObject Body for POST /deleteMyCommands (same shape as getMyCommands)

Message options and keyboards

Schema Purpose
LinkPreviewOptionsSchemaObject link_preview_options
ReplyParametersSchemaObject reply_parameters; needs message_id (or ephemeral_message_id)
ReplyMarkupSchemaObject sendMessage's reply_markup: any of the four shapes below
InlineKeyboardMarkupSchemaObject { inline_keyboard: InlineKeyboardButton[][] }; the only markup edits accept
InlineKeyboardButtonSchemaObject One inline button: exactly one action; callback_data 1-64 bytes of UTF-8
ReplyKeyboardMarkupSchemaObject A custom reply keyboard; buttons are strings or KeyboardButtons
KeyboardButtonSchemaObject One reply-keyboard button; at most one request_*/web_app action
ReplyKeyboardRemoveSchemaObject { remove_keyboard: true }
ForceReplySchemaObject { force_reply: true }
WebAppInfoSchemaObject, LoginUrlSchemaObject, CopyTextButtonSchemaObject Objects nested in inline buttons

Command menu

Schema Purpose
BotCommandSchemaObject { command, description }: 1-32 of a-z 0-9 _, and 1-256 characters
BotCommandScopeSchemaObject BotCommandScope, discriminated on type (seven variants)
BotCommandScope*SchemaObject Each scope variant on its own (Default, AllPrivateChats, Chat, …)

Response Schemas

Schema Purpose
MessageSchemaObject A Message: sent, edited, or received in an update
MessageEntitySchemaObject One MessageEntity (a bot_command, URL, bold span, …); offsets in UTF-16 units
UserSchemaObject A User: the bot from getMe(), or a message's from
ChatSchemaObject The Chat a message belongs to
EditMessageResultSchemaObject editMessageText/editMessageReplyMarkup result: a Message, or true
TrueResultSchemaObject The bare true most other methods return
WebhookInfoSchemaObject getWebhookInfo()'s result
BotCommandListSchemaObject getMyCommands()'s result
ResponseEnvelopeSchemaObject Telegram's universal { ok, result, error_code, description, parameters } wrapper
ResponseParametersSchemaObject The envelope's parameters field (retry_after, migrate_to_chat_id)

Webhook Updates

Schema Purpose
UpdateSchemaObject One webhook Update
CallbackQuerySchemaObject update.callback_query: id, from, data, message, …
MaybeInaccessibleMessageSchemaObject A callback query's message: a Message, or an inaccessible one (date: 0)
InaccessibleMessageSchemaObject A deleted or too-old message: only chat, message_id and date: 0
ChatMemberUpdatedSchemaObject update.my_chat_member / update.chat_member
ChatMemberSchemaObject A chat member's status and user; variant fields pass through

UpdateSchema types message, edited_message, channel_post, edited_channel_post, callback_query, my_chat_member and chat_member. Every other documented kind (listed in UPDATE_TYPES) and any future kind is kept untyped. Telegram.updateKind(update) names the kind.

Message models the fields a text bot uses — from, chat, text, entities, edit_date, message_thread_id, sender_chat, and the migrate_to_chat_id/migrate_from_chat_id service fields — out of the 100+ Telegram documents.

Common Validators and Constants

Export Purpose
chatIdGuard A chat_id: an integer, or an @username string (a numeric string stays a string)
botTokenGuard A bot token: <digits>:<secret>
webhookSecretTokenGuard A webhook secret_token: 1-256 of A-Z a-z 0-9 _ -; never echoes the value
PARSE_MODES 'MarkdownV2', 'HTML', 'Markdown'
MESSAGE_TEXT_MAX_LENGTH 4096; see the counting caveat in API
CALLBACK_DATA_MAX_BYTES 64
CALLBACK_ANSWER_TEXT_MAX_LENGTH 200
MAX_BOT_COMMANDS 100
UPDATE_TYPES Every documented update kind; also what allowed_updates accepts
WEBHOOK_SECRET_TOKEN_PATTERN The secret_token pattern
WEBHOOK_PORTS 443, 80, 88, 8443
CHAT_TYPES, CHAT_MEMBER_STATUSES, MESSAGE_ENTITY_TYPES, BUTTON_STYLES The documented values of those fields

← Back to Telegram

⚠️ **GitHub.com Fallback** ⚠️