Flutter Web for Telegram Mini App (TMA)

12 min readFeb 22, 2025

Flutter is everywhere.

在現今的通訊軟體中，Telegram 是一個主流且熱門的選項，它的特點很多人都清楚，就是高度的保密性。在應用的聊天場景裡，它提供了一種創新的方式，讓開發者可以透過 Web Mini App 擴展聊天機器人的功能，實現與用戶更深層的互動體驗。本文旨在完整介紹如何設置並開發 Telegram Mini App，包括初始配置、功能開發到最後的部署及偵錯。通過結合 Flutter 技術，開發者能夠快速建立豐富多彩的 Mini App，不只是簡單的網頁而已，提升項目的可用性與靈活性。無論是新手還是有經驗的開發者，相信本指南都能提供有效的參考與實踐方向，為您的應用開發注入更多可能性。

Telegram Mini App Setting

Initial Setting

首先開啟 BotFather 聊天室，它是機器人的總管，所有相關操作都需要跟他互動

使用 /newbot 建立機器人，給予名稱，必須是 bot 結尾。輸入後就會得到一個機器人，並給予一個 API token

使用 /newapp 新建 Web mini app，包含一些基本資訊，例如：名稱、描述、圖檔(640x360)

設置先前部署好的 Flutter Web Url，小應用會開啟這個網頁。最後得到一個 Telegram 的 app link，以此範例就是 t.me/jassgirl_bot/jessica

Menu Setting

使用 /mybots 查看擁有的機器人，點擊 Bot Settings → Menu Button，設置選單按鈕的名稱還有 Web 網址

之後針對選單也可以隨意更新，跟 BotFather 的互動上都很直覺和簡單。

Flutter Development

使用 telegram_web_app 套件進行 Telegram SDK 開發。

telegram_web_app | Flutter package

Representation and implementation of telegram web/mini apps apis

pub.dev

專案設置，在 index.html 加上 js 初始化。

...
<script src="<https://telegram.org/js/telegram-web-app.js>" defer=""></script>
...

開發上很簡單，透過 TelegramWebApp.instance 進行所有 Telegram 上的互動。

TelegramWebApp.instance.initData;

開啟小應用後就會顯示我們所設置的 Flutter Web 網頁，可以從中取得一些 Telegram 用戶的基本資料，例如：id、firstname、lastname、username、languageCode 等等。

另外可以經由套件執行一些 Telegram 操作。

// Get user data
TelegramWebApp.instance.initData.user
TelegramWebApp.instance.initDataUnsafe.user

// Open external link
TelegramWebApp.instance.openLink('<https://google.com>')

// Open telegram link
TelegramWebApp.instance.openTelegramLink('<https://t.me/username>');

// Show alert dialog
TelegramWebApp.instance.showAlert('Alert message');

// Show confirm dialog
TelegramWebApp.instance.showConfirm('Confirm');

// Expand bottom sheet
TelegramWebApp.instance.expand();

// Close bottom sheet
TelegramWebApp.instance.close();

針對關閉 Mini App 的操作，通常會使用 close()，但在雙平台的行為上有點不同。Android可以正常關閉，但是 iOS 需要經由 SystemNavigator 執行底層的關閉方式。

// Android
TelegramWebApp.instance.close();

// iOS
await SystemNavigator.pop();

Demo

其他操作

分享給好友

分享頻道資訊給 Telegram 好友，透過內建分享列表，並附上自定義資訊。

範例：https://t.me/<BOT_NAME>?xxx=zzz

await TelegramWebApp.instance.openTelegramLink(
  '<https://t.me/share/url?url=$link>',
);

Direct Link 開啟 Mini App

在聊天室中可以透過按鈕或是連結訊息，直接開啟 Mini App 並跳轉到指定頁面，甚至也可以直接運行某個功能，讓整體的操作體驗更絲滑。

官網在文件上有提出連結範例：

Telegram Mini Apps

With Mini Apps developers can use JavaScript to create infinitely flexible interfaces that can be launched right…

core.telegram.org

需要跟 BotFather 設置你的機器人跟 Mini App，連結會使用到他們。點擊之後即可開啟選單應用

<https://t.me/><bot-username>/<app-name>

// Example
<https://t.me/crush_on_jessica_bot/miniapp>

在連結上可以放置自定義資訊，方便我們在開啟 Mini App 後可以辨識來源與意圖。

<https://t.me/><bot-username>/<app-name>?startapp=<data>

Mini App 端可以透過 SDK 的 initDataUnsafe 取得 WebAppInitData 物件。其中的 start_param 欄位就是我們先前放置的資料，可以進一步解析後最後續處理。

final directLinkData =
        TelegramWebApp.instance.initDataUnsafe?.start_param ?? '';

經過測試驗證，initDataUnsafe 物件的資料確實不完全穩定。如果在應用開啟之後馬上要存取，可以在前面等待 1 秒，確保載入 Telegram 資訊完整。

開啟指定聊天室

<https://t.me/><bot-username>/

// Example
<https://t.me/crush_on_jessica_bot/>

開啟 Star 商品購買

透過 openInvoice() 打開指定的 Invoice 購買連結。可以透過 Telegram API 的 createInvoiceLink 創建屬於自己的購買連結。

TelegramWebApp.instance.openInvoice(
  r'<https://t.me/$61T-akbE6UVYAQAAqs9lejAKWw4>',
)

創建 Invoice URL 範例：

curl --location '<https://api.telegram.org/bot<token>/createInvoiceLink>' \\
--form 'title="test"' \\
--form 'description="test"' \\
--form 'payload="{\\"test\\":\\"test\\"}"' \\
--form 'provider_token=""' \\
--form 'currency="XTR"' \\
--form 'prices="[{\\"amount\\": 1, \\"label\\": \\"測試\\"}]"'