# Vendelieu Telegram Bot Add Telegram Update Field

> Add Telegram Update Field

- Skill: `tomevault-io/vendelieu-telegram-bot-add-telegram-update-field` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/vendelieu-telegram-bot-add-telegram-update-field`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/vendelieu-telegram-bot-add-telegram-update-field/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/vendelieu-telegram-bot-add-telegram-update-field

---


# Add Telegram Update Field

## Workflow

### 1. Add Field to Update

- In [Update.kt](telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/types/common/Update.kt): add `val myField: MyType? = null` (camelCase, nullable)
- Add import for the payload type if needed

### 2. Add UpdateType Entry

- In [UpdateType.kt](telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/types/component/UpdateType.kt): add enum entry with `@SerialName("snake_case")` matching Telegram API (e.g. `MY_FIELD`)

### 3. Add ProcessedUpdate Subclass

- In [ProcessedUpdate.kt](telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/types/component/ProcessedUpdate.kt): add `data class MyFieldUpdate(...) : ProcessedUpdate(...)`
- Use `@Serializable(MyFieldUpdate.Companion::class)` and `internal companion object : UpdateSerializer<MyFieldUpdate>()`
- Implement `UserReference` when the update has a user; `ChatReference` when it has a chat; `TextReference` when it has text

### 4. Add processUpdate Clause

- In [ProcessUpdate.kt](telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/utils/common/ProcessUpdate.kt): add `myField != null -> MyFieldUpdate(updateId, this, myField)`
- Add import for the new ProcessedUpdate subclass
- Place clause in a logical order (group with similar update types)

### 5. Update KSP Module

- In [TypeConstants.kt](ktnip/src/jvmMain/kotlin/eu/vendeli/ktnip/utils/TypeConstants.kt): add `val myFieldUpdateClass: TypeName = MyFieldUpdate::class.asTypeName()`
- In [TypeMapper.kt](ktnip/src/jvmMain/kotlin/eu/vendeli/ktnip/codegen/TypeMapper.kt): add `TypeConstants.myFieldUpdateClass to MyFieldUpdate::class` to `updateTypeMap`

### 6. Regenerate FunctionalDSLUtils

- Run `./gradlew prepareRelease` (or full build)
- api-sentinel KSP regenerates [FunctionalDSLUtils.kt](telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/utils/common/FunctionalDSLUtils.kt) from `UpdateType.entries`; no manual edits needed

**Handling**: The new `onXxx` DSL function enables `bot.setFunctionality { onXxx { ... } }`. Both functional DSL and annotation approach (`@UpdateHandler`) use the same ActivityRegistry and ProcessingPipeline; see [telegram-bot-handling.mdc](.cursor/rules/telegram-bot-handling.mdc).

## Naming Conventions

- **Update field**: camelCase (e.g. `callbackQuery`, `messageReaction`)
- **UpdateType**: SCREAMING_SNAKE_CASE, `@SerialName("snake_case")` matching Telegram API
- **ProcessedUpdate subclass**: `XxxUpdate` (e.g. `CallbackQueryUpdate`)

## Reference Examples

- [MessageUpdate](telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/types/component/ProcessedUpdate.kt) - UserReference + ChatReference
- [PollUpdate](telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/types/component/ProcessedUpdate.kt) - minimal, no User/Chat
- [CallbackQueryUpdate](telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/types/component/ProcessedUpdate.kt) - UserReference + ChatReference

## Validation

```bash
./gradlew formatKotlin
./gradlew prepareRelease
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/vendelieu) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->