Telegram Bot API

Widgets do Telegram para site: login com Telegram, post incorporado, comentários e botão compartilhar

· 9 min de leitura

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

WidgetO que fazPrecisa de bot?Onde pegar o código
Telegram LoginCadastro e login com a conta do Telegram (OpenID Connect)Sim, além de Allowed URLs e um Client ID do @BotFatherConfigurador em core.telegram.org/bots/telegram-login
Login Widget (legado)O botão de login antigo em iframe, hoje arquivadoSim, com o domínio vinculado via /setdomaincore.telegram.org/widgets/login-legacy
Widget de postIncorpora uma mensagem de um canal ou grupo públicoNãoLink t.me → EMBED, ou o configurador de posts
Widget de discussãoMostra um post do canal com os comentáriosNãoConfigurador de discussão
Botão compartilharPermite que o visitante envie seu link para um chat, grupo, canal ou Mensagens SalvasNãoConstrutor 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.

  1. 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.
  2. 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.
  3. Guarde o Client ID e o Client Secret exibidos na mesma seção. O secret fica só no servidor.
  4. Adicione o botão à página.
  5. 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: o telegram-login.js se comunica com uma janela popup. Se o seu site envia Cross-Origin-Opener-Policy: same-origin, o login falha; remova o header ou use same-origin-allow-popups.

Scopes e endpoints OIDC

ScopeO que você recebeClaims
openidObrigatório. Identificador único e horário da autenticaçãosub, iss, iat, exp
profileID do usuário, nome, username, URL da fotoid, name, preferred_username, picture
phoneTelefone verificado, com consentimento do usuáriophone_number
telegram:bot_accessSeu 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.

  1. Envie /setdomain para o @BotFather para vincular o domínio do site ao bot.
  2. 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

Próximos passos

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.

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.