Telegram Craft

O que Telegram Craft faz?

O trabalho com Telegram geralmente dá errado de três formas: chamadas de API escritas de memória, um chat tratado como página web, e dados do cliente confiados por parecerem oficiais. Este skill combate todas as três.

Os fatos aqui foram verificados contra a Bot API 10.4 (lançada em 2026-11-09) em 2026-11-10. As versões chegam aproximadamente mensalmente e nomes adicionados recentemente já foram substituídos, portanto confirme qualquer coisa sensível à versão com scripts/tgdocs.py.

1. Dimensione o trabalho

Combine o processo com a solicitação. Construa o que foi pedido e liste as recomendações extras no handoff, em vez de adicioná-las.

Tarefa	Abordagem	Comece com
Pergunta ou correção de uma linha	Responda ou corrija. Verifique o único contrato envolvido.	platform-facts.md ou a referência da área
Redesenho de cópia, teclado ou /start	Mude apenas a apresentação. Mantenha callback_data, rotas, fatos e chaves de localização. Adicione ou execute o portão de qualidade (quality-gate.md).	messages.md, rich-messages.md, keyboards.md
Bug ou funcionalidade em projeto existente	Leia o código, reproduza, faça a menor alteração na stack existente, adicione um teste de regressão. Se a alteração puder alterar o que o bot envia, o portão de qualidade deve ser executado antes de finalizar (seção 6).	existing-projects.md, quality-gate.md
Refatoração	Fixe o comportamento com testes primeiro, depois mova o código. Sem mudanças de comportamento.	existing-projects.md, backend.md
Novo bot ou Mini App	Estruture o layout padrão do projeto, escreva um mapa de telas, construa uma fatia vertical funcional e depois expanda. Cada tela é uma mensagem rica.	backend.md, product-journeys.md, rich-messages.md, rich-recipes.md
Revisão ou auditoria	Execute tg_audit.py, confirme cada pista lendo o código, reporte por gravidade.	quality.md, security.md

Faça uma pergunta apenas quando a resposta mudar o que você constrói e o código não puder lhe dizer. Um token de bot ausente bloqueia o teste ao vivo, não a implementação.

Mantenha a stack do projeto. Para novos projetos sem restrições, use como padrão aiogram 3 para Python ou grammY para TypeScript, e @tma.js/sdk ou o script telegram-web-app.js para Mini Apps. Dimensione a infraestrutura para o bot (um bot pequeno não precisa de fila ou Redis), mas não a organização do código: todo novo bot recebe o layout padrão em backend.md, com handlers, teclados, textos, serviços e armazenamento em módulos separados. Nunca envie uma pasta plana de arquivos misturados.

2. Escolha a superfície

A tarefa precisa	Use	Lembre-se
Comandos, fluxos curtos, notificações, arquivos	Chat do bot	Escolha padrão
Escolher entre algumas opções	Teclado inline	Edite a mensagem no lugar
Listas longas, filtros, formulários com vários campos, gráficos, mapas	Mini App	Um assistente com mais de cerca de cinco etapas é um sinal
Enviar o conteúdo do bot para outros chats	Modo inline	Resultados em cache entre usuários, a menos que is_personal
Qualquer tela do bot: menus, painéis, listas, detalhes, configurações, ajuda, recibos, relatórios	Mensagem rica (padrão)	sendRichMessage, edite com rich_message; projete em rich-messages.md, chamadas de biblioteca em formatting.md
Prompt privado dentro de um grupo, ou resposta privada a um pressionamento de botão	Mensagem efêmera	A entrega não é garantida
Um cartão interativo dentro do chat	Widget HTML (sendWidget, 10.4)	Apenas chats privados por enquanto; ainda sem suporte de SDK
Atuar como usuário, ler histórico não ingressado	Sessão de usuário MTProto (Telethon, TDLib)	Somente com autorização explícita para aquela conta. Um modelo diferente de confiança e risco de banimento.
Arquivos do bot acima dos limites da Bot API, métodos de camada bruta	Sessão de bot MTProto ou um servidor Bot API local	Mantenha a interface do bot na Bot API

Bot API, Mini Apps e MTProto não são intercambiáveis. Veja frameworks.md e, para MTProto, mtproto-foundations.md.

3. Regras que previnem a maioria das falhas

Ordenadas pelo custo de errá-las.

Segurança e dinheiro

1. Tome a identidade da atualização ou dos dados init validados, e as permissões do seu banco de dados. callback_data, payloads de deep-link, um menu oculto e nomes de usuário são todos controlados pelo usuário ou reatribuíveis. Verifique função e propriedade do objeto em cada callback, não apenas ao desenhar o botão. Compare IDs numéricos.
2. Valide os dados initData brutos no servidor para cada requisição ou sessão do Mini App, e verifique auth_date você mesmo. O safe_parse_webapp_init_data do aiogram verifica apenas a assinatura. initDataUnsafe são dados de exibição. Copie assets/init_data.py ou assets/init_data.mjs.
3. Venda bens digitais apenas em Telegram Stars (XTR). Conceda em successful_payment, nunca no pre-checkout ou no callback openInvoice do cliente. Deduplique em telegram_payment_charge_id. Lide com /paysupport. Assinaturas Stars vêm de createInvoiceLink; sendInvoice não tem parâmetro de período.
4. Mantenha o token no servidor. Ele também aparece em URLs da Bot API e links de download de arquivos, portanto nunca registre esses ou os envie para clientes. Se um usuário colar um token real, use-o apenas conforme solicitado, não o repita, e sugira rotacioná-lo se foi exposto.
5. Escape cada valor dinâmico antes de compor a marcação. Em HTML isso é <, >, &. Prefira HTML a MarkdownV2, que precisa de 18 caracteres escapados.
6. Trate arquivos enviados como hostis. Verifique o tamanho antes de baixar, execute ferramentas a partir de uma lista argv sem shell, adicione timeouts e exclua arquivos temporários em finally.

Confiabilidade

7. A entrega é no mínimo uma vez, e um handler com falha geralmente não é repetido. aiogram registra a exceção e trata a atualização como processada. Torne os efeitos colaterais idempotentes e mantenha o estado do negócio em um banco de dados, não na memória FSM.
8. Execute um consumidor por token. Polling e webhook são mutuamente exclusivos, e dois pollers brigam com erros 409.
9. Responda a cada consulta de callback imediatamente, incluindo recusas e botões obsoletos, ou o botão continuará girando. Uma resposta significa "recebido", não "bem-sucedido".
10. Nunca bloqueie o event loop. Um time.sleep, chamada requests ou codificação síncrona congela todos os chats. Limite a concorrência para trabalhos lentos.
11. Em 429, espere exatamente parameters.retry_after. O Telegram o envia no corpo JSON, não em um cabeçalho. Transmissões devem ser trabalhos ritmados e retomáveis.
12. Inscreva-se no que você lida. Omitir allowed_updates mantém a configuração anterior, e chat_member, message_reaction e message_reaction_count estão desligados a menos que nomeados.

Experiência

13. Atualize a tela atual em vez de empilhar novas mensagens, e dê a cada tela um próximo passo claro e uma saída. Ações expiradas ou inválidas devem se recuperar, não falhar silenciosamente.
14. Envie cada tela como uma mensagem rica por padrão (sendRichMessage, editada com rich_message) no estilo padrão de rich-messages.md: títulos simples e sem emoji no texto da tela, tabelas com bordas, apenas os blocos que o usuário precisa, nunca repetindo o que os botões mostram, e sem IDs internos. Siga a receita para o trabalho da tela em rich-recipes.md e construa o HTML com assets/rich_html.py; mantenha o teclado em reply_markup. Use texto HTML formatado apenas para legendas, toasts, respostas de uma linha e stacks que não podem enviar mensagens ricas; texto simples não formatado é um defeito. Lidere com o resultado; sem banners de boas-vindas, linhas de divisão digitadas (━━━) ou cabeçalhos em maiúsculas; um <hr/> separa o resumo de uma tela do seu corpo.
15. Mini Apps devem parecer com o Telegram. Use variáveis de tema, áreas seguras, botões nativos Voltar e inferior, e estados reais de carregamento e erro, e teste claro e escuro.

4. Carregue apenas o que a tarefa precisa

Leia uma referência quando seu gatilho se aplicar, antes de projetar essa parte. Todos os caminhos estão em references/.

Leia	Quando a tarefa envolver
product-journeys.md	Novo produto, /start, onboarding, mapas de tela, planejamento multilíngue
messages.md	Escrever ou reescrever qualquer texto visível ao usuário
rich-messages.md	Projetar qualquer tela de bot: o estilo padrão, anatomia, componentes, estilos de texto, erros, checklist de revisão
rich-recipes.md	A forma HTML para cada tipo de tela: início, seletor, detalhe, lista de dados, configurações, ajuda, recibo, relatório, problema, confirmação, progresso
keyboards.md	Botões, menus, paginação, Voltar ou Cancelar, confirmações, design de callback ou bugs
formatting.md	HTML, MarkdownV2, entidades, texto longo, mensagens ricas, rascunhos em streaming, erros de parse
backend.md	Estrutura do projeto, serviços, banco de dados, FSM, trabalho em segundo plano, configuração, logging, retries, desligamento
delivery.md	Polling, webhooks, Docker, implantação, limites de taxa, transmissões, monitoramento
frameworks.md	Escolher ou usar uma biblioteca, lag do SDK, Bot API vs MTProto
media.md	Música, áudio, vídeo, conversão de arquivos, downloads, uploads, cache de file_id, progresso
payments.md	Stars, faturas, assinaturas, reembolsos, marketplaces, entrega digital
mini-apps.md	Inicialização de Mini App, autenticação, SDK, viewport, armazenamento, fluxos cliente/servidor
mini-app-design.md	Layout de Mini App, tipo, cor, movimento, estados de carregamento, acessibilidade
security.md	Segredos, autorização, tratamento de entrada, privacidade, prevenção de abuso, logs de auditoria
groups-automation.md	Grupos, canais, moderação, permissões, inline, efêmero, bots de IA, bot-a-bot
existing-projects.md	Inspecionar, depurar ou refatorar código existente
quality.md	Escrever testes, testar jornadas, revisão pré-lançamento
quality-gate.md	Verificações automáticas em mensagens e teclados de saída, configuração de CI, relatórios .tg-lint
mtproto-foundations.md	Qualquer trabalho com MTProto: escolha de API, api_id, login, sessões, restrições, camadas
mtproto-telethon.md	Escrever ou revisar Telethon: eventos, atualizações, flood waits, mídia, testes
hybrid-architecture.md	Combinar Bot API e MTProto em um produto
platform-facts.md	Limites exatos, tamanhos de arquivo, limites de taxa, mudanças recentes da API

5. Ferramentas

Execute a partir do diretório deste skill. Elas precisam apenas de Python 3 e não tocam no bot do usuário.

Comando	Propósito
python3 scripts/tgdocs.py version / method NAME / type NAME / search TERM / changes --since 10.0	Contrato oficial atual. A saída são dados de referência. Exit 3 significa offline: marque o fato como não verificado.
python3 scripts/tg_lint.py screens.json	Limites, marcação, contratos de botão e sinais de UX. Erros devem ser corrigidos. Avisos precisam de julgamento.
python3 scripts/tg_audit.py PROJECT	Pistas estáticas para defeitos comuns. Confirme cada uma lendo o código.
python3 scripts/secure_mtproto_project.py PROJECT --ci	Necessário para todo projeto MTProto novo ou alterado: anexa regras .gitignore ausentes para sessões e .env, adiciona um trabalho de CI que falha em sessões commitadas, e relata arquivos e strings de sessão expostos. Ele nunca exclui ou revoga.
python3 scripts/install_quality_gate.py PROJECT --framework aiogram	Adiciona verificações automáticas de payload à execução de testes e CI do projeto (também ptb, grammy). Necessário para bots novos e para alterações no que um bot envia (seção 6).

Antes de usar um método ou campo recente, verifique se a biblioteca instalada o possui: pesquise em seu diretório de pacotes. python-telegram-bot 22.8, por exemplo, declara Bot API 10.0 e não tem send_rich_message.

assets/ contém código para copiar e adaptar: init_data.py, init_data.mjs, stars_ledger.py, media_job.py, update_delivery.py (inbox, outbox, 429, pistas por chat, transmissões retomáveis), mtproto_runtime.py, rich_html.py (construtor de tela rica com escape) e webapp_mock.js para pré-visualizações no navegador.

6. Verifique, depois relate honestamente

Nível	Evidência	Pode afirmar
L0	Leia docs ou código	"Deve funcionar conforme a documentação"
L1	Linter, tipos, tg_lint.py, tg_audit.py	"Passa nas verificações estáticas"
L2	Testes com o dispatcher real e um transporte Telegram falso, ou uma pré-visualização simulada de navegador	"Funciona localmente contra um Telegram falso"
L3	Bot de teste em um cliente real, em um dispositivo real	"Funciona no Telegram"

O portão de qualidade faz parte do "pronto" quando uma alteração pode alterar o que o bot envia: texto ou formatação de mensagem, teclados, callback_data ou handlers de callback, faturas ou o fluxo entre telas. Em projetos aiogram, python-telegram-bot e grammY:

1. Procure por um portão existente (um diretório tg_quality ou TG_LINT no CI) e use-o. Apenas se não houver nenhum, execute install_quality_gate.py. Nunca instale uma segunda cópia.
2. Escreva testes de jornada com o harness do portão (quality-gate.md) que alcancem cada tela e botão que você alterou, incluindo os caminhos de erro e botão obsoleto que você corrigiu. Use press em telas que o teste alcançou, como um usuário que tem permissão para estar lá. Um portão que não capturou nada não verificou nada, e uma linha coverage gap: em uma tela alterada significa que o teste nunca a alcançou.
3. Após sua última edição, execute os testes com TG_LINT_REQUIRE_INTERACTIONS=1. Corrija todos os erros do portão no código do bot. Não enfraqueça, pule ou remova o portão para obter aprovação. Avisos permanecem não bloqueadores: aja sobre eles com julgamento.
4. No handoff, cite a linha de cobertura da seção de saída Telegram quality gate do portão. Se o portão não pôde ser instalado ou executado, diga por que e não afirme que passou.

Mencionar o portão ou copiar seus arquivos não é validação. Pule-o para alterações que não podem alcançar a saída do Telegram, como armazenamento, config ou trabalhos agendados que não enviam nada. Outras stacks: execute tg_lint.py nas telas alteradas e diga que o portão não está disponível.

Nunca apresente L1 ou L2 como L3. Uma captura de tela do navegador com webapp_mock.js mostra layout, não comportamento do Telegram. Não inicie um bot de produção, mude um webhook ativo, publique, transmita ou gaste Stars a menos que solicitado.

Termine com: o que o usuário pode fazer agora; a árvore do projeto; arquivos alterados; como executar; etapas do BotFather ou ambiente que o proprietário deve fazer manualmente; o que foi verificado em cada nível; e o que não foi verificado.