| name | add-telegram-api-action |
| description | 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, answerInlineQuerybotactions/ - getMe, setWebhook, etc.chat/ - getChat, banChatMember, etc.
Required:
@TgAPI on class@TgAPI.Name("methodName") on method when Kotlin name differs from APIoverride val method, returnType, options (if OptionsFeature)
Features (add as needed):
OptionsFeature - optional params via options { }MarkupFeature - reply_markupCaptionFeature - caption, caption_entities (media)EntitiesFeature - entities (text)BusinessActionExt - chat-based actionsInlineActionExt - 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 eachinline fun actionName(...) = ActionClass(...)- Overloads for
ImplicitFile, InputFile, ByteArray, () -> String as in existing media actions
- Optional
sendActionName alias
6. Validate
./gradlew formatKotlin
./gradlew prepareRelease
Reference Examples
