Widgets do Telegram para site: login com Telegram, post incorporado, comentários e botão compartilhar
O Telegram oferece quatro widgets para sites: o Telegram Login (login com Telegram usando a conta do usuário), o widget de post (incorpora uma mensagem de um canal ou grupo público), o widget de discussão (mostra os comentários de um post do canal) e o botão compartilhar. Cada um é um pequeno snippet que você cola no HTML do seu site. Eles não têm nada a ver com os widgets interativos que os bots enviam dentro das mensagens desde a Bot API 10.4; para esses, veja widgets do Telegram nas mensagens do bot.
Widgets do Telegram para site: visão geral
| Widget | O que faz | Precisa de bot? | Onde pegar o código |
|---|---|---|---|
| Telegram Login | Cadastro e login com a conta do Telegram (OpenID Connect) | Sim, além de Allowed URLs e um Client ID do @BotFather | Configurador em core.telegram.org/bots/telegram-login |
| Login Widget (legado) | O botão de login antigo em iframe, hoje arquivado | Sim, com o domínio vinculado via /setdomain | core.telegram.org/widgets/login-legacy |
| Widget de post | Incorpora uma mensagem de um canal ou grupo público | Não | Link t.me → EMBED, ou o configurador de posts |
| Widget de discussão | Mostra um post do canal com os comentários | Não | Configurador de discussão |
| Botão compartilhar | Permite que o visitante envie seu link para um chat, grupo, canal ou Mensagens Salvas | Não | Construtor do botão ou um link simples |
Telegram Login: o novo login com Telegram (OpenID Connect)
O Telegram Login atual é uma biblioteca JavaScript somada a um provedor OpenID Connect padrão, com Authorization Code Flow e PKCE. Você pode usar o botão da biblioteca, qualquer biblioteca ou plataforma de identidade compatível com OIDC (o Telegram cita Keycloak, Authentik e Auth0 como exemplos) ou os SDKs nativos para iOS e Android.
- Configure um bot que represente o seu site (como criar um bot no Telegram). O usuário vê o nome e a foto dele na janela de confirmação, então use o nome e o logo do site.
- Cadastre as Allowed URLs. Abra o mini app do @BotFather, selecione o bot e depois Login Widget. Adicione as origens onde o botão vai aparecer (ex.:
https://example.com) e as redirect URIs do OIDC (ex.:https://example.com/auth/callback). O Telegram só processa logins e redirecionamentos para essas URLs cadastradas. - Guarde o Client ID e o Client Secret exibidos na mesma seção. O secret fica só no servidor.
- Adicione o botão à página.
- Valide o ID token no servidor antes de confiar em qualquer dado do usuário.
O código gerado pelo configurador oficial é assim (data-request-access é opcional: write permite que o bot mande mensagens ao usuário, phone pede o número de telefone 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">Entrar com Telegram</button>
<script>
function onTelegramAuth(data) {
if (data.error) return console.warn(data.error);
// Envie data.id_token para o servidor e valide lá
fetch('/auth/telegram', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({id_token: data.id_token})
});
}
</script>
O callback recebe id_token (um JWT do OIDC), user (os claims já decodificados) ou error. A biblioteca também tem uma API JS: Telegram.Login.init(InitOptions, callback), Telegram.Login.open([callback]) e Telegram.Login.auth(InitOptions, callback), com as opções client_id, scope, lang e nonce (uma string aleatória gerada no servidor que vai dentro do id_token, contra ataques de replay).
Popup e COOP: otelegram-login.jsse comunica com uma janela popup. Se o seu site enviaCross-Origin-Opener-Policy: same-origin, o login falha; remova o header ou usesame-origin-allow-popups.
Scopes e endpoints OIDC
| Scope | O que você recebe | Claims |
|---|---|---|
openid | Obrigatório. Identificador único e horário da autenticação | sub, iss, iat, exp |
profile | ID do usuário, nome, username, URL da foto | id, name, preferred_username, picture |
phone | Telefone verificado, com consentimento do usuário | phone_number |
telegram:bot_access | Seu bot pode mandar mensagens ao usuário depois do login | — |
Num cliente OIDC, use o documento de discovery https://oauth.telegram.org/.well-known/openid-configuration, response type code e PKCE com S256. Se for implementar o fluxo na mão, os endpoints são https://oauth.telegram.org/auth, https://oauth.telegram.org/token (POST no servidor com Basic auth base64(client_id:client_secret)) e https://oauth.telegram.org/.well-known/jwks.json. O Telegram não tem endpoint UserInfo separado: todos os dados vêm no ID token, então configure a sua biblioteca para pular a requisição de userinfo, se ela esperar uma.
Validar o ID token
Verifique a assinatura do JWT com as chaves do endpoint JWKS e depois confira se iss é https://oauth.telegram.org, se aud bate com o ID do bot (o valor que você passa como client_id) e se exp ainda não passou. Por padrão os tokens são assinados com RS256; ES256, EdDSA e ES256K podem ser escolhidos em Login Widget > Advanced no @BotFather (EdDSA e ES256K só permitem o scope openid). Exemplo em Node.js com a 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' // seu Client ID (ID do bot)
});
return payload; // sub, id, name, preferred_username, picture, phone_number...
}
Telegram Login Widget clássico (legado)
Muitos sites ainda usam o Login Widget original, baseado em iframe. A documentação dele foi arquivada, então use o fluxo acima em projetos novos; mas, se você mantém um site com o widget antigo, ele funciona assim.
- Envie
/setdomainpara o @BotFather para vincular o domínio do site ao bot. - Incorpore o script. Com 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('Logado como ' + user.first_name + ' ' + user.last_name + ' (' + user.id + (user.username ? ', @' + user.username : '') + ')');
}
</script>
Em vez de data-onauth, você pode usar data-auth-url="https://example.com/auth/telegram": o usuário é redirecionado para lá com id, first_name, last_name, username, photo_url, auth_date e hash como parâmetros de query. Outras opções do configurador: data-size (large, medium, small), data-userpic="false", data-radius e data-request-access="write".
Checar o hash no servidor
Nunca confie nos dados antes de verificá-los. O algoritmo: pegue todos os campos recebidos exceto hash, ordene em ordem alfabética e junte como key=value separados por quebra de linha (\n) — essa é a data-check-string; a chave secreta é o SHA256 do token do bot (bytes brutos); calcule o HMAC-SHA-256 da data-check-string com essa chave e compare o resultado em hex com hash. Depois confira se o auth_date (timestamp Unix) é recente. Passe só os campos que o Telegram enviou, não os seus próprios parâmetros de 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)Token errado é a causa mais comum de hash que não bate. Confirme que o token do servidor é mesmo do bot de login com o getMe no Bot API Tester: o username retornado tem que ser igual ao data-telegram-login. Para encontrar ou trocar o token, veja o guia do token do bot. Atenção: isso é diferente da validação do initData de Mini Apps, que deriva a chave com HMAC e a string WebAppData.
Incorporar post do Telegram no site
Dá para incorporar qualquer mensagem de um canal ou grupo público. Abra o link t.me dela (ex.: t.me/durov/43) no navegador e clique em < > EMBED, ou cole o link no configurador do widget de post. O resultado é uma única tag script:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-post="durov/43" data-width="100%"></script>
Opções do configurador: largura (data-width, padrão 100%), foto do autor (data-userpic="true" para mostrar sempre, "false" para esconder, omita para automático), cor de destaque (data-color com um valor hex como 13B4C6) e tema escuro (data-dark="1"; com cor, o configurador pode adicionar também data-dark-color).
Widget de discussão: comentários do Telegram no seu site
O widget de discussão mostra um post de canal público junto com os comentários. Passe o link de um post que tenha comentários:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-discussion="contest/198" data-comments-limit="5"></script>
Também dá para passar só o canal (data-telegram-discussion="your_channel"). Nesse caso, cada página de artigo mostra a discussão do post do canal que aponta para ela, assim que você publicar esse link no canal. Para esse modo, o cabeçalho da página precisa ter <link rel="canonical" href="%page_url%"> com a URL canônica da página. Opções: limite de comentários (data-comments-limit, de 3 a 50 no configurador), data-height, data-colorful="1" para nomes em cores diferentes, data-color e data-dark="1".
Botão compartilhar do Telegram
Quando o visitante clica no botão compartilhar, o Telegram pede para escolher um chat, grupo ou canal e deixa editar o texto opcional antes de enviar. O construtor em core.telegram.org/widgets/share gera:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-share-url="https://example.com/article" data-comment="Olha só isso!" data-size="large"></script>
Sem data-size o botão fica médio; data-text="notext" mostra só o ícone. Para usar o seu próprio design, crie um link para https://t.me/share/url?url={url}&text={text} com os dois valores codificados para URL:
<a href="https://t.me/share/url?url=https%3A%2F%2Fexample.com%2Farticle&text=Olha%20s%C3%B3%20isso%21">Compartilhar no Telegram</a>
const shareUrl = 'https://t.me/share/url?url=' + encodeURIComponent(location.href)
+ '&text=' + encodeURIComponent(document.title);
document.querySelector('#tg-share').href = shareUrl;
Problemas comuns
- O widget legado mostra "Bot domain invalid". O domínio não está vinculado ao bot. Envie
/setdomainao @BotFather para esse bot com o domínio exato da página. - O login novo não faz nada ou é recusado. A origem da página ou a redirect URI não está nas Allowed URLs do @BotFather, ou um header
Cross-Origin-Opener-Policy: same-originestá bloqueando o popup. - O widget não aparece. O
telegram-widget.jsé carregado detelegram.orge insere um iframe: det.mepara posts, discussões e o botão compartilhar, deoauth.telegram.orgpara o login legado. Uma Content-Security-Policy restritiva (script-src,frame-src) ou um bloqueador de anúncios pode impedir o carregamento. - Hash não bate. Token errado, uso do próprio token em vez do SHA256 dele como chave, campos a mais na data-check-string (seus próprios parâmetros de query), valores alterados ou separador errado. Use
\n, não&. - Não dá para incorporar o post. Só mensagens de canais e grupos públicos podem ser incorporadas; chats privados não têm link t.me público.
- Discussão vazia na página do artigo. Confira se a página tem a tag de link canônico e se o link publicado no canal aponta para essa URL canônica.
Próximos passos
- Crie um bot no Telegram para representar o seu site na janela de login.
- Encontre, teste e revogue o token do bot, necessário para a checagem do hash no widget legado.
- Widgets do Telegram nas mensagens do bot: os widgets HTML da Bot API 10.4, outro recurso.
- Documentação oficial: core.telegram.org/widgets.
Perguntas frequentes
Como colocar um botão de login com Telegram no meu site?
Escolha um bot, abra o mini app do @BotFather, selecione o bot e depois Login Widget, cadastre a origem do site e as redirect URIs em Allowed URLs e copie o Client ID. Depois adicione o snippet telegram-login.js com data-client-id na página e valide o id_token recebido no servidor.
O Login Widget antigo do Telegram ainda é suportado?
A documentação dele foi arquivada em core.telegram.org/widgets/login-legacy. Hoje o Telegram documenta a biblioteca Telegram Login e um fluxo OpenID Connect como forma principal de login com Telegram, então prefira esses dois em projetos novos.
Como validar os dados do Telegram Login Widget no servidor?
No widget legado, monte a data-check-string com todos os campos recebidos exceto hash, em ordem alfabética, no formato key=value e unidos por \n. Calcule o HMAC-SHA-256 dela usando SHA256(bot_token) como chave e compare o hex com hash; confira também o auth_date. No login novo, valide o JWT id_token com o JWKS do Telegram.
Como incorporar um post do Telegram no meu site?
Abra o link t.me do post (por exemplo t.me/durov/43) no navegador e clique em EMBED, ou use o configurador em core.telegram.org/widgets/post. Só dá para incorporar posts de canais e grupos públicos.
Como fazer um botão compartilhar do Telegram personalizado?
Crie um link para https://t.me/share/url?url={url}&text={text}, com os dois valores codificados para URL, por exemplo com encodeURIComponent em JavaScript. O texto é opcional e o usuário pode editá-lo antes de enviar.
Guias relacionados
Como criar um bot no Telegram grátis: do BotFather à primeira mensagem
Aprenda a criar bot no Telegram grátis com o @BotFather: pegue o token, teste com getMe e envie a primeira mensagem com curl e Python.
Como enviar mensagens pela API do Telegram com sendMessage (curl, Python e JavaScript)
Use a API do Telegram para enviar mensagens com sendMessage: exemplos em curl, Python e JavaScript, HTML e MarkdownV2, botões inline e erros comuns.
Telegram bot token: como pegar o token do bot, verificar e revogar
Veja como pegar o token do bot do Telegram no @BotFather, achar o token de um bot existente, testar com getMe e revogar um token vazado.
Como configurar o webhook do bot do Telegram: setWebhook, secret_token e n8n
Configure o webhook do bot do Telegram: requisitos de HTTPS e portas, setWebhook com secret_token, getWebhookInfo, deleteWebhook e erros comuns no n8n.
Chat id do Telegram: como pegar o ID de usuário, grupo, canal e tópico com o seu bot
Descubra o chat id do Telegram para o seu bot: getUpdates em chat privado, grupos, supergrupos (-100), canais e tópicos, e o que fazer se vier vazio.
Servidor de teste do Telegram: como testar um bot no ambiente de teste
Use o servidor de teste do Telegram: entre no ambiente de teste, crie um bot de teste, chame a Bot API via /test/ e ative o modo TEST no nosso tester.
API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites
Referência da API JavaScript TelegramWidget: propriedades, request(), eventos, códigos de erro, variáveis CSS, widget_query, answerWidgetQuery e limites.
Exemplos de widget do Telegram: HTML completo e bot em Python
Exemplos de widget do Telegram com código completo: card de pedido, contador com widget_query, enquete compartilhada ao vivo e prévia no navegador.
Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot
Widgets do Telegram (Bot API 10.4): o que são, como funcionam sendWidget, chat_data e public_data, onde já rodam e a diferença para Mini Apps.