2022年4月Telegram的MiniApp（之前为Web App，6.0版后改名为Mini App）上线，Mini Apps（简称 TMAs，中文名：小程序）很可能会变成一个类似于微信小程序的平台，使得Telegram 更接近一个“超级应用”。目前，电报小程序推出不久，版本还在快速迭代中，开发人员也较少，但电报庞大的用户群基础很可能会产生大量的小程序。

作为Web3的开发者，大多数应用都是前端和区块链直接交互，但电报bot只支持消息通过电报服务和bot所在的服务器进行交互，导致大量DAPP无法给到用户可靠的账户安全保障。电报小程序在电报应用中“嵌入”了Web前端应用，通过它与区块链和智能合约直接交互，将账户信息通过安全策略在本地进行保存，大幅度提高账户安全性。同时，将与区块链无关的业务逻辑通过bot与服务器进行交互，提高用户体验。

所以，Telegram+小程序+bot+智能合约的开发模式，可能会称为一种全新的Web3开发技术栈。事实上，从时间上看，电报小程序与TON链同时推出，也可能有这方面的用意。但是这种开发模式不仅仅适用于电报和TON链，更适用于用户量庞大的各种EVM链。

目前，尚未有中文教程对电报小程序做过系统介绍，笔者在开发过程中学习并翻译了官方开发文档如下。

1. Telegram Mini Apps（电报小程序）简介

通过电报小程序（Mini Apps），开发者可以使用JavaScript创建无限灵活的前端应用，直接在Telegram内启动小程序，并取代相类似功能的普通网站。

与电报机器人类似，电报小程序支持无缝授权，支持20多家支付提供商（包括Google Pay和Apple Pay）的集成支付，并向用户发送定制的推送通知等功能。

添加 @DurgerKingBot，体验下电报小程序。

2. 更新

2023年9月22日

Bot API 6.9

• 向WebApp类添加了cloudStorage属性。
• 向WebApp类添加了requestWriteAccess和requestContact方法。
• 向WebAppUser类添加了added_to_attachment_menu和allows_write_to_pm属性。
• 添加了writeAccessRequested和contactRequested事件。
• 通过setHeaderColor方法可设置任何标题颜色。

2023年4月21日

Bot API 6.7

• 支持通过内联查询inline query和直接链接direct link启动小应用程序。
• 向WebApp类添加了switchInlineQuery方法。

2022年12月30日

Bot API 6.4

• 向WebApp类添加了platform属性，方法openLink的可选参数options，以及showScanQrPopup、closeScanQrPopup、readTextFromClipboard方法。
• 添加了qrTextReceived、clipboardTextReceived事件。

2022年8月12日

Bot API 6.2

• 向WebApp类添加了isClosingConfirmationEnabled属性，以及enableClosingConfirmation、disableClosingConfirmation、showPopup、showAlert、showConfirm方法。
• 向WebAppUser类添加了is_premium属性。
• 添加了popupClosed事件。

2022年6月20日

Bot API 6.1

• 在群组、超级群组和频道聊天中，添加了使用添加到Attachment menu附件菜单的机器人的能力。
• 添加了支持t.me链接，可用于选择打开附件菜单的聊天。
• 向WebApp类添加了version、headerColor、backgroundColor、BackButton、HapticFeedback属性，以及isVersionAtLeast、setHeaderColor、setBackgroundColor、openLink、openTelegramLink、openInvoice等方法。
• 向ThemeParams类添加了secondary_bg_color属性。
• 向MainButton类添加了offClick方法。
• 向WebAppInitData类添加了chat、can_send_after属性。
• 添加了backButtonClicked、settingsButtonClicked、invoiceClosed事件。

3. 设计小程序

3.1 配色方案

小程序始终实时接收用户当前颜色主题的数据，因此您可以调整界面的外观以匹配它。例如，当用户在白天和夜间模式之间切换或使用各种自定义主题。

3.2 设计准则

Telegram以其迅捷、流畅和一致的跨平台设计而闻名。您的小程序在理想情况下应反映这些原则：

• 所有元素应具有响应性，并采用以移动设备为优先的设计方法。
• 交互元素应模仿已存在的UI组件的样式、行为和意图。
• 所有动画应该流畅，理想情况下为60帧每秒。
• 所有输入和图像应包含标签，以便实现无障碍访问。
• 应用程序应通过API提供的基于主题的动态颜色，并相应地使用它们，以提供无缝的体验。

4. 启动小程序

Telegram目前支持六种不同的方式启动小程序：

• 通过键盘按钮 keyboard button
• 通过内联按钮 inline button
• 通过机器人菜单按钮 menu button
• 通过内联模式 inline mode
• 通过直接链接 direct link
• 通过附件菜单启动 attatchment link

各种启动方法见下图：

4.1 键盘按钮启动 keyboard button

从web_app类型的键盘按钮启动的小程序，可以使用Telegram.WebApp.sendData将数据以消息的形式发送回bot。这使得bot可以在不与任何外部服务器通信的情况下生成响应，bot在接收到数据后可以继续与用户进行通信。

用户可以通过自定义的bot键盘和按钮进行与bot的交互，也可以发送任意格式的文本消息或Telegram支持的任何附件类型：照片和视频、文件、位置、联系人和投票。为了更灵活，bot还可利用HTML5的全部功能来创建用户友好的输入界面。

您可以发送一个打开指定URL的web_app类型的KeyboardButton，以启动小程序。

该方案适用于：

• 自定义数据输入界面，例如个性化的日期选择日历；具有高级搜索选项的列表中选择数据；让用户“旋转轮盘”并选择其中一个可用选项的随机数等。
• 不依赖于特定机器人的可复用组件。

4.2 内联按钮 inline button

对于像 @DurgerKingBot 这样高互动性的小程序，可以使用web_app类型的内联按钮Inline Keyboard Button，该按钮可以获取基本用户信息，并可用于代表用户向bot的发送聊天消息。

如果仅接收文本数据不满足需求或者需要更高级和个性化的界面，可以使用web_app类型的Inline Keyboard Button打开一个小程序。

从按钮中，小程序将打开指定的URL。除了用户的主题设置外，它还将接收基本用户信息（id、name、username、language_code）和会话的唯一标识符query_id，该标识符允许小程序代表用户向bot发送消息。

Bot可以调用Bot API的answerWebAppQuery方法，将用户发来的内联消息发送回机器人并关闭小程序。在接收到消息后，机器人可以继续与用户进行通信。

该方案适用于：

• 成熟度高的Web服务和各种集成。
• 可能性几乎无限的应用。

4.3 机器人菜单按钮 menu button

可以从Telegram的自定义菜单按钮启动小程序。这只是提供了一种更快捷的访问小程序的方式，除此之外与从内联按钮启动小程序完全相同。

默认情况下，与机器人的聊天会通过一个方便的菜单按钮，提供快速访问所有列出的命令。从Bot API 6.0开始，可以使用该按钮来启动小程序。

配置菜单按钮，您需要指定它应显示的文本和小程序的URL。有两种设置这些参数的方式：

• 为所有用户定义按钮，使用 @BotFather（使用/setmenubutton命令或Bot Settings > Menu Button）。

• 为所有用户和特定用户自定义按钮，请使用Bot API的setChatMenuButton方法。例如，根据用户的语言更改按钮文本，或者根据用户在您的机器人中的设置显示不同小程序的链接。

除配置方法不同之外，通过菜单按钮打开的小程序的工作方式与使用内联按钮完全相同。

@DurgerKingBot允许从内联按钮和菜单按钮启动小程序。

4.4 内联结果按钮模式 inline mode

通过web_app类型的Inline Query Results Button启动的小程序可以在内联模式下的任何地方使用。用户可以在Web界面中创建内容，然后通过内联模式无缝地将其发送到当前聊天中。

您可以在answerInlineQuery方法中使用button参数，在内联结果的上方或替代位置显示一个特殊的切换到小程序按钮。该按钮将打开指定URL的小程序。完成后，您可以调用Telegram.WebApp.switchInlineQuery方法将用户发送回内联模式。

内联小程序无法访问聊天内容， 通过这种方式打开的小程序无法读取消息或代表用户发送新消息。要发送消息，必须将用户重定向到内联模式，并主动选择一个结果。

该方案适用于：

• 完全成熟的内联模式下的Web服务和集成。

4.5 直接链接 direct link

可以从任何聊天中的直接链接启动小程序。它们支持startapp参数，并且了解当前聊天的上下文。

您可以使用直接链接直接在当前聊天中打开小程序。如果链接中包含非空的startapp参数，它将传递给小程序的start_param属性和GET参数tgWebAppStartParam。

在此模式下，小程序可以使用chat_type和chat_instance参数来跟踪当前聊天的上下文。这为多个聊天成员的并发和共享使用提供了支持，如用于创建实时白板、群组订单、多人游戏和类似的应用程序。

从直接链接打开的小程序无法访问聊天内容， 它们无法读取消息或代表用户发送新消息。要发送消息，必须将用户重定向到内联模式，并主动选择一个结果。

例子：

• https://t.me/botusername/appname
• https://t.me/botusername/appname?startapp=command

适用于：

• 任何用户可以一次点击打开的完全成熟的Web服务。
• 基于协作、多人游戏或团队合作的聊天上下文服务。

4.6 附件菜单启动 attatchment link

小程序可以请求直接添加到用户的附件菜单中，使它们可以在任何类型的聊天中快速启动。您可以配置您的小程序在哪些类型的聊天中可以从附件菜单中启动（私聊、群组、超级群组或频道）。

目前，附件菜单集成仅适用于Telegram广告平台上的主要广告商。但是，在测试服务器环境中，所有机器人都可以使用它。

要为您的机器人启用此功能，请从测试服务器上的帐户打开@BotFather，并发送/setattach命令，或转到Bot Settings > Configure Attachment Menu。然后，指定将通过附件菜单中的图标启动小程序的URL。

您可以使用@BotFather向您的小程序上下文菜单添加一个“设置”项。当用户从菜单中选择此选项时，您的机器人将收到一个settingsButtonClicked事件。

除了用户的主题设置外，机器人还将接收到用户的基本信息（id、name、username、language_code、photo），以及与聊天伙伴的公共信息（id、name、username、photo）或聊天信息（id、title、username、photo），以及用于Web会话的唯一标识符query_id，该标识符允许以打开机器人的用户的身份向聊天发送任何类型的消息。

机器人可以调用Bot API的answerWebAppQuery方法，将来自用户的内联消息通过机器人发送到启动该机器人的聊天，并关闭小程序。

您可以在此处阅读有关将机器人添加到附件菜单的更多信息。

5. 初始化小程序

5.1 连接库

在前端脚本的<head>标签中放置telegram-web-app.js脚本，使用以下代码：

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

5.2 类 Class

5.2.1 WebApp Class

一旦脚本连接成功，将可使用window.Telegram.WebApp对象，该对象具有以下属性：

WebApp方法：

5.2.2 ThemeParams Class

小程序可以实时调整界面的外观以与Telegram匹配。该对象包含用户当前的主题设置：

上述属性都可选。

5.2.3 PopupParams Class

用于原生弹窗

5.2.4 ScanQrPopupParams Class

用于系统原生的二维码扫描对象

5.2.5 PopupButton Class

用于系统原生的弹出按钮

5.2.6 BackButton Class

该对象控制返回按钮，该按钮可以显示在Telegram界面中小程序的标题栏中。

方法：

5.2.7 MainButton Class

主按钮位于电报输入框下方。

方法：

5.2.8 HapticFeedback Class

触感反馈

5.2.9 CloudStorage Class

只支持6.9+版本。

上述所有方法都会返回CloudStorage对象。

5.2.10 WebAppInitData Class

该对象定义了在打开小程序时传递给它的数据。如果小程序是从键盘按钮或内联模式启动的，则该对象为空。

5.2.11 WebAppUser Class

5.2.12 WebAppChat Class

5.3 验证小程序收到的消息

为了验证通过小程序接收到的数据，应该将数据从Telegram.WebApp.initData发送到机器人的后端。该数据是一个查询字符串，由一系列key-value对组成。

您可以通过将接收到的hash参数与使用密钥生成的数据检查字符串的HMAC-SHA-256签名的十六进制表示进行比较，来验证接收到的数据的完整性。密钥是将机器人的令牌与常量字符串WebAppData一起作为密钥生成的HMAC-SHA-256签名。

数据检查字符串是所有接收到的属性按字母顺序排序的字符串，格式为key=<value>，使用换行符（’\n’，0x0A）作为分隔符，例如'auth_date=<auth_date>\nquery_id=<query_id>\nuser=<user>'。

完整的检查过程可能如下所示：

data_check_string = ...
secret_key = HMAC_SHA256(<bot_token>, "WebAppData")
if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
  // 数据来自Telegram
}

为了防止使用过时的数据，您还可以额外检查auth_date属性，该属性包含小程序接收到数据的Unix时间戳。

一旦验证通过，数据可以在您的服务器上使用。复杂的数据类型表示为JSON序列化对象。

5.4 小程序事件

小程序可以从Telegram接收事件，并使用Telegram.WebApp.onEvent(eventType, eventHandler)方法处理程序。在eventHandler中，this对象指的是Telegram.WebApp，发送到处理程序的参数集取决于事件类型。以下是可能的事件列表：

5.5 Adding Bots to the Attachment Menu

6. 调试小程序

6.1 在测试环境中使用机器人

要登录到测试环境，请使用以下任一方法：

• iOS：点击设置图标10次 > 账户 > 登录到另一个账户 > 测试。
• Telegram桌面版：打开 ☰ 设置 > Shift + Alt + 右键单击“添加账户”，然后选择“测试服务器”。
• macOS：点击设置图标10次以打开调试菜单，⌘ + 单击“添加账户”，然后通过手机号码登录。

测试环境与主要环境完全分离，因此您需要创建一个新的用户账户和一个新的机器人（通过@BotFather）。

在收到您的机器人令牌后，您可以按以下格式向Bot API发送请求：

https://api.telegram.org/bot<token>/test/METHOD_NAME

注意：在使用测试环境时，您可以使用不带TLS的HTTP链接来测试您的小程序。

6.2 小程序调试模式

使用以下工具来Debug小程序：

Android

• 在您的设备上启用USB调试。
• 在Telegram设置中，向下滚动，按住版本号两次。
• 在调试设置中选择启用WebView调试。
• 将手机连接到计算机，并在Chrome中打开chrome://inspect/#devices - 当您在手机上启动小程序时，您会在那里看到它。

Windows和Linux上的Telegram桌面版

• 下载并启动Telegram桌面版的Beta版本。
• 转到设置 > 高级 > 实验设置 > 启用WebView检查。
• 右键单击WebView并选择检查元素。

macOS上的Telegram

• 下载并启动Telegram macOS的Beta版本
• 快速点击5次设置图标以打开调试菜单，并启用调试Web App。
• 右键单击小程序并选择检查元素。