Метод sendDocument

Описание

Примеры

php

<?php

// Конфигурация
$botToken = 'YOUR_BOT_TOKEN';
$chatId = 'TARGET_CHAT_ID'; // Может быть числовым ID или @username

// Способ 1: Отправка файла по file_id (рекомендуется для уже загруженных файлов)
$fileId = 'AgACAgIAAxkBAAIB...'; // Пример file_id из Telegram
$url1 = "https://api.telegram.org/bot{$botToken}/sendDocument";
$data1 = [
    'chat_id' => $chatId,
    'document' => $fileId,
    'caption' => 'Документ отправлен по file_id',
    'parse_mode' => 'HTML',
    'disable_notification' => false,
    'protect_content' => false,
];

// Способ 2: Отправка файла по URL
$fileUrl = 'https://example.com/sample.pdf';
$data2 = [
    'chat_id' => $chatId,
    'document' => $fileUrl,
    'caption' => 'Документ загружен по URL',
    'parse_mode' => 'Markdown',
];

// Способ 3: Загрузка нового файла через multipart/form-data (используя CURLFile)
$localFilePath = '/path/to/local/file.pdf';
if (file_exists($localFilePath)) {
    $curlFile = new CURLFile($localFilePath, mime_content_type($localFilePath), basename($localFilePath));
    
    $url3 = "https://api.telegram.org/bot{$botToken}/sendDocument";
    $postData = [
        'chat_id' => $chatId,
        'document' => $curlFile,
        'caption' => 'Новый загруженный документ',
        'parse_mode' => 'HTML',
        'disable_content_type_detection' => true,
        'reply_markup' => json_encode([
            'inline_keyboard' => [
                [
                    ['text' => 'Открыть', 'url' => 'https://example.com'],
                    ['text' => 'Удалить', 'callback_data' => 'delete_file']
                ]
            ]
        ])
    ];
    
    // Отправка с загрузкой файла
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url3);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);
    
    $result = json_decode($response, true);
    if ($result['ok']) {
        echo "Файл успешно отправлен. Message ID: " . $result['result']['message_id'];
    } else {
        echo "Ошибка: " . $result['description'];
    }
}

// Универсальная функция отправки
function sendDocument($botToken, $params) {
    $url = "https://api.telegram.org/bot{$botToken}/sendDocument";
    
    // Проверяем, есть ли файл для загрузки
    $hasFile = false;
    foreach ($params as $value) {
        if ($value instanceof CURLFile) {
            $hasFile = true;
            break;
        }
    }
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    if ($hasFile) {
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
    } else {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
    }
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        throw new Exception("HTTP error: {$httpCode}");
    }
    
    return json_decode($response, true);
}

// Пример использования функции с reply_parameters
$params = [
    'chat_id' => $chatId,
    'document' => 'BQACAgIAAxkBAAIB...',
    'caption' => 'Ответ на сообщение',
    'reply_parameters' => json_encode([
        'message_id' => 12345,
        'chat_id' => $chatId,
        'allow_sending_without_reply' => true
    ]),
    'allow_paid_broadcast' => false,
    'message_effect_id' => 'effect_id_here' // Только для приватных чатов
];

try {
    $result = sendDocument($botToken, $params);
    if ($result['ok']) {
        // Обработка успешной отправки
        $messageId = $result['result']['message_id'];
        $documentId = $result['result']['document']['file_id'];
        echo "Документ отправлен. File ID для повторного использования: {$documentId}";
    }
} catch (Exception $e) {
    echo "Ошибка: " . $e->getMessage();
}

?>

python

import requests
from typing import Union, Optional

def send_document(
    bot_token: str,
    chat_id: Union[int, str],
    document: Union[str, bytes],
    business_connection_id: Optional[str] = None,
    message_thread_id: Optional[int] = None,
    direct_messages_topic_id: Optional[int] = None,
    thumbnail: Optional[Union[str, bytes]] = None,
    caption: Optional[str] = None,
    parse_mode: Optional[str] = None,
    caption_entities: Optional[list] = None,
    disable_content_type_detection: Optional[bool] = None,
    disable_notification: Optional[bool] = None,
    protect_content: Optional[bool] = None,
    allow_paid_broadcast: Optional[bool] = None,
    message_effect_id: Optional[str] = None,
    suggested_post_parameters: Optional[dict] = None,
    reply_parameters: Optional[dict] = None,
    reply_markup: Optional[dict] = None
) -> dict:
    """
    Отправляет документ через Telegram Bot API.
    
    Args:
        bot_token: Токен бота
        chat_id: ID чата или username канала
        document: Путь к файлу, file_id или URL
        ... остальные параметры из документации
    
    Returns:
        Ответ от Telegram API
    """
    
    url = f"https://api.telegram.org/bot{bot_token}/sendDocument"
    
    # Определяем, нужно ли отправлять файл через multipart/form-data
    files = {}
    data = {
        'chat_id': chat_id,
    }
    
    # Обработка document
    if isinstance(document, bytes):
        # Локальный файл для загрузки
        files['document'] = document
    elif document.startswith(('http://', 'https://')):
        # URL файла
        data['document'] = document
    else:
        # file_id или путь к файлу
        try:
            # Пробуем открыть как локальный файл
            with open(document, 'rb') as f:
                files['document'] = f.read()
        except (FileNotFoundError, OSError):
            # Если не файл, то считаем file_id
            data['document'] = document
    
    # Обработка thumbnail
    if thumbnail:
        if isinstance(thumbnail, bytes):
            files['thumbnail'] = thumbnail
        elif thumbnail.startswith(('http://', 'https://')):
            data['thumbnail'] = thumbnail
        else:
            try:
                with open(thumbnail, 'rb') as f:
                    files['thumbnail'] = f.read()
            except (FileNotFoundError, OSError):
                data['thumbnail'] = thumbnail
    
    # Добавляем опциональные параметры
    optional_params = {
        'business_connection_id': business_connection_id,
        'message_thread_id': message_thread_id,
        'direct_messages_topic_id': direct_messages_topic_id,
        'caption': caption,
        'parse_mode': parse_mode,
        'caption_entities': caption_entities,
        'disable_content_type_detection': disable_content_type_detection,
        'disable_notification': disable_notification,
        'protect_content': protect_content,
        'allow_paid_broadcast': allow_paid_broadcast,
        'message_effect_id': message_effect_id,
        'suggested_post_parameters': suggested_post_parameters,
        'reply_parameters': reply_parameters,
        'reply_markup': reply_markup
    }
    
    for key, value in optional_params.items():
        if value is not None:
            if isinstance(value, (dict, list)):
                import json
                data[key] = json.dumps(value)
            else:
                data[key] = value
    
    # Отправка запроса
    if files:
        # Multipart запрос для загрузки файлов
        files_dict = {}
        for key, value in files.items():
            files_dict[key] = (f'file_{key}', value)
        
        response = requests.post(url, data=data, files=files_dict)
    else:
        # Обычный JSON запрос
        response = requests.post(url, json=data)
    
    return response.json()

# Примеры использования:

# 1. Отправка по file_id (рекомендуемый способ)
result = send_document(
    bot_token="YOUR_BOT_TOKEN",
    chat_id=123456789,
    document="BQACAgIAAxkBAAIB...",  # file_id документа
    caption="Вот ваш документ!",
    parse_mode="HTML"
)

# 2. Отправка локального файла
with open("document.pdf", "rb") as f:
    result = send_document(
        bot_token="YOUR_BOT_TOKEN",
        chat_id="@my_channel",
        document=f.read(),
        caption="PDF документ",
        disable_notification=True
    )

# 3. Отправка с URL
result = send_document(
    bot_token="YOUR_BOT_TOKEN",
    chat_id=123456789,
    document="https://example.com/document.zip",
    caption="Документ из интернета",
    reply_markup={
        "inline_keyboard": [[
            {"text": "Скачать", "url": "https://example.com/document.zip"}
        ]]
    }
)

# 4. Отправка в тред форума
result = send_document(
    bot_token="YOUR_BOT_TOKEN",
    chat_id=-1001234567890,
    message_thread_id=123,
    document="BQACAgIAAxkBAAIB...",
    caption="Документ для обсуждения",
    protect_content=True
)

# 5. Отправка с миниатюрой
with open("document.pdf", "rb") as doc_file, open("thumb.jpg", "rb") as thumb_file:
    result = send_document(
        bot_token="YOUR_BOT_TOKEN",
        chat_id=123456789,
        document=doc_file.read(),
        thumbnail=thumb_file.read(),
        caption="Документ с превью"
    )

История изменений

• API 5.0. Обновлен метод sendDocument: Добавлен параметр disable_content_type_detection
• API 5.6. Обновлен метод sendDocument: Добавлено поле protect_content
• API 6.3. Обновлен метод sendDocument: Добавлен параметр message_thread_id
• API 6.6. Обновлен метод sendDocument: Переименован параметр thumb в thumbnail
• API 7.0. Обновлен метод sendDocument: Заменены параметры reply_to_message_id и allow_sending_without_reply на reply_parameters
• API 7.4. Обновлен метод sendDocument: Добавлен параметр message_effect_id
• API 7.11. Обновлен метод sendDocument: Добавлен параметр allow_paid_broadcast
• API 9.2. Обновлен метод sendDocument: Добавлен параметр direct_messages_topic_id
• API 9.3. Обновлен метод sendDocument: Поддержан параметр message_thread_id в личных чатах с темами для отправки сообщения в конкретную тему.

Дополнительно

• Message - Это основной объект, представляющий сообщение в Telegram, который содержит информацию об отправителе, чате, контенте (текст, медиа, служебные данные) и различные метаданные.
• InputFile - Объект, представляющий содержимое файла для загрузки через multipart/form-data.
• MessageEntity - Объект MessageEntity представляет специальную форматированную сущность в тексте сообщения, такую как упоминания, хэштеги, ссылки или стилизованный текст.
• SuggestedPostParameters - Объект содержит параметры публикации, предлагаемой ботом, включая цену и дату отправки.
• ReplyParameters - Объект, описывающий параметры для ответа на сообщение, включая идентификатор сообщения, чат, цитирование и дополнительные настройки.
• InlineKeyboardMarkup - Объект для создания встроенной клавиатуры, которая отображается непосредственно в сообщении.
• ReplyKeyboardMarkup - Объект, представляющий пользовательскую клавиатуру с вариантами ответа для ботов Telegram.
• ReplyKeyboardRemove - Объект для удаления пользовательской клавиатуры и возврата к стандартной буквенной клавиатуре в клиентах Telegram.
• ForceReply - Объект ForceReply принудительно отображает интерфейс ответа в клиентах Telegram, упрощая создание пошаговых диалогов с ботом.