# yaml-language-server: $schema=https://schema.zeabur.app/template.json
apiVersion: zeabur.com/v1
kind: Template
metadata:
    name: OpenAB Telegram
spec:
    description: |
        One-click Telegram bot powered by OpenAB + Kiro. A single unified service — the OAB binary embeds the Telegram webhook server directly. Fill in one bot token and you're done. No gateway service, no manual config.toml edits.
        Source: https://github.com/openabdev/openab
    coverImage: https://cdn-console.zeabur.com/f/Xp0H6/openab-cover.webp
    icon: https://cdn-console.zeabur.com/f/0Ewi6/openab-icon.webp
    variables:
        - key: TELEGRAM_BOT_TOKEN
          type: STRING
          name: Telegram Bot Token
          description: Bot token from @BotFather (https://t.me/BotFather). Required.
        - key: BOT_USERNAME
          type: STRING
          name: Bot Username
          description: Your bot's username without the @ (e.g. `my_zeabur_bot`). Required for @mention gating in Telegram groups.
        - key: KIRO_API_KEY
          type: STRING
          name: Kiro API Key (optional, Pro+)
          description: Optional. API key for Kiro Pro/Pro+/Power subscribers. Leave empty to authenticate via device flow after deployment (free tier).
        - key: PUBLIC_DOMAIN
          type: DOMAIN
          name: Webhook Domain
          description: Public HTTPS domain for receiving Telegram webhooks. Auto-assigned.
        - key: OPENAB_AGENT_COMMAND
          type: STRING
          name: Agent Command (optional)
          description: 'Optional. Override the agent CLI command (default: kiro-cli). Only change if you know what you''re doing.'
        - key: OPENAB_CONFIG_URL
          type: STRING
          name: Config URL (optional)
          description: Optional. URL to a remote config.toml (https://). When set, the local config file is ignored and this URL is used instead.
    tags:
        - AI
        - Developer Tools
        - Telegram
    readme: |
        # OpenAB Telegram

        One-click [OpenAB](https://github.com/openabdev/openab) deployment for Telegram — a single unified service. The OAB binary embeds the Telegram webhook server directly (unified mode, v0.9.0+). Just fill in your Telegram bot token.

        ```
        Telegram ──POST──▶ ┌──────────────────────────────┐
                           │  openab (:8080/webhook/telegram) ──▶ Kiro CLI
                           └──────────────────────────────┘
                              public HTTPS, one service
        ```

        No separate gateway service, no PVC sharing, no manual `config.toml` edits. Telegram is auto-enabled by the `TELEGRAM_BOT_TOKEN` environment variable.

        ## Setup

        ### 1. Create a Telegram Bot

        1. Open [@BotFather](https://t.me/BotFather) in Telegram
        2. Send `/newbot` and follow the prompts
        3. **Username** you chose (e.g. `my_zeabur_bot`, must end in `bot`) → paste into **Bot Username**
        4. **Bot token** that follows (e.g. `123456:ABC-DEF...`) → paste into **Telegram Bot Token**
        5. For group/supergroup use: send `/setprivacy` → `Disable` so the bot can see all messages (required for @mention gating)
        6. For supergroups with forum topics (auto thread-per-conversation): add the bot to the group → group settings → Administrators → enable **Manage Topics**

        ### 2. (Optional) Get a Kiro API Key

        If you have a paid Kiro subscription, go to [kiro.dev](https://kiro.dev) → Settings → API Keys → create a key and paste it into `KIRO_API_KEY`. Free tier users skip this and authenticate post-deploy in step 4.

        ### 3. Deploy

        Click deploy. A public HTTPS domain is auto-assigned to the service.

        ### 4. Authenticate Kiro via Device Flow (free tier only)

        Skip if you set `KIRO_API_KEY` in step 2.

        After the `openab` service is running, open its terminal in Zeabur Dashboard and run:

        ```
        runuser -u agent -- kiro-cli login --use-device-flow
        ```

        Follow the URL and code to authorize in your browser.

        ### 5. Test

        Send a message to your Telegram bot.

        **The Telegram webhook is registered automatically** by an init container at startup — look for `openab: telegram webhook registered → https://...` in the service logs. No manual `curl setWebhook` needed.

        If you ever need to re-trigger it (e.g. after rotating the bot token or changing the domain), open the **openab** service page in Zeabur Dashboard — under **Instructions**, the `Re-register Telegram Webhook` curl is pre-filled.

        ## Access Control

        By default the bot answers everyone (`TELEGRAM_ALLOW_ALL_USERS=true`). To restrict it, set `TELEGRAM_ALLOW_ALL_USERS=false` and `TELEGRAM_ALLOWED_USERS` to a comma-separated list of Telegram user IDs, then restart.

        ## Customization

        - **`/home/agent/.config/openab/config.toml`** — OAB config (sessions, reactions, etc.). Created on first boot from a built-in template. To regenerate, delete and restart.
        - **Image tag** — tracks the floating `beta` channel (`ghcr.io/openabdev/openab:beta-kiro`) and auto-updates with each new beta release. Switch to `stable` for production use. To pin or bump, change the tag in Zeabur Dashboard → Service → Settings. Available tags: [GitHub Packages](https://github.com/openabdev/openab/pkgs/container/openab).

        ## Want a different agent backend?

        This template uses Kiro as the agent. For Claude / Codex / Cursor / Gemini / OpenCode / Hermes / Grok, deploy the corresponding [bot template](https://zeabur.com/templates) instead.

        ## Want a different platform?

        Unified mode auto-enables platforms from environment variables on this same service: LINE (`LINE_CHANNEL_SECRET`), Feishu/Lark (`FEISHU_APP_ID`), Google Chat (`GOOGLE_CHAT_ENABLED=true`), MS Teams (`TEAMS_APP_ID`), WeCom (`WECOM_CORP_ID`). See the [OpenAB docs](https://github.com/openabdev/openab/tree/main/docs) for per-platform setup.

        ## Links

        - [OpenAB GitHub](https://github.com/openabdev/openab)
        - [Telegram Setup Guide](https://github.com/openabdev/openab/blob/main/docs/telegram.md)
    resourceRequirement:
        minConfig:
            cpu: 2
            ram: 4
        recommendedConfig:
            cpu: 4
            ram: 8
    services:
        - name: openab
          icon: https://cdn-console.zeabur.com/f/0Ewi6/openab-icon.webp
          template: PREBUILT_V2
          spec:
            id: openab
            source:
                image: ghcr.io/openabdev/openab:beta-kiro
                command:
                    - /bin/sh
                    - -c
                    - /opt/start-openab.sh
                runAsUserID: 1000
            ports:
                - id: web
                  port: 8080
                  type: HTTP
            volumes:
                - id: agent-home
                  dir: /home/agent
            instructions:
                - title: Re-register Telegram Webhook (auto-runs at deploy — use this only to manually re-trigger)
                  content: curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook?url=https://${ZEABUR_WEB_DOMAIN}/webhook/telegram&secret_token=${TELEGRAM_SECRET_TOKEN}"
                - title: Unregister Telegram Webhook
                  content: curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteWebhook"
            env:
                KIRO_API_KEY:
                    default: ${KIRO_API_KEY}
                OPENAB_AGENT_COMMAND:
                    default: kiro-cli
                OPENAB_CONFIG_URL:
                    default: ""
                OPENAB_MAX_SESSIONS:
                    default: ""
                TELEGRAM_ALLOW_ALL_USERS:
                    default: "true"
                TELEGRAM_ALLOWED_USERS:
                    default: ""
                TELEGRAM_BOT_TOKEN:
                    default: ${TELEGRAM_BOT_TOKEN}
                TELEGRAM_BOT_USERNAME:
                    default: ${BOT_USERNAME}
                TELEGRAM_SECRET_TOKEN:
                    default: ${PASSWORD}
            init:
                - id: register-telegram-webhook
                  image: curlimages/curl:8.5.0
                  command:
                    - sh
                    - -c
                    - |
                      for i in 1 2 3 4 5; do
                        if curl -fsS -m 10 \
                             "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
                             --data-urlencode "url=https://${ZEABUR_WEB_DOMAIN}/webhook/telegram" \
                             --data-urlencode "secret_token=${TELEGRAM_SECRET_TOKEN}"; then
                          echo
                          echo "openab: telegram webhook registered → https://${ZEABUR_WEB_DOMAIN}/webhook/telegram"
                          exit 0
                        fi
                        echo "openab: webhook register attempt $i failed, retrying in 3s"
                        sleep 3
                      done
                      echo "openab: all webhook register attempts failed — service will still start; use the dashboard 'Re-register Telegram Webhook' instruction to recover."
                      exit 0
                  volumes: []
            configs:
                - path: /opt/start-openab.sh
                  template: |
                    #!/bin/sh
                    set -e

                    # Initialize shell dotfiles and fix ownership for persistent volume
                    if [ ! -f /home/agent/.bashrc ]; then
                      cp /etc/skel/.bashrc /etc/skel/.profile /etc/skel/.bash_logout /home/agent/ 2>/dev/null || true
                    fi

                    if [ "$(id -u)" = "0" ]; then
                      chown -R agent:agent /home/agent
                      chmod 755 /home/agent/.config 2>/dev/null || true
                    fi

                    CONFIG_DIR=/home/agent/.config/openab
                    CONFIG_FILE=$CONFIG_DIR/config.toml
                    mkdir -p "$CONFIG_DIR"

                    # Telegram is enabled by TELEGRAM_* env vars (unified mode) — no [gateway] config needed
                    if [ ! -f "$CONFIG_FILE" ]; then
                      cp /opt/config.toml.template "$CONFIG_FILE"

                      if [ -n "$OPENAB_MAX_SESSIONS" ]; then
                        printf '\n[pool]\nmax_sessions = %s\n' "$OPENAB_MAX_SESSIONS" >> "$CONFIG_FILE"
                      fi

                      echo "openab: config.toml generated"
                    else
                      echo "openab: using existing config.toml (delete to regenerate)"
                    fi

                    if [ "$(id -u)" = "0" ]; then
                      chown -R agent:agent "$CONFIG_DIR"
                      exec runuser -u agent --preserve-environment -- openab run --config "${OPENAB_CONFIG_URL:-$CONFIG_FILE}"
                    fi

                    exec openab run --config "${OPENAB_CONFIG_URL:-$CONFIG_FILE}"
                  permission: 493
                  envsubst: null
                - path: /opt/config.toml.template
                  template: |
                    [agent]
                    args = ["acp", "--trust-all-tools"]
                  permission: null
                  envsubst: null
            healthCheck:
                type: TCP
                port: web
          domainKey: PUBLIC_DOMAIN
localization:
    zh-CN:
        description: |
            一键部署的 Telegram Bot，集成 OpenAB + Kiro。单一 unified 服务——OAB 主程序直接内置 Telegram webhook server，只需填入 Bot Token 即可使用。无需 gateway 服务、无需手动修改 config.toml。
            来源：https://github.com/openabdev/openab
        variables:
            - key: TELEGRAM_BOT_TOKEN
              type: STRING
              name: Telegram Bot Token
              description: 来自 @BotFather 的 Bot Token（https://t.me/BotFather）。必填。
            - key: BOT_USERNAME
              type: STRING
              name: Bot Username
              description: Bot 的 username（不含 @，例如 `my_zeabur_bot`）。群组中 @mention 判定需要这个值。
            - key: KIRO_API_KEY
              type: STRING
              name: Kiro API Key（选填，Pro+ 方案）
              description: 选填。Kiro Pro/Pro+/Power 订阅者可填入 API Key，部署后无需手动登录。免费方案留空，部署后使用 device flow 认证。
            - key: PUBLIC_DOMAIN
              type: STRING
              name: Webhook 域名
              description: 用于接收 Telegram Webhook 的公开 HTTPS 域名，自动分配。
        readme: |
            # OpenAB Telegram

            一键部署的 [OpenAB](https://github.com/openabdev/openab) Telegram bot — 单一 unified 服务，OAB 主程序直接内置 Telegram webhook server（unified mode，v0.9.0+）。只需填入 Telegram Bot Token。

            无需独立 gateway 服务、无需共享 PVC、无需手动修改 `config.toml`。设置 `TELEGRAM_BOT_TOKEN` 环境变量即自动启用 Telegram。

            ## 设置步骤

            ### 1. 创建 Telegram Bot

            1. 在 Telegram 打开 [@BotFather](https://t.me/BotFather)
            2. 发送 `/newbot` 并按照提示操作
            3. **你设置的 username**（例如 `my_zeabur_bot`，必须以 `bot` 结尾）→ 粘贴到 **Bot Username**
            4. **生成的 bot token**（例如 `123456:ABC-DEF...`）→ 粘贴到 **Telegram Bot Token**
            5. 群组 / supergroup 使用：发送 `/setprivacy` → `Disable`，让 Bot 可以看到所有消息（@mention 判定需要此设置）
            6. Supergroup 含 forum topic（自动「每段对话一个 thread」）：把 bot 加入群组 → 群组设置 → 管理员 → 开启 **Manage Topics** 权限

            ### 2. （选填）获取 Kiro API Key

            如有付费 Kiro 订阅，前往 [kiro.dev](https://kiro.dev) → Settings → API Keys 创建 key，填入 `KIRO_API_KEY`。免费方案跳过此步骤，于步骤 4 部署后再认证。

            ### 3. 部署

            点击部署。系统会自动分配公开 HTTPS 域名给服务。

            ### 4. 通过 Device Flow 认证 Kiro（仅免费方案）

            若步骤 2 已填入 `KIRO_API_KEY`，跳过此步骤。

            待 `openab` 服务启动后，在 Zeabur Dashboard 打开该服务的终端，运行：

            ```
            runuser -u agent -- kiro-cli login --use-device-flow
            ```

            按照屏幕显示的 URL 和 code 完成浏览器授权。

            ### 5. 测试

            向 Telegram Bot 发送消息。

            **Telegram webhook 由 init container 在启动时自动注册**——于服务 log 找 `openab: telegram webhook registered → https://...` 确认。不需要手动跑 `curl setWebhook`。

            若日后需要重新触发（例如 revoke bot token 后、或更换域名），可到 **openab** 服务页面 → **Instructions** 区，已预填好的 `Re-register Telegram Webhook` curl 指令可手动执行。

            ## 访问控制

            默认任何人都可以与 Bot 互动（`TELEGRAM_ALLOW_ALL_USERS=true`）。如需限制，设置 `TELEGRAM_ALLOW_ALL_USERS=false` 并在 `TELEGRAM_ALLOWED_USERS` 填入逗号分隔的 Telegram 用户 ID，然后重启服务。

            ## 想换不同的 agent 后端？

            本模板使用 Kiro 作为 agent。若想用 Claude / Codex / Cursor / Gemini / OpenCode / Hermes / Grok，请改部署对应的 [bot template](https://zeabur.com/templates)。

            ## 想用其他通讯平台？

            Unified mode 直接以环境变量在同一服务启用其他平台：LINE（`LINE_CHANNEL_SECRET`）、飞书/Lark（`FEISHU_APP_ID`）、Google Chat（`GOOGLE_CHAT_ENABLED=true`）、MS Teams（`TEAMS_APP_ID`）、WeCom（`WECOM_CORP_ID`）。各平台设置请见 [OpenAB 文档](https://github.com/openabdev/openab/tree/main/docs)。

            ## 链接

            - [OpenAB GitHub](https://github.com/openabdev/openab)
            - [Telegram 设置指南](https://github.com/openabdev/openab/blob/main/docs/telegram.md)
    zh-TW:
        description: |
            一鍵部署的 Telegram Bot，整合 OpenAB + Kiro。單一 unified 服務——OAB 主程式直接內建 Telegram webhook server，只需填入 Bot Token 即可使用。無需 gateway 服務、無需手動修改 config.toml。
            來源：https://github.com/openabdev/openab
        variables:
            - key: TELEGRAM_BOT_TOKEN
              type: STRING
              name: Telegram Bot Token
              description: 來自 @BotFather 的 Bot Token（https://t.me/BotFather）。必填。
            - key: BOT_USERNAME
              type: STRING
              name: Bot Username
              description: Bot 的 username（不含 @，例如 `my_zeabur_bot`）。群組中 @mention 判定需要這個值。
            - key: KIRO_API_KEY
              type: STRING
              name: Kiro API Key（選填，Pro+ 方案）
              description: 選填。Kiro Pro/Pro+/Power 訂閱者可填入 API Key，部署後無需手動登入。免費方案留空，部署後使用 device flow 認證。
            - key: PUBLIC_DOMAIN
              type: STRING
              name: Webhook 網域
              description: 用於接收 Telegram Webhook 的公開 HTTPS 網域，自動分配。
        readme: |
            # OpenAB Telegram

            一鍵部署的 [OpenAB](https://github.com/openabdev/openab) Telegram bot — 單一 unified 服務，OAB 主程式直接內建 Telegram webhook server（unified mode，v0.9.0+）。只需填入 Telegram Bot Token。

            ```
            Telegram ──POST──▶ ┌──────────────────────────────┐
                               │  openab (:8080/webhook/telegram) ──▶ Kiro CLI
                               └──────────────────────────────┘
                                  公開 HTTPS，單一服務
            ```

            無需獨立 gateway 服務、無需共用 PVC、無需手動修改 `config.toml`。設定 `TELEGRAM_BOT_TOKEN` 環境變數即自動啟用 Telegram。

            ## 設定步驟

            ### 1. 建立 Telegram Bot

            1. 在 Telegram 開啟 [@BotFather](https://t.me/BotFather)
            2. 發送 `/newbot` 並依照提示操作
            3. **你設定的 username**（例如 `my_zeabur_bot`，必須以 `bot` 結尾）→ 貼到 **Bot Username**
            4. **產生的 bot token**（例如 `123456:ABC-DEF...`）→ 貼到 **Telegram Bot Token**
            5. 群組 / supergroup 使用：發送 `/setprivacy` → `Disable`，讓 Bot 可以看到所有訊息（@mention 判定需要此設定）
            6. Supergroup 含 forum topic（自動「每段對話一個 thread」）：把 bot 加入群組 → 群組設定 → 管理員 → 開啟 **Manage Topics** 權限

            ### 2. （選填）取得 Kiro API Key

            如果你有付費的 Kiro 訂閱，前往 [kiro.dev](https://kiro.dev) → Settings → API Keys 建立 key，填入 `KIRO_API_KEY`。免費方案跳過此步驟，於步驟 4 部署後再認證。

            ### 3. 部署

            點擊部署。系統會自動分配公開 HTTPS 網域給服務。

            ### 4. 透過 Device Flow 認證 Kiro（僅免費方案）

            若步驟 2 已填入 `KIRO_API_KEY`，跳過此步驟。

            待 `openab` 服務啟動後，於 Zeabur Dashboard 開啟該服務的終端機，執行：

            ```
            runuser -u agent -- kiro-cli login --use-device-flow
            ```

            依照畫面顯示的 URL 與 code 完成瀏覽器授權。

            ### 5. 測試

            向你的 Telegram Bot 發送訊息。

            **Telegram webhook 由 init container 在啟動時自動註冊**——於服務 log 找 `openab: telegram webhook registered → https://...` 確認。不需要手動跑 `curl setWebhook`。

            若日後需要重新觸發（例如 revoke bot token 後、或更換網域），可至 **openab** 服務頁面 → **Instructions** 區，已預填好的 `Re-register Telegram Webhook` curl 指令可手動執行。

            ## 存取控制

            預設任何人都可以與 Bot 互動（`TELEGRAM_ALLOW_ALL_USERS=true`）。如需限制，設定 `TELEGRAM_ALLOW_ALL_USERS=false` 並在 `TELEGRAM_ALLOWED_USERS` 填入逗號分隔的 Telegram 用戶 ID，然後重啟服務。

            ## 自訂設定

            - **`/home/agent/.config/openab/config.toml`** — OAB 設定（sessions、reactions 等）。首次啟動時從內建範本建立。如需重建，刪除檔案後重啟服務。
            - **映像標籤** — 追蹤 floating `beta` 標籤（`ghcr.io/openabdev/openab:beta-kiro`），每次推出新 beta 版時自動更新。正式環境建議切換至 `stable`。若要 pin 至特定版本或手動升版，請至 Zeabur Dashboard → 服務 → 設定修改映像標籤。可用標籤：[GitHub Packages](https://github.com/openabdev/openab/pkgs/container/openab)。

            ## 想換不同的 agent 後端？

            本模板使用 Kiro 作為 agent。若想用 Claude / Codex / Cursor / Gemini / OpenCode / Hermes / Grok，請改部署對應的 [bot template](https://zeabur.com/templates)。

            ## 想用其他通訊平台？

            Unified mode 直接以環境變數在同一服務啟用其他平台：LINE（`LINE_CHANNEL_SECRET`）、Feishu/Lark（`FEISHU_APP_ID`）、Google Chat（`GOOGLE_CHAT_ENABLED=true`）、MS Teams（`TEAMS_APP_ID`）、WeCom（`WECOM_CORP_ID`）。各平台設定請見 [OpenAB 文件](https://github.com/openabdev/openab/tree/main/docs)。

            ## 連結

            - [OpenAB GitHub](https://github.com/openabdev/openab)
            - [Telegram 設定指南](https://github.com/openabdev/openab/blob/main/docs/telegram.md)