Telegram Bot API 10.0–10.5: configurações do bot, widgets, rich messages, mensagens efêmeras, guest mode e mais
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ão | Data | Destaques |
|---|---|---|
| 10.0 | 8 de maio de 2026 | Guest mode, live photos, mídia em enquetes, remoção de reações |
| 10.1 | 11 de junho de 2026 | Rich messages e rascunhos rich, join request queries |
| 10.2 | 14 de julho de 2026 | Mensagens efêmeras, comunidades, update subscription, proteção de origem das Mini Apps |
| 10.3 | 24 de agosto de 2026 | EphemeralMessageParameters, rascunhos interrompíveis, DisabledButton, botões em rich messages |
| 10.4 | 9 de novembro de 2026 | Widgets 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.5 | 22 de novembro de 2026 | setMySettings, 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.
- Reações e admins:
deleteMessageReactionremove uma reação num grupo;deleteAllMessageReactionsremove até 10000 reações recentes de um usuário ou chat. OgetChatAdministratorsganhoureturn_bots. - Enquetes: mídia na enquete, nas opções e na explicação do quiz (
media,explanation_media), além demembers_onlyecountry_codes. O número mínimo de opções caiu de 2 para 1. - Live photos:
sendLivePhotoenvia uma foto com um vídeo curto; live photos também funcionam emsendMediaGroup,editMessageMediae mídia paga. - Outros:
getManagedBotAccessSettingsesetManagedBotAccessSettings,getUserPersonalChatMessages, mensagens entre bots por username quando os dois permitem, etextvazio nosendMessageDraftpara mostrar um placeholder "Thinking...".
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:
- Qualquer bot pode responder de forma efêmera em até 15 segundos após uma ação elegível: um callback query (pelo id) ou uma mensagem efêmera recebida (via
reply_parameters.ephemeral_message_id). - Um bot administrador do chat pode enviar uma mensagem efêmera a qualquer membro que não seja bot, a qualquer momento.
- A entrega não é garantida, principalmente se o usuário estiver offline.
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}
- Comunidades: supergrupos, canais e bots ligados em torno de um tema comum, com o tipo
Community, as mensagens de serviçocommunity_chat_addedecommunity_chat_removedeChatFullInfo.community. - Assinaturas: o novo update
subscriptioninforma mudanças na assinatura paga de um usuário. - Proteção de origem das Mini Apps: os métodos de Mini App são bloqueados quando chamados de uma origem diferente do domínio da Mini App. A proteção foi ativada para todas as Mini Apps em 20 de julho de 2026, com opção de desativar no @BotFather. Veja em como testar uma Mini App do Telegram o que isso muda na prática.
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ões desativados: o novo campo
disableddoInlineKeyboardButtonrecebe um objetoDisabledButton, por exemplo{"text": "Esgotado", "disabled": {}}; o botão não faz nada.InlineKeyboardMarkupeReplyKeyboardMarkuptambém ganharamforce_reply. - Rich messages: botões dentro da mensagem (
<tg-button>,<tg-button-row>), tabelas compactas, citações expansíveis e blocos de documento. - Admins: o direito
can_send_welcome_messagesemChatAdministratorRightsepromoteChatMember. - Edição de efêmeras: upload de arquivos novos no
editEphemeralMessageMedia,show_caption_above_medianoeditEphemeralMessageCaptionerich_messagenoeditEphemeralMessageText.
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>"}
}
- Citações de rich messages:
TextQuote.rich_textseReplyParameters.quote_rich_texts. - Carteira TON:
TonWalletCardeChatFullInfo.ton_wallet_card, a mensagem de serviçoton_wallet_transfer;StoryAreaPositionfoi renomeado paraAreaPosition. - Temas de compartilhamento do chat:
ChatFullInfo.share_themee o novo métodogetChatShareThemeBackdrops. - Presentes:
getUniqueGiftdevolve um presente único pelo nome;deleteBusinessAccountGiftapaga um presente comum de uma conta business gerenciada sem receber Stars por ele. - Entidades e verificação: novos tipos de
MessageEntity,ton_addressebank_card_number;custom_description_parse_modeecustom_description_entitiesemverifyUsereverifyChat. - Outros: a mensagem de serviço
paid_messages_waived; usuários Premium podem dar a até 2 bots seus usernames secundários terminados em agent, ai, app, game ou gay; links para tópicos em chats privados com o bot,https://t.me/<bot_username>/<message_thread_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:
- Inline mode:
supports_inline_queries,inline_query_placeholder,needs_inline_query_locationeinline_feedback_share_denominator(receber 1 a cada 1, 10, 100 ou 1000 resultados inline escolhidos; 0 desliga). - Grupos e privacidade:
can_join_groupsecan_read_all_group_messages(truedesativa o privacy mode). - Recursos:
can_connect_to_business,can_manage_bots,supports_guest_queries,supports_join_request_queriesecan_communicate_with_botspara comunicação entre bots. - Tópicos em chats privados:
has_topics_enabled,allows_users_to_create_topicsehas_topic_sidebar. - Callback queries:
callback_query_modedefine como o bot recebe callback queries de botões em mensagens enviadas por ele."default"sempre usa o campomessage;"auto"usainline_message_idquando a mensagem está inacessível para o bot;"inline"sempre usainline_message_idem vez demessage.
{
"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.
- Links de convite do bot: o dono do bot pode convidar até 10 usuários de uma vez para um chat privado com o bot via
https://t.me/botinvite/<bot_username>; depois o bot pode mandar mensagens aos convidados. OWriteAccessAllowedganhou o campoinviter. - Citações expansíveis (mudança incompatível): em
RichBlockExpandableBlockQuotationeInputRichBlockExpandableBlockQuotationo campotextfoi substituído porblocks, então uma citação expansível agora pode conter quaisquer blocos rich.
Como atualizar um bot para o Bot API 10.5
- 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.
- Mova
receiver_user_idecallback_query_idno estilo 10.2 para dentro deephemeral_message_parameters. - 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. - Afrouxe a validação de enquetes: agora uma única opção é permitida.
- Nas Mini Apps, garanta que toda chamada do
Telegram.WebApprode no domínio registrado. - Renomeie
StoryAreaPositionparaAreaPositionse o seu código se refere ao tipo pelo nome. - Trate o resultado do
getMecomoBotFullInfoe pare de ler campos exclusivos do getMe, comocan_join_groups, em outros objetosUser. - Nas rich messages, monte citações expansíveis com
blocksem vez detext. - Se mudar o
callback_query_modepara"auto"ou"inline", faça o handler de callback aceitarinline_message_idquandomessagenão vier. - 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.
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 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.