Перейти к содержанию
12 минут чтения
Тема: Практика PHP · Unicode · Длинные сообщения

Как отправить длинное сообщение в Telegram: разбивка текста без повреждения разметки

Для примера возьмём ежедневный отчёт магазина: список заказов, комментарии сотрудников и итоговые суммы. Иногда он не помещается в одно сообщение. Подготовим части так, чтобы не разорвать эмодзи или HTML-тег, а затем выберем между несколькими сообщениями и документом.

Почему длинный текст не отправляется

Для обычного sendMessage Telegram указывает предел 4096 символов после разбора entities. Это не размер JSON в байтах. Длина UTF-8 строки в strlen, количество видимых символов и единицы UTF-16 — разные величины. Поэтому разрезать текст через substr по 4096 байт нельзя.

Ниже используем запас: не более 3000 единиц UTF-16 на часть и отдельную проверку длины с заголовком. Это консервативный бюджет нашего алгоритма, а не новая формулировка лимита Telegram. Он оставляет место для нумерации и не режет строку посреди UTF-8 последовательности.

Статья относится к обычному sendMessage. Подписи к файлам и фотографиям имеют другие ограничения: длинный отчёт не стоит переносить целиком в caption.

Официальные параметры sendMessage

Сначала делим текст, потом добавляем оформление

Надёжный исходник для этого примера — обычный текст. Сначала делим его на части, затем экранируем каждую и оборачиваем собственный заголовок в HTML-тег. Пользовательские <, > и & остаются текстом, а не командами разметки.

Не передавайте в функцию готовый HTML или MarkdownV2. Чтобы сохранить сложное исходное форматирование, нужен разбор структуры и закрытие/повторное открытие тегов либо перерасчёт entities для каждой части. Обычное разрезание строки этого не делает. Для таблиц и сложного отчёта часто удобнее документ.

Если проблема возникает даже у короткого текста, проверьте HTML и MarkdownV2

Функция разбиения для PHP

Нужны PHP 8.2+ и mbstring. Сохраните функцию в split-text.php. Короткие абзацы стараемся не разрывать, а слишком длинный абзац делим по графемным кластерам через \X. Кластер может включать несколько Unicode-символов — например, эмодзи с модификатором или букву с комбинируемым ударением.

PHP · split-text.php
<?php
declare(strict_types=1);

function utf16Length(string $text): int
{
    return intdiv(strlen(mb_convert_encoding($text, 'UTF-16LE', 'UTF-8')), 2);
}

/** Принимает обычный UTF-8 текст, не HTML и не Markdown.
 *  @return list<string>
 */
function splitTelegramText(string $text, int $limit = 3000): array
{
    if ($limit < 1 || $limit > 3000 || !mb_check_encoding($text, 'UTF-8')) {
        throw new InvalidArgumentException('Проверьте UTF-8 и limit от 1 до 3000');
    }
    if (!preg_match('/\S/u', $text)) {
        throw new InvalidArgumentException('Пустой текст');
    }
    $paragraphs = preg_split('/(\R\R+)/u', $text, -1, PREG_SPLIT_DELIM_CAPTURE);
    if ($paragraphs === false) {
        throw new RuntimeException('Не удалось разобрать абзацы');
    }
    $parts = [];
    $current = '';
    $used = 0;
    foreach ($paragraphs as $paragraph) {
        $size = utf16Length($paragraph);
        // Абзац, который целиком помещается в сообщение, не разрываем.
        if ($size <= $limit) {
            if ($used + $size > $limit) {
                $parts[] = $current;
                $current = '';
                $used = 0;
            }
            $current .= $paragraph;
            $used += $size;
            continue;
        }
        if (preg_match_all('/\X/u', $paragraph, $matches) === false) {
            throw new RuntimeException('Не удалось разобрать Unicode');
        }
        foreach ($matches[0] as $cluster) {
            $units = utf16Length($cluster);
            if ($units > $limit) {
                throw new LengthException('Один составной символ превышает лимит');
            }
            if ($used + $units > $limit) {
                $parts[] = $current;
                $current = '';
                $used = 0;
            }
            $current .= $cluster;
            $used += $units;
        }
    }
    if ($current !== '') {
        $parts[] = $current;
    }
    foreach ($parts as $part) {
        if (!preg_match('/\S/u', $part)) {
            throw new InvalidArgumentException('Получилась часть только из пробелов: очистите исходный текст');
        }
    }
    return $parts;
}

Функция сохраняет исходный текст: объединение частей без разделителя должно дать исходную строку. Невалидный UTF-8, пустой текст, часть только из пробелов или необычно длинный одиночный кластер приводят к явной ошибке до отправки. Для произвольного большого файла установите ограничение размера входа в вашем приложении: этот учебный вариант работает с текстом в памяти.

Готовим HTML для каждой части

Создайте report.txt в UTF-8 рядом со скриптами. Положите туда тестовый отчёт с несколькими абзацами, кириллицей, символами < и & и эмодзи. Следующий скрипт только выводит подготовленные параметры, ничего не отправляя.

PHP · prepare-parts.php
<?php
declare(strict_types=1);
require __DIR__.'/split-text.php';

$text = file_get_contents(__DIR__.'/report.txt');
if ($text === false) {
    throw new RuntimeException('Не найден report.txt');
}
$parts = splitTelegramText($text);
$payloads = [];
foreach ($parts as $index => $part) {
    $header = 'Отчёт — часть '.($index + 1).' из '.count($parts);
    if (utf16Length($header."\n".$part) > 4096) {
        throw new LengthException('Сообщение с заголовком слишком длинное');
    }
    $payloads[] = [
        'text' => '<b>'.htmlspecialchars($header, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')."</b>\n"
            .htmlspecialchars($part, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
        'parse_mode' => 'HTML',
    ];
}
echo json_encode($payloads, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR), PHP_EOL;
Bash / PowerShell · локальный просмотр частей
php prepare-parts.php

Проверьте нумерацию и границы абзацев. В JSON вы увидите HTML-сущности и теги — это нормально: Telegram обработает их при parse_mode: HTML. Для проверки лимита важен текст после разбора разметки, а не длина этой сериализации.

Отправляем части последовательно

Задания по одному отчёту должны выполняться последовательно. Сохраните подготовленные части и курсор следующей отправки в хранилище приложения. Не создавайте параллельную отправку всех частей: порядок выполнения сетевых запросов может отличаться от порядка отчёта.

  • Перед вызовом отметьте конкретную часть как отправляемую.

  • При подтверждённом ответе сохраните message_id этой части и переходите к следующей.

  • При 429 отложите текущую часть на указанное время; следующие части пока не отправляйте.

  • При таймауте или потерянном ответе остановите отчёт в состоянии неизвестного результата.

  • После ошибки не начинайте отчёт заново с первой части.

Это схема обработки заданий, а не готовая реализация очереди. Даже транзакция в вашей БД не делает запись message_id атомарной с Telegram: процесс может завершиться после отправки, но до сохранения ответа. Для неизвестного результата нужна отдельная процедура проверки, а не обещание доставки без дублей.

Очередь и обработка ошибок в Laravel

Задержка при 429 и ограничения отправки

Почему возникают повторные сообщения

Проверяем одну часть через BotGate

Для отправки используйте composer require botgate/sdk и переменные окружения BOTGATE_API_KEY, BOTGATE_BOT_ID и TELEGRAM_CHAT_ID. PHP SDK требует PHP 8.2+. Сохраните следующую настройку в botgate.php:

PHP · botgate.php
<?php
declare(strict_types=1);

require __DIR__.'/vendor/autoload.php';

use BotGate\Client;
use BotGate\Config;

$apiKey = getenv('BOTGATE_API_KEY');
$botId = getenv('BOTGATE_BOT_ID');
if (!is_string($apiKey) || $apiKey === '' || !is_string($botId) || $botId === '') {
    throw new RuntimeException('Задайте BOTGATE_API_KEY и BOTGATE_BOT_ID');
}
$bot = Client::fromConfig(new Config(
    apiKey: $apiKey,
    timeout: 60.0,
    maxRetries: 0,
))->bot($botId);

Этот CLI-скрипт намеренно отправляет только первую часть отчёта в тестовый чат. Он проверяет переносы, экранирование и внешний вид. Полную последовательность подключайте к описанной выше очереди после этой проверки.

PHP · send-first-part.php
<?php
declare(strict_types=1);
require __DIR__.'/botgate.php';
require __DIR__.'/split-text.php';

$chatId = getenv('TELEGRAM_CHAT_ID');
$text = file_get_contents(__DIR__.'/report.txt');
if (!is_string($chatId) || $chatId === '' || $text === false) {
    throw new RuntimeException('Проверьте TELEGRAM_CHAT_ID и report.txt');
}
$parts = splitTelegramText($text);
$header = 'Отчёт — часть 1 из '.count($parts);
if (utf16Length($header."\n".$parts[0]) > 4096) {
    throw new LengthException('Сообщение с заголовком слишком длинное');
}
$response = $bot->call('sendMessage', [
    'chat_id' => $chatId,
    'parse_mode' => 'HTML',
    'text' => '<b>'.htmlspecialchars($header, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')."</b>\n"
        .htmlspecialchars($parts[0], ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
]);
echo json_encode($response->result, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR), PHP_EOL;

maxRetries: 0 оставляет решение о повторе вашему приложению. Смена транспорта не увеличивает допустимую длину сообщения и не исправляет повреждённую разметку. При прямой отправке к Telegram используются те же text и parse_mode.

Когда удобнее отправить документ

Если отчёт получается на десятки сообщений, содержит таблицы или нужен для скачивания, подготовьте TXT либо PDF и отправьте его через sendDocument с короткой подписью. Читателю будет проще сохранить один файл и вернуться к нему.

Для TXT явно используйте UTF-8. Для PDF сначала проверьте переносы страниц и шрифты. Не делайте файл с персональными данными публично доступным ради передачи по URL: можно загрузить его с сервера через multipart.

Загрузка документа и диагностика ошибок файлов

Проверяем разбиение до подключения очереди

  • Короткий текст даёт одну часть; длинный — несколько, без потери и перестановки исходных символов.

  • Длинный абзац без пробелов укладывается в лимит; обычные короткие абзацы остаются целыми.

  • Кириллица, комбинируемые буквы, эмодзи с оттенком кожи и семейные эмодзи не разрываются внутри кластера.

  • Знаки <, >, &, кавычки и текст, похожий на HTML, отображаются как пользовательский текст.

  • Каждая часть вместе с заголовком проходит проверку длины до сетевого вызова.

  • Ошибка второй части не приводит к повторной отправке первой и бесконтрольной отправке третьей.

Источники

Telegram: sendMessage и форматирование

PHP: \X и Unicode-кластеры в PCRE

PHP: mb_convert_encoding

PHP: htmlspecialchars