wramirez83/telegram

Laravel 12 compatible library for sending Telegram messages, including texts and files

2.0.0 2025-11-20 00:55 UTC

Requires

• php: ^8.2
• illuminate/config: ^12.0
• illuminate/support: ^12.0

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• Wilson Ramirez Z

README

Librería PHP compatible con Laravel 12 para enviar mensajes y archivos a través de la API de Telegram Bot.

Requisitos

• PHP >= 8.2
• Laravel >= 12.0
• Composer

Instalación

composer require wramirez83/telegram

Si estás usando Laravel, publica el archivo de configuración:

php artisan vendor:publish --tag=telegram-config

Configuración

Agrega las siguientes variables de entorno en tu archivo .env:

TELEGRAM_BOT_TOKEN=tu_token_del_bot
TELEGRAM_CHANNEL_ID=tu_channel_id

O configura en config/telegram.php:

return [
    'bot_token' => env('TELEGRAM_BOT_TOKEN', ''),
    'channel_id' => env('TELEGRAM_CHANNEL_ID', ''),
];

Métodos Disponibles

Información del Bot

getMe()

Obtiene información básica sobre el bot.

use Wramirez83\Telegram\Telegram;

$botInfo = Telegram::getMe();

Mensajes

sendMessage($message, $chatId = '', $mode = 'Markdown')

Envía un mensaje de texto a un chat.

Parámetros:

• $message (string): El mensaje a enviar
• $chatId (string|int, opcional): ID del chat destino. Si está vacío, usa el canal por defecto
• $mode (string, opcional): Modo de parseo. Valores: 'Markdown', 'HTML', 'MarkdownV2'

use Wramirez83\Telegram\Telegram;

// Mensaje simple
Telegram::sendMessage('Hola desde Laravel 12!');

// Mensaje con formato HTML
Telegram::sendMessage('<b>Texto en negrita</b>', '', 'HTML');

// Mensaje a un chat específico
Telegram::sendMessage('Mensaje personalizado', '@mi_canal');

forwardMessage($chatId, $fromChatId, $messageId, $disableNotification = false)

Reenvía un mensaje de cualquier tipo.

use Wramirez83\Telegram\Telegram;

Telegram::forwardMessage(
    '@destino',      // Chat destino
    '@origen',       // Chat origen
    12345,           // ID del mensaje
    false            // Notificación silenciosa
);

Archivos y Medios

sendPhoto($file, $message = '', $chatId = '')

Envía una foto.

use Wramirez83\Telegram\Telegram;

// Desde ruta local
Telegram::sendPhoto('/ruta/imagen.jpg', 'Descripción de la imagen');

// Usando CURLFile
Telegram::sendPhoto(Telegram::curFile('/ruta/imagen.jpg'), 'Mi foto');

sendDocument($file, $message = '', $chatId = '')

Envía un documento.

use Wramirez83\Telegram\Telegram;

Telegram::sendDocument(
    Telegram::curFile('/ruta/documento.pdf'),
    'Nuevo documento',
    '@mi_canal'
);

sendAudio($audio, $caption = '', $chatId = '', $duration = null, $performer = null, $title = null)

Envía un archivo de audio.

use Wramirez83\Telegram\Telegram;

Telegram::sendAudio(
    Telegram::curFile('/ruta/audio.mp3'),
    'Mi canción',
    '',
    180,              // Duración en segundos
    'Artista',        // Intérprete
    'Título'          // Título
);

sendVideo($video, $caption = '', $chatId = '', $duration = null, $width = null, $height = null)

Envía un video.

use Wramirez83\Telegram\Telegram;

Telegram::sendVideo(
    Telegram::curFile('/ruta/video.mp4'),
    'Mi video',
    '',
    60,    // Duración
    1920,  // Ancho
    1080   // Alto
);

sendVoice($voice, $caption = '', $chatId = '', $duration = null)

Envía un mensaje de voz.

use Wramirez83\Telegram\Telegram;

Telegram::sendVoice(
    Telegram::curFile('/ruta/voice.ogg'),
    'Mensaje de voz',
    '',
    30  // Duración en segundos
);

sendSticker($sticker, $chatId = '')

Envía un sticker (.webp).

use Wramirez83\Telegram\Telegram;

Telegram::sendSticker(Telegram::curFile('/ruta/sticker.webp'));

Ubicación

sendLocation($latitude, $longitude, $chatId = '', $horizontalAccuracy = null, $livePeriod = null, $heading = null, $proximityAlertRadius = null)

Envía un punto en el mapa.

use Wramirez83\Telegram\Telegram;

Telegram::sendLocation(
    40.7128,  // Latitud
    -74.0060, // Longitud
    '@mi_canal'
);

Acciones del Chat

sendChatAction($action, $chatId = '')

Indica al usuario que algo está pasando del lado del bot.

Acciones válidas:

• typing - Escribiendo
• upload_photo - Subiendo foto
• record_video - Grabando video
• upload_video - Subiendo video
• record_voice - Grabando audio
• upload_voice - Subiendo audio
• upload_document - Subiendo documento
• find_location - Buscando ubicación
• record_video_note - Grabando nota de video
• upload_video_note - Subiendo nota de video

use Wramirez83\Telegram\Telegram;

Telegram::sendChatAction('typing', '@mi_canal');

Actualizaciones y Webhooks

getUpdate($offset = null, $limit = null, $timeout = null, $allowedUpdates = null)

Obtiene actualizaciones del bot.

use Wramirez83\Telegram\Telegram;

// Obtener todas las actualizaciones
$updates = Telegram::getUpdate();

// Con parámetros
$updates = Telegram::getUpdate(
    0,      // Offset
    10,     // Límite
    30,     // Timeout en segundos
    ['message', 'callback_query']  // Tipos de actualizaciones
);

setWebhook($url, $certificate = null, $ipAddress = null, $maxConnections = null, $allowedUpdates = null, $dropPendingUpdates = false, $secretToken = null)

Configura un webhook para recibir actualizaciones.

use Wramirez83\Telegram\Telegram;

Telegram::setWebhook(
    'https://tudominio.com/webhook/telegram',
    null,  // Certificado (opcional)
    null,  // IP fija (opcional)
    40,    // Máximo de conexiones
    ['message', 'callback_query'],  // Tipos permitidos
    true,  // Eliminar actualizaciones pendientes
    'mi_secret_token'  // Token secreto
);

removeWebhook($dropPendingUpdates = false)

Elimina el webhook configurado.

use Wramirez83\Telegram\Telegram;

Telegram::removeWebhook(true);  // Eliminar actualizaciones pendientes

Archivos

getFile($fileId)

Obtiene información sobre un archivo.

use Wramirez83\Telegram\Telegram;

$fileInfo = Telegram::getFile('BAACAgIAAxkBAAIBY2...');

getFileUrl($fileId)

Obtiene la URL completa para descargar un archivo.

use Wramirez83\Telegram\Telegram;

$url = Telegram::getFileUrl('BAACAgIAAxkBAAIBY2...');
// Retorna: https://api.telegram.org/file/bot{token}/{file_path}

Perfil de Usuario

getUserProfilePhotos($userId, $offset = 0, $limit = 100)

Obtiene las fotos de perfil de un usuario.

use Wramirez83\Telegram\Telegram;

$photos = Telegram::getUserProfilePhotos(123456789, 0, 10);

Utilidades

curFile($routeFile)

Crea un objeto CURLFile para subir archivos.

use Wramirez83\Telegram\Telegram;

$file = Telegram::curFile('/ruta/archivo.pdf');
Telegram::sendDocument($file, 'Mi documento');

Ejemplos Completos

Enviar mensaje con formato

use Wramirez83\Telegram\Telegram;

$message = <<<MSG
*Título en negrita*
_Texto en cursiva_
`Código`
[Enlace](https://example.com)
MSG;

Telegram::sendMessage($message, '', 'Markdown');

Enviar múltiples archivos

use Wramirez83\Telegram\Telegram;

$files = [
    '/ruta/imagen1.jpg',
    '/ruta/imagen2.jpg',
    '/ruta/documento.pdf'
];

foreach ($files as $file) {
    if (pathinfo($file, PATHINFO_EXTENSION) === 'pdf') {
        Telegram::sendDocument(Telegram::curFile($file), 'Documento');
    } else {
        Telegram::sendPhoto(Telegram::curFile($file), 'Imagen');
    }
}

Manejar actualizaciones

use Wramirez83\Telegram\Telegram;

$updates = Telegram::getUpdate();

if ($updates->ok) {
    foreach ($updates->result as $update) {
        if (isset($update->message)) {
            $chatId = $update->message->chat->id;
            $text = $update->message->text;
            
            Telegram::sendMessage("Recibí: $text", $chatId);
        }
    }
}

Compatibilidad con Laravel 12

Esta librería es completamente compatible con Laravel 12 y utiliza:

• Sistema de configuración de Laravel
• Soporte para PHP 8.2+
• Estructura compatible con Service Providers de Laravel

Referencias

• Telegram Bot API Documentation
• Telegram Bot SDK Reference

Licencia

MIT

Autor

Wilson Ramirez Z - [e-mail]