AgentSkillsCN

add-telegram-api-action

【库贡献者】为 Telegram Bot API 新增一个方法（动作类与顶级函数）。适用于实现新的 Telegram API 端点，为特定方法（如 sendVideoNote、getChatMemberCount）添加支持，或为 Telegram Bot 库创建全新动作时使用。

SKILL.md
--- frontmatter
name: add-telegram-api-action
description: [Library contributor] Adds a new Telegram Bot API method (action class and top-level functions). Use when implementing a new Telegram API endpoint, adding support for a specific method (e.g. sendVideoNote, getChatMemberCount), or creating a new action for the telegram-bot library.

Add Telegram API Action

Workflow

1. Determine Action Type

  • •Requires chat_id? -> Action (or MediaAction for media)
  • •No chat context? -> SimpleAction (e.g. getMe, getUpdates, setWebhook)

2. Check Telegram API Spec

Consult core.telegram.org/bots/api for:

  • •Method name (snake_case)
  • •Required vs optional parameters
  • •Return type

3. Create Options Class (if optional params)

  • •Place in telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/types/options/
  • •data class implementing Options + mixins (OptionsCommon, OptionsParseMode, MediaSpoiler, ForumProps, etc.)
  • •All optional params: var prop: Type? = null
  • •Add @Serializable
  • •Mixin interfaces: Put optional params into separate mixin interfaces in IOptions.kt when they can be reused by other Options classes. Add a new interface (e.g. interface MyProp : Options { var myParam: Type? }) only when the param is shared; single-use params stay in the data class.

4. Create Action Class

Place in appropriate package under telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/api/:

  • •media/ - photo, video, document, etc.
  • •message/ - sendMessage, editMessage, etc.
  • •answer/ - answerCallbackQuery, answerInlineQuery
  • •botactions/ - getMe, setWebhook, etc.
  • •chat/ - getChat, banChatMember, etc.

Required:

  • •@TgAPI on class
  • •@TgAPI.Name("methodName") on method when Kotlin name differs from API
  • •override val method, returnType, options (if OptionsFeature)

Features (add as needed):

  • •OptionsFeature - optional params via options { }
  • •MarkupFeature - reply_markup
  • •CaptionFeature - caption, caption_entities (media)
  • •EntitiesFeature - entities (text)
  • •BusinessActionExt - chat-based actions
  • •InlineActionExt - inline message actions

Parameter handling:

  • •Simple (String, Long, Int, Boolean): parameters["key"] = value.toJsonElement()
  • •Complex objects: value.encodeWith(MyType.serializer())
  • •Lists: list.encodeWith(ListSerializer(ItemType.serializer()))
  • •Polymorphic ID (chat/user: Long or String): value.encodeWith(DynamicLookupSerializer)
  • •Enums: value.encodeWith(EnumType.serializer())
  • •Required media: handleImplicitFile(file, "paramName") in init
  • •Optional media in Options (thumbnail): handleImplicitFile(options::thumbnail) in override val beforeReq
  • •Complex types with nested ImplicitFile (InputProfilePhoto, InputStoryContent): transform in beforeReq, then encodeWith(Serializer)

Use encodeWith for any @Serializable class, list, or polymorphic type; use toJsonElement() only for primitives.

5. Add Top-Level Functions

  • •@TgAPI on each
  • •inline fun actionName(...) = ActionClass(...)
  • •Overloads for ImplicitFile, InputFile, ByteArray, () -> String as in existing media actions
  • •Optional sendActionName alias

6. Validate

bash
./gradlew formatKotlin
./gradlew prepareRelease

Reference Examples