Telegram Serverless começou a hospedar Mini Apps no domínio tgcloud.ai

Em 6 de outubro, o Telegram atualizou o Serverless, sua plataforma para código de bots. Agora, ela também hospeda o frontend de Mini Apps: a saída de build é enviada junto com o bot em um único comando e é acessada em um endereço como app<id>.tgcloud.ai. O Mini App ganhou funções de servidor que ele chama a partir de telegram-web-app.js. A atualização afeta todos que mantêm o backend de um bot ou Mini App em seu próprio servidor, e aqueles que já migraram o bot para o Serverless em julho: o projeto antigo precisa ser migrado uma única vez para a nova estrutura de pastas do projeto.

Serverless é um backend para bots que o Telegram executa em seus próprios servidores. O código é escrito em módulos JavaScript comuns e executado em isolados V8, ou seja, em sandboxes leves dentro de um único processo, ao lado da Bot API. O código é acompanhado por um banco de dados SQLite e HTTP de saída. Não são necessários servidores próprios, contêineres ou webhooks. A primeira versão da ferramenta de linha de comando @tgcloud/cli foi lançada no npm em 12 de julho, e a página de documentação apareceu no web archive em 13 de julho. Naquela época, a plataforma só conseguia responder a atualizações de bot: a versão de julho da documentação não tinha uma seção sobre frontend, nem a palavra "endpoint".

O que mudou em 6 de outubro

O Mini App não requer mais hospedagem separada, certificado e servidor com API. O frontend é construído por qualquer bundler, a ferramenta de linha de comando compara os arquivos por hashes e carrega apenas os alterados. O endereço que push imprime é inserido no @BotFather como o endereço do Mini App.

O que fazer com um projeto na versão 0.1

A ferramenta de linha de comando 0.2.0 se recusará a funcionar com a estrutura antiga até que o projeto seja migrado para a nova. A migração é feita com um único comando:

• npx tgcloud upgrade move schema.js, lib/ e handlers/ para a pasta tgcloud/. Os nomes dos módulos (lib/cart, handlers/message) não mudam.
• As importações por nome de módulo continuam funcionando, mas a documentação aconselha a usar caminhos relativos com .js.

Para quem conecta um Mini App:

• push carrega a pasta de build como está e não constrói nada por si só. Se executado após uma alteração no frontend sem uma nova build, a versão anterior será enviada para produção. O script npm run deploy, que é adicionado pelo modelo de projeto, primeiro constrói e depois carrega.
• O Telegram Web abre Mini Apps em um iframe, portanto, o cabeçalho X-Frame-Options e o frame-ancestors estrito não podem ser definidos.
• O caminho /api/ no mesmo endereço é ocupado pelos endpoints, não é aconselhável colocar seus próprios arquivos lá.
• immutable na configuração é apenas para arquivos com hash no nome. Os outros serão mantidos no cache do navegador por um ano, e não haverá como revogá-los.
• Next.js, Nuxt, SvelteKit e Angular não são reconhecidos automaticamente pela ferramenta de linha de comando: primeiro é preciso configurar a exportação estática e inserir manualmente a pasta em "source".

Como um Mini App chama seu backend

No mesmo dia, às 09:27 UTC, o Telegram atualizou o telegram-web-app.js, o script que conecta qualquer Mini App. Nele, apareceu o objeto Telegram.WebApp.Serverless com o único método call. O método faz um POST para o endereço relativo /api/<nome>, ou seja, para o mesmo host de onde o aplicativo foi aberto. Portanto, a chamada funciona apenas para Mini Apps hospedados em tgcloud.ai: de um domínio próprio, a solicitação irá para o servidor próprio.

No cabeçalho Authorization, o script coloca a string TMA e o initData em base64. initData é um conjunto de campos assinados pelo Telegram sobre o usuário e o chat com o qual o cliente abre o Mini App. A plataforma verifica a assinatura antes de executar o código, e sem ela a solicitação recebe 401. O endpoint recebe o usuário já verificado em ctx.initData.user. Não é mais necessário verificar manualmente a assinatura initData, como é preciso fazer em seu próprio servidor, e um backend como este não possui uma API aberta que precise ser protegida.

Os erros são divididos em dois tipos. Um EndpointError, lançado intencionalmente pelo código, chega ao cliente com texto e parâmetros pelos quais o frontend pode se ramificar. Qualquer outra exceção é vista pelo cliente como um erro interno, e o texto real permanece nos logs, para que a estrutura do backend não seja exposta.

O que o servidor informa sobre si mesmo sem token

A ferramenta de linha de comando acessa a API em cloud.telegram.org. Um de seus métodos, /capabilities, responde sem autorização: ele descreve a estrutura do projeto, os modelos AGENTS.md e docs/tgcloud-sdk.md e uma lista de tipos de atualizações para os quais um handler pode ser anexado. Existem 27 desses tipos. A ferramenta de linha de comando compara o número do esquema do projeto com esta resposta e avisa se o servidor já conhece pastas que ela ainda não conhece. No código da ferramenta de linha de comando, há também um switch TGCLOUD_BETA=1, que direciona as solicitações para /beta. Em 6 de outubro, a resposta beta coincide com a principal.

Por que o domínio se chama .ai

O domínio tgcloud.ai foi registrado em 11 de setembro de 2026 através da GoDaddy. No mesmo dia, um certificado *.tgcloud.ai foi emitido para ele, um para todos os subdomínios do tipo app<id>. O endereço IP do domínio, 149.154.166.100, está na rede Telegram_Messenger_Network (AS62041). A raiz do domínio retorna um 404 vazio: a plataforma não tem uma vitrine, apenas subdomínios de aplicativos.

A própria extensão não prova nada: .ai é o domínio nacional de Anguilla, que há muito tempo é usado por projetos de tecnologia. E tgcloud.com está ocupado desde 2011 por um proprietário externo, então a escolha pode ter sido uma simples questão de nome disponível.

Mas a plataforma foi construída desde o primeiro dia em torno de agentes de IA que escrevem código e em torno de bots que geram respostas.

• O código é escrito por um agente. A seção «Building with AI» está na documentação desde julho. Cada novo projeto recebe um AGENTS.md que, segundo o próprio modelo, é lido automaticamente por Claude Code, Cursor e ferramentas semelhantes, e um manual do SDK em docs/. A documentação sugere abrir o projeto em um agente e descrever o bot com palavras, e chama essa etapa de primeira.
• O ambiente é projetado para código gerado. Nenhum pacote npm, um único SDK, regras rígidas como um arquivo por tipo de atualização. Quanto menos opções, menos o agente erra, e a documentação lista diretamente os acordos que a "geração de código comum" ignora.
• Um bot que gera uma resposta. Entre os 27 tipos de atualizações que o Serverless aceita, estão stopped_message_generation e guest_message. Ambos apareceram na Bot API na primavera e no verão, juntamente com outras funções para bots baseados em modelos de linguagem.

O que ainda não existe no Serverless é o próprio modelo. O SDK consiste em três partes: banco de dados (sdk/db), Bot API (sdk/api) e fetch. Para que um bot no Serverless responda com texto de um modelo de linguagem, ele passa por fetch para uma API externa com sua própria chave. A documentação de fetch discute separadamente a leitura de resposta por streaming como uma forma de receber a saída da API de IA por tokens.

O Telegram tem sua própria capacidade para redes neurais. Cocoon, uma rede de computação confidencial em GPU com pagamento em TON, foi apresentada por Durov na Blockchain Life 2025, e seu site é servido do mesmo endereço na rede Telegram que o telegram.org. Daqui surge uma hipótese: a próxima parte do SDK pode ser uma chamada de modelo integrada, sem chave externa e com pagamento via Telegram. A segunda hipótese diz respeito ao @BotFather: o editor de manipuladores, banco de dados e arquivos de Mini App já reside nele no telefone, e a descrição do bot por palavras em vez de código parece ser o próximo passo para tal editor. Nenhuma das hipóteses foi confirmada até agora, exceto pelo domínio e pela direção das últimas atualizações: na documentação, na ferramenta CLI e na resposta /capabilities de 6 de outubro, não há módulo para redes neurais.