telegram-bot-api

Telegram Bot API Rules

TgAPI Annotation

• Mark Action classes and top-level API functions with @TgAPI (required for api-sentinel validation)
• Use @TgAPI.Name("methodName") on the method property when the Kotlin name differs from the Telegram API method (e.g. sendMessage vs message)
• Use @TgAPI.Ignore on params/classes to exclude from validation

beforeReq

• protected open val beforeReq = {} runs right before the request (in doRequest / doRequestReturning)
• Override when you need to process data at request time (e.g. multipart, transform files)
• Use for: uploading files from Options (thumbnail, certificate), transforming nested ImplicitFile in complex types (InputProfilePhoto, InputStoryContent)
• beforeReq runs after init; it has access to parameters, multipartData, and options

override val beforeReq: () -> Unit = {
    handleImplicitFile(options::thumbnail)  // optional file from Options
}

ImplicitFile Handling

• ImplicitFile = FileId (String file_id) or FileData (InputFile for upload)
• Use handleImplicitFile(file, "paramName") in init for required media params
• For optional media in Options (thumbnail, cover): handleImplicitFile(options::thumbnail) in beforeReq
• transform(multipartData): FileData -> uploads to multipart, returns FileId with attach://filename
• Convert: String.toImplicitFile(), InputFile.toImplicitFile(), ByteArray.toImplicitFile("name.ext")
• Complex types (InputProfilePhoto, InputStoryContent): use file.transform(multipartData) in beforeReq, then replace file with result and encode

Action Hierarchy

• TgAction (base) -> Action (chat-based: send(to, via)) or SimpleAction (no chat: send(via))
• Use Action when the method requires chat_id (messages, media, etc.)
• Use SimpleAction when no chat context (getMe, getUpdates, setWebhook, etc.)
• MediaAction extends Action; overrides entitiesFieldName = "caption_entities"
• Extensions: BusinessActionExt (business connection), InlineActionExt (inline message ID)