Telegram Bot API

Telegram Bot API 10.0–10.5: configurações do bot, widgets, rich messages, mensagens efêmeras, guest mode e mais

· 8 min de leitura

O Telegram Bot API 10.5, lançado em 22 de novembro de 2026, é a versão atual do Bot API, com 194 métodos. A série 10.x, que começou com o Bot API 10.0 em 8 de maio de 2026, trouxe guest mode, live photos, rich messages com rascunhos em streaming, mensagens efêmeras, comunidades, join request queries, widgets HTML interativos dentro das mensagens (10.4) e, no 10.5, o método setMySettings e o novo objeto BotFullInfo devolvido pelo getMe. Abaixo estão as novidades de cada versão, com exemplos curtos em JSON e as mudanças que podem quebrar um bot que já está no ar.

Telegram Bot API 10 num relance

VersãoDataDestaques
10.08 de maio de 2026Guest mode, live photos, mídia em enquetes, remoção de reações
10.111 de junho de 2026Rich messages e rascunhos rich, join request queries
10.214 de julho de 2026Mensagens efêmeras, comunidades, update subscription, proteção de origem das Mini Apps
10.324 de agosto de 2026EphemeralMessageParameters, rascunhos interrompíveis, DisabledButton, botões em rich messages
10.49 de novembro de 2026Widgets HTML, respostas efêmeras a callback queries em qualquer chat, citações de rich messages, cartão de carteira TON, temas de compartilhamento do chat
10.522 de novembro de 2026setMySettings, BotFullInfo no getMe, callback_query_mode, links de convite do bot, blocos em citações expansíveis

Bot API 10.0: guest mode, live photos e enquetes

Guest mode. Depois que você ativa o Guest Mode na Mini App do @BotFather, os usuários podem mencionar o bot em chats dos quais ele não participa. O bot recebe um update guest_message e pode mandar uma resposta com answerGuestQuery, passando o guest_query_id da mensagem e um InlineQueryResult:

{
  "guest_query_id": "<message.guest_query_id>",
  "result": {
    "type": "article",
    "id": "1",
    "title": "Tradução",
    "input_message_content": {"message_text": "Bonjour tout le monde"}
  }
}

Um bot convidado não tem acesso ao histórico nem à lista de membros do chat e não vê as mensagens seguintes, a não ser que seja mencionado ou respondido de novo.

Bot API 10.1: rich messages do Telegram e join request queries

Rich messages servem para saídas estruturadas, como relatórios, documentação e respostas de IA. O sendRichMessage recebe um objeto rich_message com o conteúdo em html ou markdown (o 10.2 adicionou blocks explícitos e uma lista media). Suporta títulos, listas e listas de tarefas, tabelas, citações, blocos recolhíveis, notas de rodapé, fórmulas LaTeX, mapas, colagens, slideshows e blocos de mídia. Limites: 32768 caracteres UTF-8, 500 blocos, 16 níveis de aninhamento, 50 mídias e 20 colunas de tabela.

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendRichMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "rich_message": {
      "markdown": "# Relatório semanal\n\n| Métrica | Valor |\n|:-------|------:|\n| Usuários | **1204** |\n| Erros | 3 |\n\n- [x] Deploy v2.1\n- [ ] Atualizar docs\n\n$$E = mc^2$$"
    }
  }'

O sendRichMessageDraft faz streaming de uma rich message parcial num chat privado enquanto ela é gerada. O rascunho é uma prévia temporária de 30 segundos, então finalize com sendRichMessage. O editMessageText agora também aceita rich_message.

Join request queries. Quando o seu bot é configurado como bot guardião de um chat, o update chat_join_request traz um query_id. Decida na hora com answerChatJoinRequestQuery (approve, decline ou queue para deixar a decisão com outros admins), ou mostre antes uma Mini App com sendChatJoinRequestWebApp; a Mini App recebe chat_join_request_query_id nos dados de inicialização.

{"chat_join_request_query_id": "<chat_join_request.query_id>", "result": "approve"}

As enquetes também ganharam mídia do tipo link no 10.1.

Bot API 10.2: mensagens efêmeras, comunidades e segurança das Mini Apps

Mensagens efêmeras são mensagens de grupo visíveis só para um usuário e o bot, o que tira dicas, boas-vindas e resultados pessoais da timeline compartilhada. Os usuários também podem enviar comandos efêmeros (BotCommand.is_ephemeral) que ninguém mais vê. Regras de entrega:

Mensagens efêmeras têm métodos próprios: editEphemeralMessageText, editEphemeralMessageMedia, editEphemeralMessageCaption, editEphemeralMessageReplyMarkup e deleteEphemeralMessage:

{"chat_id": -1001234567890, "receiver_user_id": 123456789, "ephemeral_message_id": 15}

Bot API 10.3: EphemeralMessageParameters, rascunhos interrompíveis e DisabledButton

Mudança incompatível nas mensagens efêmeras. Os parâmetros receiver_user_id e callback_query_id do 10.2 foram substituídos em 13 métodos de envio (sendMessage, sendPhoto, sendVideo, sendAnimation, sendAudio, sendDocument, sendLivePhoto, sendSticker, sendVideoNote, sendVoice, sendContact, sendLocation, sendVenue) por um único objeto, ephemeral_message_parameters. O sendRichMessage também o aceita, e o novo replace_callback_query_message mostra a mensagem efêmera no lugar da mensagem com o botão pressionado:

{
  "chat_id": -1001234567890,
  "text": "Só você pode ver isto.",
  "ephemeral_message_parameters": {
    "receiver_user_id": 123456789,
    "callback_query_id": "<callback_query.id>",
    "replace_callback_query_message": true
  }
}

Rascunhos interrompíveis. Passe can_stop no sendMessageDraft ou no sendRichMessageDraft para mostrar um botão Stop. Quando o usuário toca nele, o bot recebe um update stopped_message_generation com chat e draft_id, e você pode cancelar o modelo. O keep_on_stop deixa o rascunho parcial visível por um tempo; envie-o como mensagem normal se ele precisar ficar.

import time
import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
text, last = "", 0.0
for chunk in generate_reply():          # o stream de tokens do seu LLM
    text += chunk
    if time.monotonic() - last > 0.5:   # não envie um rascunho por token
        requests.post(f"{API}/sendMessageDraft", json={"chat_id": 123456789,
                      "draft_id": 1, "text": text, "can_stop": True}, timeout=10)
        last = time.monotonic()
requests.post(f"{API}/sendMessage", json={"chat_id": 123456789, "text": text}, timeout=10)
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const post = (method, body) => fetch(`${API}/${method}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(10_000),
});

let text = "", last = 0;
for await (const chunk of generateReply()) {  // o stream de tokens do seu LLM
  text += chunk;
  if (Date.now() - last > 500) {               // não envie um rascunho por token
    await post("sendMessageDraft", { chat_id: 123456789,
      draft_id: 1, text, can_stop: true });
    last = Date.now();
  }
}
await post("sendMessage", { chat_id: 123456789, text });

Bot API 10.4: widgets do Telegram, respostas efêmeras em qualquer chat e carteira TON

Widgets. Agora os bots podem enviar pequenos blocos HTML interativos dentro das mensagens. Um widget é um documento HTML (até 32768 bytes, 4096 bytes após compressão zlib) que o app executa num sandbox sem acesso à rede, mais um estado que só o bot altera: chat_data para uma mensagem e public_data compartilhado onde quer que o widget apareça. Métodos novos: sendWidget, sendSharedWidget, answerWidgetQuery, editMessageWidgetData e editSharedWidgetData; updates novos: widget_query e shared_widget_query; o inline mode ganha InputWidgetMessageContent e InputSharedWidgetMessageContent (por enquanto só no servidor de testes).

{
  "chat_id": 123456789,
  "html": "<h3>Pedido #1042</h3><p>2 × Margherita, 1 × Limonada</p><p><strong>Total: R$ 23,50</strong></p>",
  "caption": "Pedido #1042: R$ 23,50"
}

Em produção, os widgets por enquanto só funcionam em chats privados e são enviados com conteúdo protegido, então não podem ser encaminhados; grupos, inline mode e encaminhamentos funcionam no servidor de testes. Mensagens com widget não podem ser copiadas com copyMessage / copyMessages, e a permissão can_send_other_messages agora também cobre widgets. Detalhes: widgets do Telegram explicados.

Respostas efêmeras a callback queries em qualquer chat (exceto chats de mensagens diretas de canal). Passe callback_query_id sem receiver_user_id em ephemeral_message_parameters, e a mensagem aparece só para quem tocou no botão. O receiver_user_id e o parâmetro chat_id dos métodos de envio agora são opcionais. Você continua precisando chamar answerCallbackQuery.

{
  "text": "Só você pode ver esta resposta.",
  "ephemeral_message_parameters": {"callback_query_id": "<callback_query.id>"}
}

Bot API 10.5: setMySettings, BotFullInfo e links de convite do bot

Configurações do bot pelo código. O novo método setMySettings altera configurações que antes só existiam no @BotFather. Todos os parâmetros são opcionais, então passe apenas os que quer mudar; o método devolve True:

{
  "supports_inline_queries": true,
  "inline_query_placeholder": "Buscar receitas...",
  "can_join_groups": false,
  "has_topics_enabled": true,
  "callback_query_mode": "auto"
}

Envie para https://api.telegram.org/bot<token>/setMySettings ou teste com o seu token no Bot API Tester, e depois chame getMe para conferir o resultado.

BotFullInfo (mudança incompatível). O getMe agora devolve o novo objeto BotFullInfo em vez de User, e os campos que só o getMe devolvia foram removidos de User. O BotFullInfo também traz active_usernames, inline_query_placeholder, needs_inline_query_location e has_topic_sidebar. Código que lê campos como can_join_groups, can_read_all_group_messages ou supports_inline_queries do resultado do getMe continua funcionando, porque esses campos estão no BotFullInfo. O que quebra é código que espera esses campos em outros objetos User e código tipado que declara o resultado do getMe como User.

Como atualizar um bot para o Bot API 10.5

  1. Atualize a sua biblioteca (python-telegram-bot, aiogram, grammY, Telegraf e outras) para uma versão que cite suporte ao Bot API 10.5 no changelog.
  2. Mova receiver_user_id e callback_query_id no estilo 10.2 para dentro de ephemeral_message_parameters.
  3. Se você passa uma lista explícita de allowed_updates, adicione os tipos novos que trata: guest_message, subscription, stopped_message_generation, widget_query, shared_widget_query.
  4. Afrouxe a validação de enquetes: agora uma única opção é permitida.
  5. Nas Mini Apps, garanta que toda chamada do Telegram.WebApp rode no domínio registrado.
  6. Renomeie StoryAreaPosition para AreaPosition se o seu código se refere ao tipo pelo nome.
  7. Trate o resultado do getMe como BotFullInfo e pare de ler campos exclusivos do getMe, como can_join_groups, em outros objetos User.
  8. Nas rich messages, monte citações expansíveis com blocks em vez de text.
  9. Se mudar o callback_query_mode para "auto" ou "inline", faça o handler de callback aceitar inline_message_id quando message não vier.
  10. Teste os métodos novos com o seu token no Bot API Tester: setMySettings, sendWidget, sendRichMessage, deleteEphemeralMessage e answerChatJoinRequestQuery.

Mensagens efêmeras e comuns compartilham a mesma base, então enviar mensagens pela API do Telegram é uma boa revisão, e limites do Telegram Bot API lista os limites das rich messages ao lado dos clássicos. O histórico completo está no changelog oficial do Bot API.

Perguntas frequentes

Qual é a versão mais recente do Telegram Bot API?

O Bot API 10.5, lançado em 22 de novembro de 2026, com 194 métodos. É a sexta versão da série 10.x, que começou com o Bot API 10.0 em 8 de maio de 2026. Ela trouxe o setMySettings, que permite ao bot mudar as próprias configurações, e o getMe agora devolve BotFullInfo. A versão anterior, 10.4 (9 de novembro de 2026), adicionou widgets HTML nas mensagens.

O que são rich messages no Telegram?

Rich messages (Bot API 10.1) são mensagens estruturadas enviadas com sendRichMessage: títulos, listas, tabelas, fórmulas LaTeX, blocos de mídia, mapas e, desde o 10.3, botões. O conteúdo vai em rich_message como HTML, Markdown ou blocos, com até 32768 caracteres UTF-8.

O que são mensagens efêmeras em bots do Telegram?

Mensagens efêmeras (Bot API 10.2) são mensagens num grupo ou supergrupo que só um usuário e o bot conseguem ver. Desde o 10.3 elas são enviadas com ephemeral_message_parameters no sendMessage e em outros métodos de envio; desde o 10.4 o bot também pode responder de forma efêmera a um callback query em qualquer chat, exceto chats de mensagens diretas de canal. A entrega não é garantida, principalmente se o usuário estiver offline.

Como fazer streaming de respostas de IA num bot do Telegram?

Num chat privado, chame sendMessageDraft ou sendRichMessageDraft várias vezes com o mesmo draft_id e depois envie o texto final com sendMessage ou sendRichMessage, porque o rascunho é só uma prévia temporária de 30 segundos. Com can_stop o usuário ganha um botão Stop e o bot recebe stopped_message_generation.

O que é o setMySettings do Telegram Bot API 10.5?

O setMySettings permite que o bot mude as próprias configurações sem o @BotFather: inline mode, privacy mode, entrada em grupos, conexões business, guest queries e join request queries, tópicos em chats privados, comunicação entre bots e callback_query_mode. Passe só os campos que quer alterar; o método devolve True. Os valores atuais vêm do getMe, que agora devolve BotFullInfo.

O que é o guest mode do Telegram Bot API 10.0?

O guest mode permite que o bot responda quando é mencionado num chat do qual não faz parte. O bot recebe um update guest_message e responde uma vez com answerGuestQuery, sem acesso ao histórico do chat. Ele é ativado na Mini App do @BotFather.

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 hospedar um bot do Telegram: deploy em VPS, Docker e serverless

Como hospedar e fazer deploy de um bot do Telegram: polling ou webhook, serviço systemd na VPS, Docker, Cloudflare Workers com secret_token e checklist.

Erros do Telegram Bot API: o que cada erro significa e como resolver

Erros do Telegram Bot API explicados: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Causas, soluções e código pronto.

Limites do Telegram Bot API: rate limit, erro 429, tamanho de arquivos e de mensagens

Rate limit do Telegram Bot API na prática: 30 msg/s, 1 msg/s por chat, 20/min em grupos, como tratar 429 e retry_after, limites de arquivo e de texto.

Comandos de bot no Telegram: setMyCommands, escopos e deep links com /start

Configure os comandos do bot do Telegram: /setcommands no @BotFather, setMyCommands com escopos e idiomas, parâmetro do /start e /cmd@bot em grupos.

Teclados de bot no Telegram: inline keyboard, botões de callback e reply keyboard

Botões no bot do Telegram: inline keyboard com callback_data, answerCallbackQuery, editar a mensagem após o clique, reply keyboard e ForceReply.

Integração n8n + Telegram: conecte o bot, dispare workflows e envie mensagens

Conecte o n8n ao Telegram: token do bot como Access Token, webhook do Telegram Trigger com HTTPS público, envio por chat id e soluções para erros comuns.

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.

Bot inline no Telegram: como ativar o modo inline e responder às consultas

Crie um bot inline no Telegram: ative o modo inline no @BotFather ou com setMySettings, trate updates inline_query e responda com answerInlineQuery.

Pagamentos com Telegram Stars em bots: faturas, pre-checkout, reembolsos e assinaturas

Receba pagamentos em Telegram Stars no seu bot: sendInvoice com XTR, pre_checkout_query, successful_payment, reembolsos e assinaturas, com código.

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.

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

Telegram no seu site: novo login com Telegram (OIDC), Login Widget clássico com checagem do hash, post incorporado, comentários e botão compartilhar.

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.

Como testar uma Mini App do Telegram: do mock no navegador ao app real

Teste sua Mini App do Telegram passo a passo: modo mock no navegador, localhost via túnel HTTPS, ambiente de testes, DevTools e validação do initData.