# Telegram Bot API Paid Broadcasts 使用教程
## 1. Paid Broadcasts 用途介绍
Paid Broadcasts（付费广播）是 Telegram Bot API 提供的一项功能，允许机器人通过 `sendPaidMedia` 方法发送付费媒体内容。当用户查看这些内容时，机器人可以获得 Telegram Stars 作为报酬。
**主要用途：**
- 实现内容付费功能，让用户通过 Telegram Stars 解锁或查看特定媒体内容
- 作为机器人开发者的一种 monetization（ monetization）方式
- 适用于需要向用户提供优质付费内容的场景，如教育材料、独家资讯、创意作品等
**核心特点：**
- 支持多种媒体类型：照片、视频、音频、文档等
- 与现有的消息发送机制无缝集成
- 提供完整的交易状态跟踪
- 支持设置不同的价格点，以 Telegram Stars 为计价单位
## 2. 原生 PHP 调用实例
### 2.1 准备工作
确保你的 PHP 环境满足以下要求：
- PHP 5.6 或更高版本
- 已安装 cURL 扩展
- 已创建 Telegram Bot 并获取 Bot Token
### 2.2 基础的 sendPaidMedia 调用
<?php
/**
* 使用 Telegram Bot API 发送付费媒体
* @param string $botToken Bot Token
* @param int $chatId 聊天 ID
* @param string $mediaType 媒体类型: photo, video, audio, document 等
* @param string $mediaUrl 媒体文件的 URL
* @param string $caption 媒体描述文字
* @param int $starCount 所需的 Telegram Stars 数量
* @return array 响应结果
*/
function sendPaidMedia($botToken, $chatId, $mediaType, $mediaUrl, $caption, $starCount) {
$url = "https://api.telegram.org/bot{$botToken}/sendPaidMedia";
$media = [
'type' => $mediaType,
'media' => $mediaUrl
];
$data = [
'chat_id' => $chatId,
'media' => json_encode([$media]),
'star_count' => $starCount,
'caption' => $caption
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// 使用示例
$botToken = "YOUR_BOT_TOKEN";
$chatId = 123456789; // 用户的聊天 ID
$mediaType = "photo";
$mediaUrl = "https://example.com/paid-content.jpg";
$caption = "这是一个付费照片示例，需要 5 颗 Telegram Stars 才能查看。";
$starCount = 5; // 价格：5 Telegram Stars
$result = sendPaidMedia($botToken, $chatId, $mediaType, $mediaUrl, $caption, $starCount);
if ($result['ok']) {
echo "付费媒体发送成功！";
echo "消息 ID: " . $result['result']['message_id'];
echo "媒体组 ID: " . $result['result']['paid_media']['media_group_id'];
} else {
echo "发送失败：" . $result['description'];
}
?>
```
### 2.3 发送多个付费媒体（媒体组）
```php
<?php
/**
* 使用 Telegram Bot API 发送付费媒体组
* @param string $botToken Bot Token
* @param int $chatId 聊天 ID
* @param array $mediaList 媒体列表数组
* @param int $starCount 所需的 Telegram Stars 数量
* @return array 响应结果
*/
function sendPaidMediaGroup($botToken, $chatId, $mediaList, $starCount) {
$url = "https://api.telegram.org/bot{$botToken}/sendPaidMedia";
$data = [
'chat_id' => $chatId,
'media' => json_encode($mediaList),
'star_count' => $starCount
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
// 使用示例
$botToken = "YOUR_BOT_TOKEN";
$chatId = 123456789;
// 构建媒体列表
$mediaList = [
[
'type' => 'photo',
'media' => 'https://example.com/paid-photo1.jpg'
],
[
'type' => 'photo',
'media' => 'https://example.com/paid-photo2.jpg'
],
[
'type' => 'video',
'media' => 'https://example.com/paid-video.mp4',
'caption' => '这是一个付费媒体组示例，包含两张照片和一个视频。'
]
];
$starCount = 10; // 价格：10 Telegram Stars
$result = sendPaidMediaGroup($botToken, $chatId, $mediaList, $starCount);
if ($result['ok']) {
echo "付费媒体组发送成功！";
echo "消息 ID: " . $result['result']['message_id'];
echo "媒体组 ID: " . $result['result']['paid_media']['media_group_id'];
} else {
echo "发送失败：" . $result['description'];
}
?>
```
### 2.4 完整的 Telegram Bot 付费媒体类
```php
<?php
class TelegramPaidMediaBot {
private $botToken;
/**
* 构造函数
* @param string $botToken Bot Token
*/
public function __construct($botToken) {
$this->botToken = $botToken;
}
/**
* 发送付费媒体
* @param int $chatId 聊天 ID
* @param string $mediaType 媒体类型
* @param string $mediaUrl 媒体 URL
* @param string $caption 描述文字
* @param int $starCount Telegram Stars 数量
* @param string|null $parseMode 解析模式: MarkdownV2, HTML, Markdown
* @return array 响应结果
*/
public function sendPaidMedia($chatId, $mediaType, $mediaUrl, $caption, $starCount, $parseMode = null) {
$media = [
'type' => $mediaType,
'media' => $mediaUrl,
'caption' => $caption
];
return $this->sendPaidMediaRequest($chatId, [$media], $starCount, $parseMode);
}
/**
* 发送付费媒体组
* @param int $chatId 聊天 ID
* @param array $mediaList 媒体列表
* @param int $starCount Telegram Stars 数量
* @param string|null $parseMode 解析模式
* @return array 响应结果
*/
public function sendPaidMediaGroup($chatId, $mediaList, $starCount, $parseMode = null) {
return $this->sendPaidMediaRequest($chatId, $mediaList, $starCount, $parseMode);
}
/**
* 发送付费媒体请求
* @param int $chatId 聊天 ID
* @param array $mediaList 媒体列表
* @param int $starCount Telegram Stars 数量
* @param string|null $parseMode 解析模式
* @return array 响应结果
*/
private function sendPaidMediaRequest($chatId, $mediaList, $starCount, $parseMode = null) {
$url = "https://api.telegram.org/bot{$this->botToken}/sendPaidMedia";
$data = [
'chat_id' => $chatId,
'media' => json_encode($mediaList),
'star_count' => $starCount
];
if ($parseMode !== null) {
$data['parse_mode'] = $parseMode;
}
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch)) {
$error = curl_error($ch);
curl_close($ch);
return [
'ok' => false,
'error_code' => $httpCode,
'description' => 'cURL 错误: ' . $error
];
}
curl_close($ch);
return json_decode($response, true);
}
/**
* 获取机器人的 Telegram Stars 余额
* @return array 响应结果
*/
public function getMyStarBalance() {
$url = "https://api.telegram.org/bot{$this->botToken}/getMyStarBalance";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
}
// 使用示例
$botToken = "YOUR_BOT_TOKEN";
$chatId = 123456789;
$bot = new TelegramPaidMediaBot($botToken);
// 发送单个付费媒体
$result1 = $bot->sendPaidMedia(
$chatId,
'photo',
'https://example.com/paid-content.jpg',
'这是一个付费照片示例，使用 MarkdownV2 格式：\*粗体\* _斜体_ [链接](https://example.com)',
5,
'MarkdownV2'
);
if ($result1['ok']) {
echo "付费媒体发送成功！\n";
echo "消息 ID: " . $result1['result']['message_id'] . "\n";
} else {
echo "发送失败：" . $result1['description'] . "\n";
}
// 获取机器人的 Star 余额
$balance = $bot->getMyStarBalance();
if ($balance['ok']) {
echo "机器人当前 Star 余额: " . $balance['result']['star_balance'] . "\n";
}
?>
### 2.5 注意事项
1. **Bot Token 安全**：确保 Bot Token 不被泄露，不要硬编码在前端代码中
2. **媒体文件要求**：确保媒体文件可公开访问，或使用 Telegram 内部文件 ID
3. **价格设置**：根据内容价值合理设置 Telegram Stars 数量
4. **用户体验**：在发送付费媒体前，明确告知用户所需的 Stars 数量和内容价值
5. **响应处理**：总是检查 API 响应的 `ok` 字段，以便正确处理成功和失败情况
6. **交易状态**：通过监听 `message` 事件中的 `paid_media` 字段，可以跟踪用户的查看状态
## 3. 应用场景
- **数字内容销售**：销售照片、视频、音频等数字内容
- **付费教程**：提供付费教育内容，如编程教程、语言学习材料等
- **独家资讯**：发布付费的独家新闻、分析报告等
- **创意作品**：艺术家可以销售自己的创意作品
- **会员内容**：为订阅用户提供专属付费内容
## 4. 运行指南
1. 将以上代码保存为 `.php` 文件
2. 替换 `YOUR_BOT_TOKEN` 为你的实际 Bot Token
3. 替换 `$chatId` 为实际的聊天 ID
4. 确保媒体文件 URL 可公开访问
5. 在命令行或浏览器中运行 PHP 文件
```bash
php telegram-paid-media.php
```
发表评论 取消回复