Класс Telegram для отправки сообщений

Описание

Класс Telegram предназначен для взаимодействия с Telegram Bot API. Он позволяет отправлять сообщения в чаты и получать обновления от бота.

Пространство имен

WeppsExtensions\Addons\Messages\Telegram

Зависимости

• WeppsCore\Connect - для получения конфигурации проекта и сервисов
• Curl\Curl - для выполнения HTTP-запросов к API Telegram
• WeppsCore\Utils - утилиты (подключены, но не используются в текущей реализации)

Инициализация

Конструктор

public function __construct()

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

1. Формирование токена бота:

   $this->token = "bot" . Connect::$projectServices['telegram']['token'];

   Токен берется из конфигурации проекта и добавляется префикс "bot".

2. Настройка CURL:

   • Создается экземпляр Curl\Curl
   • Если в конфигурации указан прокси-сервер, настраивается SOCKS5 прокси:

     if (!empty($proxy = Connect::$projectServices['telegram']['proxy'])) {
     $this->curl->setOpt(CURLOPT_PROXYTYPE, CURLPROXY_SOCKS5);
     $this->curl->setOpt(CURLOPT_PROXY, $proxy);
     }

Пример создания экземпляра

use WeppsExtensions\Addons\Messages\Telegram\Telegram;

$telegram = new Telegram();

Методы класса

send() - Отправка сообщения

public function send(int $chat, string $text): array

Отправляет текстовое сообщение в указанный чат Telegram.

Параметры

• $chat (int) - ID чата или пользователя, куда отправляется сообщение
• $text (string) - Текст сообщения для отправки

Особенности

1. Режим отладки: Если в проекте включен режим отладки (Connect::$projectDev['debug']==1), сообщение будет отправлено не в указанный чат, а в тестовый чат разработчика:

   if (Connect::$projectDev['debug']==1) {
      $chat = Connect::$projectServices['telegram']['dev'];
   }

2. Форматирование сообщений: Сообщения отправляются с поддержкой HTML-разметки (parse_mode=html), что позволяет использовать теги:

   • <b>текст</b> - жирный текст
   • <i>текст</i> - курсив
   • <code>текст</code> - моноширинный шрифт
   • <pre>текст</pre> - блок кода
   • <a href="URL">текст</a> - ссылка

Возвращаемое значение

Массив с двумя ключами:

• url (string) - полный URL запроса к API
• response (object) - ответ от Telegram API

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

Простое сообщение:

$telegram = new Telegram();
$result = $telegram->send(123456789, "Привет, мир!");

Сообщение с HTML-форматированием:

$message = "<b>Важно!</b>\n\n";
$message .= "Заказ <code>#12345</code> выполнен.\n";
$message .= "<i>Сумма: 1500 руб.</i>";

$result = $telegram->send(123456789, $message);

Проверка результата:

$result = $telegram->send(123456789, "Тестовое сообщение");

if ($result['response']->ok) {
    echo "Сообщение отправлено успешно!";
    echo "ID сообщения: " . $result['response']->result->message_id;
} else {
    echo "Ошибка: " . $result['response']->description;
}

updates() - Получение обновлений

public function updates($method = "getUpdates"): array

Получает обновления от бота (новые сообщения, команды и т.д.).

Параметры

• $method (string) - метод API (по умолчанию "getUpdates", но не используется в текущей реализации)

Возвращаемое значение

Массив с двумя ключами:

• url (string) - URL запроса к API
• response (object) - ответ от API с массивом обновлений

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

$telegram = new Telegram();
$updates = $telegram->updates();

if ($updates['response']->ok) {
    foreach ($updates['response']->result as $update) {
        // Обработка каждого обновления
        if (isset($update->message)) {
            $chatId = $update->message->chat->id;
            $text = $update->message->text;

            echo "Получено сообщение от {$chatId}: {$text}\n";
        }
    }
}

Конфигурация

Для работы класса необходимо настроить следующие параметры в конфигурации проекта:

Обязательные параметры

Connect::$projectServices['telegram']['token'] = 'YOUR_BOT_TOKEN';

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

// Прокси-сервер (если необходим)
Connect::$projectServices['telegram']['proxy'] = 'socks5://127.0.0.1:9050';

// Чат для режима отладки
Connect::$projectServices['telegram']['dev'] = 987654321;

// Режим отладки
Connect::$projectDev['debug'] = 1; // или 0

Практические примеры

Уведомление о новом заказе

use WeppsExtensions\Addons\Messages\Telegram\Telegram;

function notifyNewOrder($orderId, $customerName, $amount) {
    $telegram = new Telegram();

    $message = "🔔 <b>Новый заказ!</b>\n\n";
    $message .= "📋 Номер: <code>#{$orderId}</code>\n";
    $message .= "👤 Клиент: {$customerName}\n";
    $message .= "💰 Сумма: <b>{$amount} руб.</b>";

    $adminChatId = 123456789;
    $result = $telegram->send($adminChatId, $message);

    return $result;
}

Отправка уведомления об ошибке

function notifyError($errorMessage, $file, $line) {
    $telegram = new Telegram();

    $message = "❌ <b>Ошибка на сайте</b>\n\n";
    $message .= "<code>{$errorMessage}</code>\n\n";
    $message .= "📄 Файл: {$file}\n";
    $message .= "📍 Строка: {$line}";

    $devChatId = 123456789;
    $telegram->send($devChatId, $message);
}

Массовая рассылка

function sendBroadcast($message, array $chatIds) {
    $telegram = new Telegram();
    $results = [];

    foreach ($chatIds as $chatId) {
        $result = $telegram->send($chatId, $message);
        $results[$chatId] = $result['response']->ok;

        // Задержка для избежания лимитов API
        usleep(100000); // 0.1 секунды
    }

    return $results;
}

Ограничения и особенности

1. Лимиты API Telegram:

   • Максимум 30 сообщений в секунду
   • Максимальная длина сообщения: 4096 символов

2. Режим отладки:

   • При включенном debug все сообщения отправляются в тестовый чат
   • Удобно для тестирования без спама в рабочие чаты

3. HTML-форматирование:

   • Обязательно экранируйте специальные символы HTML: <, >, &
   • Неправильная разметка приведет к ошибке отправки

4. Прокси:

   • Поддерживается только SOCKS5
   • Полезно при блокировке API Telegram в некоторых регионах

Возможные улучшения

1. Добавить метод для отправки фото, документов
2. Реализовать поддержку клавиатур (inline и reply)
3. Добавить методы для редактирования и удаления сообщений
4. Реализовать webhook вместо polling для получения обновлений
5. Добавить логирование ошибок
6. Использовать параметр $method в методе updates()

Заключение

Класс Telegram предоставляет простой и удобный интерфейс для отправки сообщений через Telegram Bot API. Поддержка режима отладки и прокси делает его гибким инструментом для различных сценариев использования.