Почему длинный текст не отправляется
Для обычного sendMessage Telegram указывает предел 4096 символов после разбора entities. Это не размер JSON в байтах. Длина UTF-8 строки в strlen, количество видимых символов и единицы UTF-16 — разные величины. Поэтому разрезать текст через substr по 4096 байт нельзя.
Ниже используем запас: не более 3000 единиц UTF-16 на часть и отдельную проверку длины с заголовком. Это консервативный бюджет нашего алгоритма, а не новая формулировка лимита Telegram. Он оставляет место для нумерации и не режет строку посреди UTF-8 последовательности.
Статья относится к обычному sendMessage. Подписи к файлам и фотографиям имеют другие ограничения: длинный отчёт не стоит переносить целиком в caption.
Сначала делим текст, потом добавляем оформление
Надёжный исходник для этого примера — обычный текст. Сначала делим его на части, затем экранируем каждую и оборачиваем собственный заголовок в HTML-тег. Пользовательские <, > и & остаются текстом, а не командами разметки.
Не передавайте в функцию готовый HTML или MarkdownV2. Чтобы сохранить сложное исходное форматирование, нужен разбор структуры и закрытие/повторное открытие тегов либо перерасчёт entities для каждой части. Обычное разрезание строки этого не делает. Для таблиц и сложного отчёта часто удобнее документ.
Если проблема возникает даже у короткого текста, проверьте HTML и MarkdownV2
Функция разбиения для PHP
Нужны PHP 8.2+ и mbstring. Сохраните функцию в split-text.php. Короткие абзацы стараемся не разрывать, а слишком длинный абзац делим по графемным кластерам через \X. Кластер может включать несколько Unicode-символов — например, эмодзи с модификатором или букву с комбинируемым ударением.
<?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
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;
php prepare-parts.php
Проверьте нумерацию и границы абзацев. В JSON вы увидите HTML-сущности и теги — это нормально: Telegram обработает их при parse_mode: HTML. Для проверки лимита важен текст после разбора разметки, а не длина этой сериализации.
Отправляем части последовательно
Задания по одному отчёту должны выполняться последовательно. Сохраните подготовленные части и курсор следующей отправки в хранилище приложения. Не создавайте параллельную отправку всех частей: порядок выполнения сетевых запросов может отличаться от порядка отчёта.
Перед вызовом отметьте конкретную часть как отправляемую.
При подтверждённом ответе сохраните message_id этой части и переходите к следующей.
При 429 отложите текущую часть на указанное время; следующие части пока не отправляйте.
При таймауте или потерянном ответе остановите отчёт в состоянии неизвестного результата.
После ошибки не начинайте отчёт заново с первой части.
Это схема обработки заданий, а не готовая реализация очереди. Даже транзакция в вашей БД не делает запись message_id атомарной с Telegram: процесс может завершиться после отправки, но до сохранения ответа. Для неизвестного результата нужна отдельная процедура проверки, а не обещание доставки без дублей.
Очередь и обработка ошибок в Laravel
Проверяем одну часть через BotGate
Для отправки используйте composer require botgate/sdk и переменные окружения BOTGATE_API_KEY, BOTGATE_BOT_ID и TELEGRAM_CHAT_ID. PHP SDK требует PHP 8.2+. Сохраните следующую настройку в 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
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 и форматирование