Telegram Bot API sendChecklist 使用教程

<?php
/**
 * 使用 Telegram Bot API 发送基本任务清单
 * @param string $botToken Bot Token
 * @param int|string $chatId 聊天 ID
 * @param string $title 清单标题
 * @param array $tasks 任务列表
 * @return array 响应结果
 */
function sendBasicChecklist($botToken, $chatId, $title, $tasks) {
    $url = "https://api.telegram.org/bot{$botToken}/sendChecklist";
    
    // 构建任务数组
    $inputTasks = [];
    foreach ($tasks as $task) {
        $inputTasks[] = [
            'text' => $task['text'],
            'is_done' => $task['is_done'] ?? false
        ];
    }
    
    $data = [
        'chat_id' => $chatId,
        'title' => $title,
        'tasks' => json_encode($inputTasks)
    ];
    
    $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
$title = "今日待办事项";
$tasks = [
    ['text' => '完成项目报告', 'is_done' => false],
    ['text' => '参加团队会议', 'is_done' => false],
    ['text' => '回复客户邮件', 'is_done' => true],
    ['text' => '更新项目文档', 'is_done' => false]
];

$result = sendBasicChecklist($botToken, $chatId, $title, $tasks);

if ($result['ok']) {
    echo "任务清单发送成功！消息 ID: " . $result['result']['message_id'];
} else {
    echo "发送失败：" . $result['description'];
}
?>
```

### 2.3 发送带高级选项的任务清单

```php
<?php
/**
 * 使用 Telegram Bot API 发送带高级选项的任务清单
 * @param string $botToken Bot Token
 * @param int|string $chatId 聊天 ID
 * @param string $title 清单标题
 * @param array $tasks 任务列表
 * @param array $options 高级选项
 * @return array 响应结果
 */
function sendAdvancedChecklist($botToken, $chatId, $title, $tasks, $options = []) {
    $url = "https://api.telegram.org/bot{$botToken}/sendChecklist";
    
    // 构建任务数组
    $inputTasks = [];
    foreach ($tasks as $task) {
        $inputTask = [
            'text' => $task['text'],
            'is_done' => $task['is_done'] ?? false
        ];
        $inputTasks[] = $inputTask;
    }
    
    $data = [
        'chat_id' => $chatId,
        'title' => $title,
        'tasks' => json_encode($inputTasks)
    ];
    
    // 合并高级选项
    $allowedOptions = [
        'business_connection_id', 'message_thread_id', 'disable_notification',
        'protect_content', 'reply_to_message_id', 'allow_sending_without_reply',
        'reply_markup', 'direct_messages_topic_id', 'suggested_post_parameters'
    ];
    
    foreach ($allowedOptions as $option) {
        if (isset($options[$option])) {
            $data[$option] = $options[$option];
        }
    }
    
    $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;
$title = "项目开发计划";
$tasks = [
    ['text' => '需求分析与设计', 'is_done' => true],
    ['text' => '前端开发', 'is_done' => true],
    ['text' => '后端开发', 'is_done' => false],
    ['text' => '测试与调试', 'is_done' => false],
    ['text' => '部署与上线', 'is_done' => false]
];

$result = sendAdvancedChecklist(
    $botToken,
    $chatId,
    $title,
    $tasks,
    [
        'disable_notification' => false,
        'protect_content' => true,
        'reply_to_message_id' => null, // 可设置回复的消息 ID
        'allow_sending_without_reply' => true
    ]
);

if ($result['ok']) {
    echo "高级任务清单发送成功！消息 ID: " . $result['result']['message_id'];
} else {
    echo "发送失败：" . $result['description'];
}
?>
```

### 2.4 编辑已发送的任务清单

```php
<?php
/**
 * 使用 Telegram Bot API 编辑已发送的任务清单
 * @param string $botToken Bot Token
 * @param int|string $chatId 聊天 ID
 * @param int $messageId 清单消息 ID
 * @param string $title 新的清单标题（可选）
 * @param array $tasks 新的任务列表（可选）
 * @return array 响应结果
 */
function editChecklist($botToken, $chatId, $messageId, $title = null, $tasks = null) {
    $url = "https://api.telegram.org/bot{$botToken}/editMessageChecklist";
    
    $data = [
        'chat_id' => $chatId,
        'message_id' => $messageId
    ];
    
    // 添加可选参数
    if ($title !== null) {
        $data['title'] = $title;
    }
    
    if ($tasks !== null) {
        $inputTasks = [];
        foreach ($tasks as $task) {
            $inputTask = [
                'text' => $task['text'],
                'is_done' => $task['is_done'] ?? false
            ];
            $inputTasks[] = $inputTask;
        }
        $data['tasks'] = json_encode($inputTasks);
    }
    
    $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;
$messageId = 12345; // 已发送的清单消息 ID

// 更新任务状态和标题
$newTitle = "项目开发计划（更新）";
$updatedTasks = [
    ['text' => '需求分析与设计', 'is_done' => true],
    ['text' => '前端开发', 'is_done' => true],
    ['text' => '后端开发', 'is_done' => true], // 标记为已完成
    ['text' => '测试与调试', 'is_done' => true], // 标记为已完成
    ['text' => '部署与上线', 'is_done' => false],
    ['text' => '项目验收', 'is_done' => false] // 新增任务
];

$result = editChecklist($botToken, $chatId, $messageId, $newTitle, $updatedTasks);

if ($result['ok']) {
    echo "任务清单编辑成功！";
} else {
    echo "编辑失败：" . $result['description'];
}
?>
```

### 2.5 完整的 Telegram Bot 清单发送类

```php
<?php
class TelegramChecklistBot {
    private $botToken;
    
    /**
     * 构造函数
     * @param string $botToken Bot Token
     */
    public function __construct($botToken) {
        $this->botToken = $botToken;
    }
    
    /**
     * 发送基本任务清单
     * @param int|string $chatId 聊天 ID
     * @param string $title 清单标题
     * @param array $tasks 任务列表
     * @return array 响应结果
     */
    public function sendChecklist($chatId, $title, $tasks) {
        return $this->sendAdvancedChecklist($chatId, $title, $tasks, []);
    }
    
    /**
     * 发送带高级选项的任务清单
     * @param int|string $chatId 聊天 ID
     * @param string $title 清单标题
     * @param array $tasks 任务列表
     * @param array $options 高级选项
     * @return array 响应结果
     */
    public function sendAdvancedChecklist($chatId, $title, $tasks, $options = []) {
        $url = "https://api.telegram.org/bot{$this->botToken}/sendChecklist";
        
        // 验证任务格式
        if (!is_array($tasks) || empty($tasks)) {
            return [
                'ok' => false,
                'error_code' => 400,
                'description' => '任务列表不能为空且必须是数组'
            ];
        }
        
        // 构建任务数组
        $inputTasks = [];
        foreach ($tasks as $task) {
            if (!isset($task['text']) || empty($task['text'])) {
                return [
                    'ok' => false,
                    'error_code' => 400,
                    'description' => '每个任务必须包含text字段'
                ];
            }
            
            $inputTask = [
                'text' => $task['text'],
                'is_done' => isset($task['is_done']) ? (bool)$task['is_done'] : false
            ];
            $inputTasks[] = $inputTask;
        }
        
        $data = [
            'chat_id' => $chatId,
            'title' => $title,
            'tasks' => json_encode($inputTasks)
        ];
        
        // 合并高级选项
        $allowedOptions = [
            'business_connection_id', 'message_thread_id', 'disable_notification',
            'protect_content', 'reply_to_message_id', 'allow_sending_without_reply',
            'reply_markup', 'direct_messages_topic_id', 'suggested_post_parameters'
        ];
        
        foreach ($allowedOptions as $option) {
            if (isset($options[$option])) {
                $data[$option] = $options[$option];
            }
        }
        
        return $this->sendRequest($url, $data);
    }
    
    /**
     * 编辑已发送的任务清单
     * @param int|string $chatId 聊天 ID
     * @param int $messageId 清单消息 ID
     * @param string $title 新的清单标题（可选）
     * @param array $tasks 新的任务列表（可选）
     * @return array 响应结果
     */
    public function editChecklist($chatId, $messageId, $title = null, $tasks = null) {
        $url = "https://api.telegram.org/bot{$this->botToken}/editMessageChecklist";
        
        $data = [
            'chat_id' => $chatId,
            'message_id' => $messageId
        ];
        
        // 添加可选参数
        if ($title !== null) {
            $data['title'] = $title;
        }
        
        if ($tasks !== null) {
            // 验证任务格式
            if (!is_array($tasks) || empty($tasks)) {
                return [
                    'ok' => false,
                    'error_code' => 400,
                    'description' => '任务列表不能为空且必须是数组'
                ];
            }
            
            $inputTasks = [];
            foreach ($tasks as $task) {
                if (!isset($task['text']) || empty($task['text'])) {
                    return [
                        'ok' => false,
                        'error_code' => 400,
                        'description' => '每个任务必须包含text字段'
                    ];
                }
                
                $inputTask = [
                    'text' => $task['text'],
                    'is_done' => isset($task['is_done']) ? (bool)$task['is_done'] : false
                ];
                $inputTasks[] = $inputTask;
            }
            $data['tasks'] = json_encode($inputTasks);
        }
        
        return $this->sendRequest($url, $data);
    }
    
    /**
     * 发送 HTTP 请求
     * @param string $url 请求 URL
     * @param array $data 请求数据
     * @return array 响应结果
     */
    private function sendRequest($url, $data) {
        $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);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
        
        $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);
    }
}

// 使用示例
$botToken = "YOUR_BOT_TOKEN";
$bot = new TelegramChecklistBot($botToken);
$chatId = 123456789;

// 发送任务清单
echo "发送任务清单...\n";
$tasks = [
    ['text' => '准备会议材料', 'is_done' => false],
    ['text' => '安排会议时间', 'is_done' => true],
    ['text' => '发送会议邀请', 'is_done' => true],
    ['text' => '准备演示幻灯片', 'is_done' => false]
];

$result = $bot->sendAdvancedChecklist(
    $chatId,
    "会议准备清单",
    $tasks,
    [
        'disable_notification' => false,
        'protect_content' => false
    ]
);

if ($result['ok']) {
    echo "任务清单发送成功！消息 ID: " . $result['result']['message_id'] . "\n";
    $messageId = $result['result']['message_id'];
    
    // 示例：更新任务清单（实际使用时取消注释）
    // sleep(5); // 等待5秒
    // echo "更新任务清单...\n";
    // $updatedTasks = $tasks;
    // $updatedTasks[0]['is_done'] = true; // 标记第一个任务为已完成
    // $updatedTasks[] = ['text' => '检查设备是否正常', 'is_done' => false]; // 添加新任务
    // 
    // $editResult = $bot->editChecklist($chatId, $messageId, "会议准备清单（更新）", $updatedTasks);
    // if ($editResult['ok']) {
    //     echo "任务清单更新成功！\n";
    // } else {
    //     echo "更新失败：" . $editResult['description'] . "\n";
    // }
} else {
    echo "发送失败：" . $result['description'] . "\n";
}
?>