Метод postStory | Telegram Bot API

Описание

Публикует историю от имени управляемого бизнес-аккаунта. Требуется право бизнес-бота can_manage_stories. В случае успеха возвращает Story.

Параметр	Тип	Обязательный	Описание
business_connection_id	String	Да	Уникальный идентификатор бизнес-подключения
content	InputStoryContent	Да	Содержание истории
active_period	Integer	Да	Период в секундах, после которого история перемещается в архив; должен быть одним из значений `6 * 3600`, `12 * 3600`, `86400` или `2 * 86400`
caption	String	Опционально	Подпись к истории, 0-2048 символов после обработки сущностей
parse_mode	String	Опционально	Режим обработки сущностей в подписи истории. Подробнее см. параметры форматирования.
caption_entities	Array of MessageEntity	Опционально	Сериализованный в JSON список специальных сущностей, появляющихся в подписи, которые можно указать вместо parse_mode
areas	Array of StoryArea	Опционально	Сериализованный в JSON список кликабельных областей, отображаемых в истории
post_to_chat_page	Boolean	Опционально	Передайте True, чтобы история оставалась доступной после истечения срока
protect_content	Boolean	Опционально	Передайте True, если содержимое истории должно быть защищено от пересылки и создания скриншотов

Примеры

php

<?php

// Пример использования метода postStory Telegram Bot API

// Конфигурация
$botToken = 'YOUR_BOT_TOKEN';
$businessConnectionId = 'YOUR_BUSINESS_CONNECTION_ID';
$apiUrl = "https://api.telegram.org/bot{$botToken}/postStory";

// 1. Пример с фото-сторисом
$photoStoryData = [
    'business_connection_id' => $businessConnectionId,
    'content' => [
        'type' => 'photo',
        'media' => 'https://example.com/path/to/photo.jpg' // или file_id существующего фото
    ],
    'active_period' => 86400, // 24 часа
    'caption' => '✨ Новый продукт уже в продаже! #новинка',
    'parse_mode' => 'HTML',
    'protect_content' => true
];

// 2. Пример с видео-сторисом
$videoStoryData = [
    'business_connection_id' => $businessConnectionId,
    'content' => [
        'type' => 'video',
        'media' => 'https://example.com/path/to/video.mp4',
        'thumbnail' => 'https://example.com/path/to/thumbnail.jpg' // опционально
    ],
    'active_period' => 6 * 3600, // 6 часов
    'caption' => 'Закулисные съемки нашего производства 🎬',
    'parse_mode' => 'MarkdownV2',
    'post_to_chat_page' => true
];

// 3. Пример с загруженным файлом (multipart/form-data)
function sendStoryWithUploadedFile($filePath, $isVideo = false) {
    global $botToken, $businessConnectionId;
    
    $type = $isVideo ? 'video' : 'photo';
    $url = "https://api.telegram.org/bot{$botToken}/postStory";
    
    $postData = [
        'business_connection_id' => $businessConnectionId,
        'content' => json_encode(['type' => $type]),
        'active_period' => 12 * 3600,
        'caption' => 'Ежедневное обновление от нашей команды! 👋'
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, [
        'business_connection_id' => $businessConnectionId,
        'content' => json_encode(['type' => $type]),
        'active_period' => '43200',
        'caption' => 'Ежедневное обновление от нашей команды! 👋',
        'media' => new CURLFile($filePath)
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// 4. Пример с интерактивными областями (StoryArea)
$storyWithAreas = [
    'business_connection_id' => $businessConnectionId,
    'content' => [
        'type' => 'photo',
        'media' => 'https://example.com/path/to/product.jpg'
    ],
    'active_period' => 86400,
    'caption' => 'Нажми на продукт, чтобы узнать больше!',
    'areas' => [
        [
            'position' => [
                'x' => 0.5,
                'y' => 0.5,
                'width' => 0.3,
                'height' => 0.3,
                'rotation' => 0
            ],
            'type' => 'link',
            'url' => 'https://yourwebsite.com/product123'
        ],
        [
            'position' => [
                'x' => 0.8,
                'y' => 0.2,
                'width' => 0.15,
                'height' => 0.1,
                'rotation' => 0
            ],
            'type' => 'mention',
            'user_id' => 123456789 // ID пользователя для упоминания
        ]
    ]
];

// 5. Базовая функция отправки сторис
function postStory($data) {
    global $apiUrl;
    
    // Преобразуем массив в JSON
    $jsonData = json_encode($data);
    
    // Настраиваем cURL запрос
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($jsonData)
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 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' => "cURL Error: {$error}"];
    }
    
    curl_close($ch);
    
    // Парсим ответ
    $result = json_decode($response, true);
    
    if ($httpCode !== 200) {
        return [
            'ok' => false,
            'error_code' => $result['error_code'] ?? $httpCode,
            'description' => $result['description'] ?? 'Unknown error'
        ];
    }
    
    return $result;
}

// Пример использования базовой функции
try {
    // Отправляем фото-сторис
    $result = postStory($photoStoryData);
    
    if ($result['ok']) {
        $story = $result['result'];
        echo "Story posted successfully! ID: {$story['id']}\n";
        echo "Expires at: " . date('Y-m-d H:i:s', $story['expire_date']) . "\n";
    } else {
        echo "Error: {$result['description']}\n";
        if (isset($result['error_code'])) {
            echo "Error code: {$result['error_code']}\n";
        }
    }
} catch (Exception $e) {
    echo "Exception: " . $e->getMessage() . "\n";
}

// 6. Валидация active_period
function validateActivePeriod($seconds) {
    $allowedPeriods = [
        6 * 3600,    // 6 часов
        12 * 3600,   // 12 часов
        86400,       // 24 часа
        2 * 86400    // 48 часов
    ];
    
    if (!in_array($seconds, $allowedPeriods)) {
        throw new InvalidArgumentException(
            'active_period must be one of: 21600 (6h), 43200 (12h), 86400 (24h), 172800 (48h)'
        );
    }
    
    return $seconds;
}

// Пример с валидацией
$validatedData = $photoStoryData;
$validatedData['active_period'] = validateActivePeriod(43200); // 12 часов

?>

python

import asyncio
from telegram import Bot, InputFile, InputStoryContentPhoto, InputStoryContentVideo, StoryArea, StoryAreaLocation, StoryAreaText, StoryAreaMention, StoryAreaLink
from telegram.constants import ParseMode

async def post_story_example():
    bot = Bot(token="YOUR_BOT_TOKEN")
    
    # Example 1: Posting a photo story
    try:
        # Create InputStoryContent for photo
        with open("story_photo.jpg", "rb") as photo_file:
            photo_content = InputStoryContentPhoto(
                photo=InputFile(photo_file),
                add_animation=False  # Optional: add animation to photo
            )
        
        # Create story areas (clickable areas)
        areas = [
            StoryArea(
                position=StoryArea.Position(x=0.5, y=0.5, width=0.3, height=0.3),
                location=StoryAreaLocation(
                    latitude=40.7128,
                    longitude=-74.0060,
                    horizontal_accuracy=50
                )
            ),
            StoryArea(
                position=StoryArea.Position(x=0.2, y=0.8, width=0.4, height=0.1),
                text=StoryAreaText(
                    text="Click here!",
                    font_size=16,
                    color="#FF0000"
                )
            )
        ]
        
        # Post the story
        story = await bot.post_story(
            business_connection_id="YOUR_BUSINESS_CONNECTION_ID",
            content=photo_content,
            active_period=86400,  # 24 hours
            caption="Check out our new product! 🚀",
            parse_mode=ParseMode.HTML,
            areas=areas,
            protect_content=True
        )
        
        print(f"Story posted successfully! Story ID: {story.story_id}")
        
    except Exception as e:
        print(f"Error posting photo story: {e}")
    
    # Example 2: Posting a video story
    try:
        with open("story_video.mp4", "rb") as video_file:
            video_content = InputStoryContentVideo(
                video=InputFile(video_file),
                duration=15,  # Video duration in seconds
                supports_streaming=True
            )
        
        # Post video story with mention area
        story = await bot.post_story(
            business_connection_id="YOUR_BUSINESS_CONNECTION_ID",
            content=video_content,
            active_period=6 * 3600,  # 6 hours
            caption="Behind the scenes! 🎬",
            parse_mode=ParseMode.MARKDOWN_V2,
            caption_entities=[],  # Can specify entities manually
            areas=[
                StoryArea(
                    position=StoryArea.Position(x=0.1, y=0.1, width=0.8, height=0.1),
                    mention=StoryAreaMention(
                        user_id=123456789,  # User to mention
                        text="@username"
                    )
                )
            ],
            post_to_chat_page=True,  # Keep accessible after expiration
            protect_content=False
        )
        
        print(f"Video story posted! Story ID: {story.story_id}")
        
    except Exception as e:
        print(f"Error posting video story: {e}")

# Run the example
if __name__ == "__main__":
    asyncio.run(post_story_example())

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

API 9.0. Добавлен метод postStory

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

Story - Объект, представляющий историю, опубликованную в чате Telegram.
InputStoryContent - Объект, описывающий контент (фото или видео) для публикации в виде истории.
MessageEntity - Объект MessageEntity представляет специальную форматированную сущность в тексте сообщения, такую как упоминания, хэштеги, ссылки или стилизованный текст.
StoryArea - Объект описывает интерактивную область на медиафайле в историях Telegram.