Para probar un webhook de bot de Telegram en localhost, exponga su servidor local con un túnel HTTPS público, llame a setWebhook con esa URL y valide el encabezado del token secreto de Telegram en cada solicitud. Esto le brinda mensajes reales, consultas de devolución de llamadas y actualizaciones de membresía sin implementar después de cada cambio de código. El ciclo completo es: ejecutar el controlador del bot, iniciar npx portpreview 3000, registrar la URL resultante, enviar un mensaje a su bot e inspeccionar la solicitud localmente.
Por qué Telegram no puede enviar actualizaciones directamente a localhost
La API Bot de Telegram envía actualizaciones de webhooks desde la infraestructura de Telegram a una URL accesible en Internet. localhost, 127.0.0.1 y las direcciones LAN privadas no se pueden enrutar desde esa infraestructura. Un túnel de host local finaliza HTTPS en una dirección pública y reenvía la solicitud HTTP sin cambios a su puerto local.
Los bots de Telegram pueden recibir actualizaciones de dos formas mutuamente excluyentes: encuestas largas a través de getUpdates o webhooks. La referencia oficial setWebhook indica que getUpdates no está disponible mientras se configura un webhook saliente. Si aún se está ejecutando un proceso de sondeo, deténgalo antes de juzgar el flujo del webhook.
Construya un punto final de webhook local
Este ejemplo de Express mantiene el controlador intencionalmente pequeño. Comprueba el secreto compartido antes de tocar la actualización, reconoce rápidamente y mueve el trabajo fuera de la ruta de respuesta.
import express from 'express';
import crypto from 'node:crypto';
const app = express();
app.use(express.json({ limit: '1mb' }));
function sameSecret(received = '', expected = '') {
const a = Buffer.from(received);
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/webhooks/telegram', (req, res) => {
const received = req.get('x-telegram-bot-api-secret-token') || '';
if (!sameSecret(received, process.env.TELEGRAM_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
const update = req.body;
res.sendStatus(200);
queueMicrotask(() => handleUpdate(update));
});
app.listen(3000, () => console.log('Listening on http://localhost:3000'));Telegram envía un Update serializado en JSON. A diferencia de los proveedores basados en HMAC, la función secret_token de Telegram no firma el cuerpo. Coloca el valor elegido en X-Telegram-Bot-Api-Secret-Token. El token demuestra que el remitente conoce el valor utilizado cuando se registró el webhook, pero no proporciona un resumen de la carga útil. TLS protege la solicitud en tránsito.
Exponer el punto final con HTTPS
- Inicie la aplicación y confirme que
curl -i http://localhost:3000/webhooks/telegramllega al servidor, incluso si GET devuelve 404. - Abra una segunda terminal y ejecute
npx portpreview 3000. - Copie el origen HTTPS público y agregue
/webhooks/telegram. - Mantenga el proceso del túnel en ejecución mientras Telegram entrega actualizaciones.
La API de Bot acepta URL de webhook HTTPS. Telegram documenta la compatibilidad con webhooks en los puertos 443, 80, 88 y 8443; El punto final público de un túnel administrado normalmente usa 443 incluso cuando el proceso local reenviado escucha en 3000.
Registra el webhook de Telegram de forma segura
Cree un secreto aleatorio que contenga solo letras, dígitos, guiones bajos o guiones. Telegram permite entre 1 y 256 caracteres. No reutilice el token del bot con este valor.
export TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"
curl -sS -X POST \
"https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
-d "url=https://YOUR-TUNNEL.portpreview.dev/webhooks/telegram" \
-d "secret_token=${TELEGRAM_WEBHOOK_SECRET}" \
-d 'allowed_updates=["message","callback_query"]' \
-d "drop_pending_updates=true"allowed_updates reduce el ruido y debe enumerar solo los tipos de actualización que maneja el bot. drop_pending_updates=true es útil al iniciar una nueva sesión local, pero descarta permanentemente las actualizaciones en cola, así que omítalo cuando esos eventos sean importantes. La Documentación de actualización de Telegram describe campos como message, callback_query y my_chat_member.
Confirmar registro antes de depurar el código
Utilice getWebhookInfo para separar los errores de configuración de los errores del controlador:
curl -sS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"Marque url, pending_update_count, last_error_message y last_error_date. Una URL vacía significa que el registro no se realizó. Un recuento pendiente creciente generalmente significa que Telegram no puede conectarse o que su punto final devuelve un estado que no es 2xx. Enviar un mensaje directo al bot después del registro; simplemente abrir el chat no necesariamente crea una actualización.
Manejar actualizaciones sin provocar reintentos
Reconocimiento antes de trabajo lento
Devuelve una respuesta 2xx tan pronto como la solicitud esté autenticada y aceptada de forma duradera. Las exportaciones de bases de datos, las llamadas de IA y las API de terceros deben ejecutarse de forma asincrónica. Telegram reintenta solicitudes fallidas después de respuestas que no son 2xx, por lo que el trabajo sincrónico lento puede crear duplicados.
Deduplicar con update_id
Cada actualización tiene un update_id. Almacene las identificaciones procesadas con una ventana de vencimiento o aplique una clave de base de datos única. Un reintento no debe enviar un segundo recibo de pago, crear un ticket duplicado ni ejecutar la misma devolución de llamada dos veces.
Modele cada tipo de actualización explícitamente
No todas las actualizaciones contienen message.text. Los botones de devolución de llamada llegan bajo callback_query; Las publicaciones del canal y los cambios de membresía tienen otros campos. Bifurque en el campo actual de nivel superior y trate los tipos desconocidos como no operaciones válidas en lugar de descartarlos.
Reglas de seguridad para pruebas de bots de Telegram locales
- Valide primero el encabezado secreto. Rechace los valores faltantes o incorrectos antes de registrar o analizar campos confidenciales.
- Mantenga los tokens fuera de las URL y los registros. El token de Bot API en el comando de registro es una credencial. Evite el historial de shell en sistemas compartidos y rote un token expuesto a través de BotFather.
- Utiliza una ruta indescifrable y secreta. La ruta es defensa en profundidad; el encabezado secreto es la verificación de la aplicación real.
- Limitar datos capturados. Los mensajes pueden contener nombres, nombres de usuario, números de teléfono, archivos y texto de conversaciones privadas. Redactar registros y eliminar capturas locales cuando haya terminado.
- Nunca deshabilite la autenticación en desarrollo. Un túnel público es público. El código local debe ejercer los mismos controles que la producción.
Consulte la guía de seguridad del túnel localhost más amplia para prácticas de control de acceso y retención de datos.
Solucionar fallas comunes del webhook de Telegram
Telegram reporta error de certificado o conexión
Utilice la URL HTTPS del túnel, no su destino HTTP local. Confirme que el túnel esté activo y que la URL no haya cambiado. Si proporciona su propio certificado autofirmado, Telegram requiere cargar el certificado público como un archivo; un punto final TLS administrado evita esa configuración.
El punto final devuelve 401
Compare el secreto pasado a setWebhook con la variable de entorno utilizada por el proceso. Los nombres de los encabezados no distinguen entre mayúsculas y minúsculas, pero los servidores proxy o middleware pueden eliminar los encabezados personalizados. Inspeccione los encabezados entrantes sin imprimir el valor secreto.
No llegan solicitudes
Ejecute getWebhookInfo, verifique que la ruta registrada coincida exactamente con su ruta y asegúrese de que ningún firewall bloquee la conexión local del túnel. Si utilizó encuestas recientemente, confirme que la URL del webhook ya esté completa. Active una actualización real enviando un mensaje al bot.
Las actualizaciones llegan repetidamente
Estado del registro y tiempo de respuesta. Las excepciones después de recibir la solicitud pueden convertir un 200 previsto en un 500. Devuelva 200 rápidamente, haga que el procesamiento sea idempotente y use repetición controlada de webhook en lugar de esperar los reintentos del proveedor durante la depuración.
Pruebe consultas y archivos de devolución de llamada, no solo texto
Una útil matriz de prueba de bot cubre más de message.text. Envíe una foto con un título, comparta un contacto, edite un mensaje y presione un botón del teclado en línea. Para consultas de devolución de llamada, llame al answerCallbackQuery de inmediato para que el cliente deje de mostrar su indicador de progreso y luego realice un trabajo más lento por separado. Las actualizaciones de archivos contienen identificadores; descargar los bytes es una segunda operación de Bot API y no debería retrasar la respuesta del webhook.
Conserve los dispositivos elaborados a partir de actualizaciones desinfectadas para las pruebas unitarias, pero conserve la ruta de transporte completa para al menos una prueba de cada tipo admitido. Un dispositivo demuestra que su despachador comprende una carga útil; una entrega tunelizada real también demuestra el comportamiento de registro, TLS, encabezados, análisis del cuerpo y reconocimiento. Al agregar una nueva entrada allowed_updates, llame a setWebhook nuevamente y verifique que getWebhookInfo refleje la configuración deseada.
Eliminar el webhook después de la sesión local
curl -sS -X POST \
"https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/deleteWebhook" \
-d "drop_pending_updates=false"Eliminar el webhook le permite volver a getUpdates. Si la URL del túnel cambia en la siguiente sesión, llame a setWebhook nuevamente. Para diagnósticos adicionales, siga el flujo de trabajo de depuración de webhook local.