弹窗交互

Mini App 提供多种弹窗和交互方法，用于显示消息、扫描二维码、读取剪贴板、处理支付等。

弹窗

showPopup

Telegram.WebApp.showPopup(params, callback)

显示自定义弹窗。

参数	类型	必填	描述
params	Object	是	弹窗参数
params.title	String	否	弹窗标题，最多 64 个字符
params.message	String	是	弹窗消息文本，最多 256 个字符
params.buttons	Array	否	按钮列表，最多 3 个按钮
callback	Function	否	关闭回调，参数为按钮 ID

按钮对象

字段	类型	必填	描述
id	String	否	按钮 ID，最多 64 个字符，默认为空字符串
type	String	否	按钮类型："default"、"ok"、"close"、"cancel"、"destructive"
text	String	条件	按钮文字（type 为 "default" 或 "destructive" 时必填）

Telegram.WebApp.showPopup({
  title: '确认操作',
  message: '确定要执行此操作吗？',
  buttons: [
    { id: 'confirm', type: 'default', text: '确认' },
    { id: 'cancel', type: 'cancel' }
  ]
}, (buttonId) => {
  if (buttonId === 'confirm') {
    // 用户点击了确认
  }
});

showAlert

Telegram.WebApp.showAlert(message, callback)

显示警告弹窗，包含一个"确定"按钮。

参数	类型	必填	描述
message	String	是	警告消息文本
callback	Function	否	用户点击"确定"后的回调

Telegram.WebApp.showAlert('操作成功！', () => {
  console.log('用户已确认');
});

showConfirm

Telegram.WebApp.showConfirm(message, callback)

显示确认弹窗，包含"确定"和"取消"两个按钮。

参数	类型	必填	描述
message	String	是	确认消息文本
callback	Function	否	回调函数，参数 confirmed（Boolean）表示用户是否点击了确定

Telegram.WebApp.showConfirm('确定要删除吗？', (confirmed) => {
  if (confirmed) {
    deleteItem();
  }
});

QR 码扫描

showScanQrPopup

Telegram.WebApp.showScanQrPopup(params, callback)

显示 QR 码扫描弹窗。Bot API 6.9+

参数	类型	必填	描述
params	Object	否	扫描参数
params.text	String	否	扫描界面的提示文字
callback	Function	否	扫描成功回调，参数为扫描到的文本。返回 true 关闭弹窗

Telegram.WebApp.showScanQrPopup({ text: '扫描二维码' }, (text) => {
  console.log('扫描结果:', text);
  return true; // 关闭扫描弹窗
});

closeScanQrPopup

Telegram.WebApp.closeScanQrPopup()

关闭 QR 码扫描弹窗。Bot API 6.9+

剪贴板

readTextFromClipboard

Telegram.WebApp.readTextFromClipboard(callback)

读取剪贴板中的文本内容。Bot API 6.9+

参数	类型	必填	描述
callback	Function	否	回调函数，参数 text（String | null）为剪贴板内容

Telegram.WebApp.readTextFromClipboard((text) => {
  if (text) {
    console.log('剪贴板内容:', text);
  }
});

发票与支付

openInvoice

Telegram.WebApp.openInvoice(url, callback)

打开发票支付界面。

参数	类型	必填	描述
url	String	是	发票链接
callback	Function	否	支付完成回调，参数 status 为支付状态

Telegram.WebApp.openInvoice('https://t.me/$invoice_id', (status) => {
  if (status === 'paid') {
    showSuccess('支付成功');
  } else if (status === 'cancelled') {
    showInfo('支付已取消');
  }
});

支付状态值：

状态	描述
paid	支付成功
cancelled	用户取消支付
failed	支付失败
pending	支付处理中

分享

shareToStory

Telegram.WebApp.shareToStory(media_url, params)

分享内容到故事。Bot API 7.8+

参数	类型	必填	描述
media_url	String	是	媒体文件 URL
params	Object	否	分享参数
params.text	String	否	附加文字
params.widget_link	Object	否	小组件链接
params.widget_link.url	String	否	链接 URL
params.widget_link.name	String	否	显示名称

shareMessage

Telegram.WebApp.shareMessage(msg_id, callback)

分享 Bot 预先准备的消息。Bot API 8.0+

参数	类型	必填	描述
msg_id	String	是	预先准备的消息 ID
callback	Function	否	回调函数，参数 sent（Boolean）

Emoji 状态

setEmojiStatus

Telegram.WebApp.setEmojiStatus(custom_emoji_id, params, callback)

为用户设置自定义 emoji 状态。Bot API 8.0+

参数	类型	必填	描述
custom_emoji_id	String	是	自定义 emoji ID
params	Object	否	参数
params.duration	Integer	否	持续时间（秒）
callback	Function	否	回调函数，参数 set（Boolean）

requestEmojiStatusAccess

Telegram.WebApp.requestEmojiStatusAccess(callback)

请求设置 emoji 状态的权限。Bot API 8.0+

参数	类型	必填	描述
callback	Function	否	回调函数，参数 granted（Boolean）

文件下载

downloadFile

Telegram.WebApp.downloadFile(params, callback)

请求下载文件。Bot API 8.0+

参数	类型	必填	描述
params	Object	是	下载参数
params.url	String	是	文件 URL
params.file_name	String	是	建议的文件名
callback	Function	否	回调函数，参数 accepted（Boolean）

Telegram.WebApp.downloadFile({
  url: 'https://example.com/report.pdf',
  file_name: 'report.pdf'
}, (accepted) => {
  if (accepted) {
    console.log('用户已同意下载');
  }
});

权限请求

requestWriteAccess

Telegram.WebApp.requestWriteAccess(callback)

请求向用户发送消息的写入权限。Bot API 6.9+

参数	类型	必填	描述
callback	Function	否	回调函数，参数 granted（Boolean）

requestContact

Telegram.WebApp.requestContact(callback)

请求用户的联系人信息（手机号）。Bot API 6.9+

参数	类型	必填	描述
callback	Function	否	回调函数，参数 sent（Boolean）