Telegram Bot API

Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir

· 9 min de lectura

Telegram ofrece cuatro widgets para sitios web: Telegram Login (para iniciar sesión con Telegram en tu sitio), el widget de post (inserta un mensaje de un canal o grupo público), el widget de discusión (muestra los comentarios de un post del canal) y el botón compartir. Cada uno es un pequeño snippet que pegas en tu HTML. No son los widgets interactivos que los bots envían dentro de los mensajes desde Bot API 10.4; para esos, consulta widgets de Telegram en mensajes de bots.

Widgets de Telegram para web de un vistazo

WidgetQué hace¿Necesita bot?Cómo obtener el código
Telegram LoginRegistro e inicio de sesión con la cuenta de Telegram (OpenID Connect)Sí, además de Allowed URLs y un Client ID de @BotFatherConfigurador en core.telegram.org/bots/telegram-login
Login Widget (clásico)El botón de login antiguo en iframe, hoy archivadoSí, con el dominio vinculado mediante /setdomaincore.telegram.org/widgets/login-legacy
Widget de postInserta un mensaje de un canal o grupo públicoNoEnlace t.me → EMBED, o el configurador de posts
Widget de discusiónMuestra un post del canal con sus comentariosNoConfigurador de discusión
Botón compartirPermite al visitante enviar tu enlace a un chat, grupo, canal o a Mensajes guardadosNoConstructor del botón o un enlace simple

Telegram Login: iniciar sesión con Telegram mediante OpenID Connect

El Telegram Login actual es una biblioteca JavaScript más un proveedor OpenID Connect estándar con Authorization Code Flow y PKCE. Puedes usar el botón de la biblioteca, cualquier biblioteca o plataforma de identidad compatible con OIDC (Telegram menciona Keycloak, Authentik y Auth0 como ejemplos) o los SDK nativos para iOS y Android.

  1. Prepara un bot que represente a tu sitio (cómo crear un bot de Telegram). El usuario ve su nombre y foto de perfil en la ventana de confirmación, así que conviene que coincidan con el nombre y el logo de tu sitio.
  2. Registra las Allowed URLs. Abre la mini app de @BotFather, selecciona el bot y entra en Login Widget. Agrega los orígenes donde insertas el botón (p. ej. https://example.com) y tus redirect URIs de OIDC (p. ej. https://example.com/auth/callback). Telegram solo procesa logins y redirecciones hacia estas URLs registradas.
  3. Guarda el Client ID y el Client Secret que aparecen en esa misma sección. El secret se queda en el servidor.
  4. Agrega el botón a tu página.
  5. Valida el ID token en tu servidor antes de confiar en cualquier dato del usuario.

El código que genera el configurador oficial se ve así (data-request-access es opcional: write permite que tu bot le escriba al usuario y phone pide su número de teléfono verificado):

<script async src="https://oauth.telegram.org/js/telegram-login.js?6" data-client-id="123456789" data-onauth="onTelegramAuth(data)" data-request-access="write"></script>

<button class="tg-auth-button">Iniciar sesión con Telegram</button>

<script>
  function onTelegramAuth(data) {
    if (data.error) return console.warn(data.error);
    // Envía data.id_token a tu servidor y verifícalo allí
    fetch('/auth/telegram', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({id_token: data.id_token})
    });
  }
</script>

El callback recibe id_token (un JWT de OIDC), user (los claims ya decodificados) o error. La biblioteca también tiene una API JS: Telegram.Login.init(InitOptions, callback), Telegram.Login.open([callback]) y Telegram.Login.auth(InitOptions, callback), con las opciones client_id, scope, lang y nonce (una cadena aleatoria generada en el servidor que se incluye en el id_token para evitar ataques de repetición).

Popup y COOP: telegram-login.js se comunica con una ventana emergente. Si tu sitio envía Cross-Origin-Opener-Policy: same-origin, el login falla; quita el header o usa same-origin-allow-popups.

Scopes y endpoints de OIDC

ScopeQué obtienesClaims
openidObligatorio. Identificador único y momento de la autenticaciónsub, iss, iat, exp
profileID de usuario, nombre, username, URL de la fotoid, name, preferred_username, picture
phoneNúmero de teléfono verificado, con el consentimiento del usuariophone_number
telegram:bot_accessTu bot puede escribirle al usuario después del login—

En un cliente OIDC usa el documento de descubrimiento https://oauth.telegram.org/.well-known/openid-configuration, response type code y PKCE con S256. Si implementas el flujo a mano, los endpoints son https://oauth.telegram.org/auth, https://oauth.telegram.org/token (POST desde el servidor con Basic auth base64(client_id:client_secret)) y https://oauth.telegram.org/.well-known/jwks.json. Telegram no tiene endpoint UserInfo: todos los datos vienen en el ID token, así que configura tu biblioteca para que no haga esa petición si la espera.

Validar el ID token

Verifica la firma del JWT con las claves del endpoint JWKS y luego comprueba que iss sea https://oauth.telegram.org, que aud coincida con el ID de tu bot (el valor que pasas como client_id) y que exp no haya vencido. Por defecto los tokens se firman con RS256; en @BotFather, en Login Widget > Advanced, puedes elegir ES256, EdDSA o ES256K (con EdDSA y ES256K solo se permite el scope openid). Un ejemplo en Node.js con la biblioteca jose:

import { createRemoteJWKSet, jwtVerify } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://oauth.telegram.org/.well-known/jwks.json'));

export async function verifyTelegramIdToken(idToken) {
  const { payload } = await jwtVerify(idToken, JWKS, {
    issuer: 'https://oauth.telegram.org',
    audience: '123456789' // tu Client ID (ID del bot)
  });
  return payload; // sub, id, name, preferred_username, picture, phone_number...
}

Telegram Login Widget clásico (legacy)

Muchos sitios todavía usan el Login Widget original basado en iframe. Su documentación está archivada, así que en proyectos nuevos usa el flujo anterior; si mantienes uno existente, así funciona.

  1. Envía /setdomain a @BotFather para vincular el dominio de tu sitio con el bot.
  2. Inserta el script. Con un callback:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-login="your_bot" data-size="large" data-onauth="onTelegramAuth(user)" data-request-access="write"></script>
<script type="text/javascript">
  function onTelegramAuth(user) {
    alert('Sesión iniciada como ' + user.first_name + ' ' + user.last_name + ' (' + user.id + (user.username ? ', @' + user.username : '') + ')');
  }
</script>

En lugar de data-onauth puedes usar data-auth-url="https://example.com/auth/telegram": el usuario se redirige ahí con id, first_name, last_name, username, photo_url, auth_date y hash como parámetros de la query. Otras opciones del configurador: data-size (large, medium, small), data-userpic="false", data-radius y data-request-access="write".

Verificar el hash en el servidor

No confíes en los datos hasta verificarlos. El algoritmo: toma todos los campos recibidos excepto hash, ordénalos alfabéticamente y únelos como key=value con un salto de línea (\n) para obtener el data-check-string; la clave secreta es el SHA256 del token del bot (bytes crudos); calcula el HMAC-SHA-256 del data-check-string con esa clave y compara su forma hex con hash. Después comprueba que auth_date (timestamp Unix) sea reciente. Usa solo los campos que envió Telegram, no tus propios parámetros de la query.

import hashlib
import hmac
import time

def check_telegram_auth(data: dict, bot_token: str, max_age: int = 86400) -> bool:
    fields = {k: v for k, v in data.items() if k != "hash"}
    data_check_string = "\n".join(f"{k}={fields[k]}" for k in sorted(fields))
    secret_key = hashlib.sha256(bot_token.encode()).digest()
    calc_hash = hmac.new(secret_key, data_check_string.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(calc_hash, str(data.get("hash", ""))):
        return False
    return time.time() - int(fields["auth_date"]) <= max_age

# Flask: check_telegram_auth(request.args.to_dict(), BOT_TOKEN)
const crypto = require('crypto');

function checkTelegramAuth(data, botToken, maxAgeSec = 86400) {
  const { hash, ...fields } = data;
  const dataCheckString = Object.keys(fields).sort()
    .map((k) => `${k}=${fields[k]}`)
    .join('\n');
  const secretKey = crypto.createHash('sha256').update(botToken).digest();
  const calcHash = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest('hex');
  if (typeof hash !== 'string' || hash.length !== calcHash.length) return false;
  if (!crypto.timingSafeEqual(Buffer.from(calcHash), Buffer.from(hash))) return false;
  return Date.now() / 1000 - Number(fields.auth_date) <= maxAgeSec;
}

// Express: checkTelegramAuth(req.query, process.env.BOT_TOKEN)

Un token equivocado es la causa más común de que el hash no coincida. Comprueba que el token de tu servidor pertenece al bot del login con getMe en el Bot API Tester: el username devuelto debe ser igual a data-telegram-login. Si necesitas encontrar o renovar el token, revisa la guía del token del bot. Ojo: esto no es lo mismo que validar el initData de una Mini App, donde la clave se deriva con HMAC y la cadena WebAppData.

Insertar un post de Telegram en tu web

Puedes insertar cualquier mensaje de un canal o grupo público. Abre su enlace t.me (p. ej. t.me/durov/43) en el navegador y haz clic en < > EMBED, o pega el enlace en el configurador del widget de post. El resultado es una sola etiqueta script:

<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-post="durov/43" data-width="100%"></script>

Opciones del configurador: ancho (data-width, por defecto 100%), foto del autor (data-userpic="true" para mostrarla siempre, "false" para ocultarla, sin el atributo en modo automático), color de acento (data-color con un valor hex como 13B4C6) y tema oscuro (data-dark="1"; con un color, el configurador puede agregar también data-dark-color).

Widget de discusión: comentarios de Telegram en tu sitio

El widget de discusión muestra un post de un canal público junto con sus comentarios. Pásale el enlace a un post con comentarios:

<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-discussion="contest/198" data-comments-limit="5"></script>

También puedes pasar solo el canal (data-telegram-discussion="your_channel"). Así, cada página de artículo muestra la discusión del post del canal que enlaza a ella, en cuanto publiques ese enlace en el canal. Para este modo, el head de tu página debe incluir <link rel="canonical" href="%page_url%"> con la URL canónica de la página. Opciones: límite de comentarios (data-comments-limit, de 3 a 50 en el configurador), data-height, data-colorful="1" para nombres de distintos colores, data-color y data-dark="1".

Botón compartir de Telegram

Cuando el visitante pulsa el botón compartir, Telegram le pide elegir un chat, grupo o canal y le deja editar el texto opcional antes de enviarlo. El constructor de core.telegram.org/widgets/share genera:

<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-share-url="https://example.com/article" data-comment="¡Mira esto!" data-size="large"></script>

Sin data-size obtienes el botón mediano; data-text="notext" muestra solo el ícono. Para un diseño propio, enlaza a https://t.me/share/url?url={url}&text={text} con ambos valores codificados para URL:

<a href="https://t.me/share/url?url=https%3A%2F%2Fexample.com%2Farticle&text=%C2%A1Mira%20esto%21">Compartir en Telegram</a>
const shareUrl = 'https://t.me/share/url?url=' + encodeURIComponent(location.href)
  + '&text=' + encodeURIComponent(document.title);
document.querySelector('#tg-share').href = shareUrl;

Solución de problemas

Siguientes pasos

Preguntas frecuentes

¿Cómo agrego un botón de iniciar sesión con Telegram a mi sitio web?

Elige un bot, abre la mini app de @BotFather, selecciona el bot y luego Login Widget, agrega el origen de tu sitio y tus redirect URIs como Allowed URLs y copia el Client ID. Después pega el snippet de telegram-login.js con data-client-id en tu página y verifica el id_token recibido en tu servidor.

¿El Telegram Login Widget clásico sigue funcionando?

Su documentación está archivada en core.telegram.org/widgets/login-legacy. Hoy Telegram documenta la biblioteca Telegram Login y un flujo OpenID Connect como la forma principal de iniciar sesión con Telegram, así que úsalos en proyectos nuevos.

¿Cómo verifico en el servidor los datos del Telegram Login Widget?

En el widget clásico, arma el data-check-string con todos los campos recibidos excepto hash, ordenados alfabéticamente como líneas key=value unidas con \n. Calcula su HMAC-SHA-256 usando SHA256(bot_token) como clave y compara el resultado en hex con hash; revisa también auth_date. En el login nuevo, valida el JWT id_token con el JWKS de Telegram.

¿Cómo inserto un post de Telegram en mi página web?

Abre el enlace t.me del post (por ejemplo t.me/durov/43) en el navegador y haz clic en EMBED, o usa el configurador de core.telegram.org/widgets/post. Solo se pueden insertar posts de canales y grupos públicos.

¿Cómo hago un botón compartir de Telegram personalizado?

Enlaza a https://t.me/share/url?url={url}&text={text} con ambos valores codificados para URL, por ejemplo con encodeURIComponent en JavaScript. El texto es opcional y el usuario puede editarlo antes de enviar.

Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje

Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.

Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso

Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.

Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)

Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.

Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)

Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.

Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas

Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.

Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas

Usa el servidor de pruebas de Telegram: entra al entorno de pruebas, crea un bot de prueba, llama a la Bot API con /test/ y activa TEST en nuestro tester.

API JavaScript de TelegramWidget: referencia, eventos, errores y límites

Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.

Ejemplos de widgets de Telegram: HTML completo y bot en Python

Ejemplos de widgets de Telegram listos para usar: tarjeta de pedido, contador con widget_query, encuesta compartida en vivo y vista previa en el navegador.

Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot

Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.