Por onde começar

O que é o Dromornis, em uma frase

É um editor onde você desenha o comportamento do bot em vez de digitá-lo. O resultado não é um bot preso a uma plataforma: é um arquivo bot.py de verdade, com requirements.txt, README.md e .env.example, que roda no seu computador, no seu servidor, onde você quiser.

Mapa da documentação

Convenções usadas neste manual

Ao longo do texto você vai encontrar caixas com significados fixos:

Os níveis Iniciante Intermediário Avançado aparecem em tutoriais e blocos para você calibrar por onde ir.

Introdução aos conceitos

Antes de arrastar o primeiro bloco, vale entender oito palavras. Elas se repetem em todo o manual, e depois de entendê-las o resto fica fácil.

O que é um bot

Tecnicamente: um bot do Telegram é um programa que se autentica na Bot API do Telegram usando um token, recebe eventos (mensagens, cliques em botões, entradas em grupo) e responde chamando métodos HTTP da API. Ele tem uma conta própria no Telegram, com @username terminado em bot, mas não é operado por uma pessoa.

O que um bot pode fazer: enviar e apagar mensagens, mostrar botões, banir usuários em grupos onde é administrador, guardar dados, consultar sites e APIs, cobrar pagamentos, agendar tarefas. O que ele não pode: ler mensagens de outras pessoas em conversas privadas onde não foi adicionado, iniciar conversa com alguém que nunca falou com ele, ou ver histórico anterior à sua entrada num grupo.

O que é automação

Tecnicamente: automação é a substituição de uma ação humana repetitiva por uma regra determinística: dado um gatilho, execute uma sequência de operações. A qualidade de uma automação se mede por três coisas — ela cobre os casos normais, trata os casos anormais (erro, dado faltando) e é observável (você consegue ver o que ela fez).

O que é um fluxo

Tecnicamente: no Dromornis um fluxo é uma pilha de blocos ligada a um bloco de evento. Ele tem um ponto de entrada único (o evento), executa de cima para baixo, pode se ramificar em condições e pode terminar antes do fim com o bloco parar por aqui. Cada fluxo vira uma função Python async no código gerado — um handler.

O que é um evento

Tecnicamente: um evento é a condição de disparo de um handler. No Dromornis, todo bloco de evento tem formato de "chapéu" — nada se encaixa acima dele, porque ele é o começo. Sem pelo menos um evento no workspace, o Dromornis avisa: "O bot precisa de pelo menos um evento", porque um bot sem evento é um programa que liga e não faz nada.

Exemplos de eventos: receber o comando /start, receber qualquer mensagem de texto, alguém clicar num botão, um usuário entrar no grupo, o bot ser iniciado. Veja todos em Categoria Eventos.

O que é um gatilho

"Gatilho" e "evento" são frequentemente usados como sinônimos, e na prática são. A diferença útil: o evento é o fato que aconteceu no mundo ("chegou uma mensagem"); o gatilho é a regra que você configurou para reagir a ele ("quando chegar uma mensagem que contenha a palavra preço"). O bloco quando a mensagem contiver ( ) é um evento com gatilho filtrado.

O que é um bloco

Tecnicamente: cada bloco é um nó em uma árvore sintática. Ele declara entradas (o que ele precisa receber), um tipo de saída (o que ele devolve) e um gerador que traduz o nó para uma expressão ou comando Python. Existem três formatos, e reconhecê-los é meio caminho andado:

O que é uma ação

Ação é tudo o que muda alguma coisa: envia mensagem, apaga mensagem, grava no banco, bane um usuário, espera 3 segundos. No código gerado, ações viram linhas de comando dentro da função do handler, executadas na ordem em que estão empilhadas.

A distinção prática entre evento e ação: o evento você não controla — ele acontece quando o usuário quiser. A ação você controla totalmente — ela acontece porque você mandou. Um fluxo é sempre um evento seguido de N ações.

O que é uma condição

Tecnicamente: uma condição avalia uma expressão booleana (verdadeiro/falso) e executa um dos ramos. No Dromornis isso é o bloco se … faça, opcionalmente com senão. A expressão dentro do "se" deve ser um bloco de valor booleano: uma comparação, um e/ou, ou um bloco que já devolve sim/não como é administrador?.

O que é uma variável

Tecnicamente: uma variável é um nome ligado a um valor na memória durante a execução do handler. No Dromornis, variáveis criadas na categoria Variáveis viram variáveis Python locais ao handler — elas não sobrevivem ao fim do fluxo. Para guardar algo entre mensagens ou entre reinícios do bot, use Banco de Dados ou os blocos salvar dado / carregar dado. Essa distinção é a fonte número 1 de confusão para iniciantes — ela está detalhada em Variáveis.

Juntando tudo

Um bot completo é: eventos (quando reagir) + ações (o que fazer) + condições (quando fazer diferente) + variáveis (o que lembrar) organizados em fluxos. Todo o resto — banco de dados, APIs, teclados, pagamentos — são variações mais poderosas dessas quatro peças.

Comece aqui — trilha de aprendizado

Nove etapas, na ordem. Cada uma se apoia na anterior. Se você pular etapas, provavelmente vai travar em algo que a etapa pulada explicava.

1. Entenda o que é um botConceitos: bot, fluxo, evento, bloco, variável. → Introdução aos conceitos Iniciante
2. Crie seu bot no TelegramFale com o @BotFather, escolha o nome e receba o token. → Criando o bot no BotFather Iniciante
3. Conecte o token ao DromornisCole o token no painel Projeto e configure a variável de ambiente. → Configurando o token Iniciante
4. Crie seu primeiro fluxoUm evento /start e uma mensagem de resposta. Exporte e rode. → Seu primeiro bot Iniciante
5. Aprenda variáveisGuarde o nome do usuário, monte textos dinâmicos, entenda escopo. → Variáveis Iniciante
6. Aprenda condiçõesFaça o bot responder diferente conforme a situação. → Controle e Operadores Intermediário
7. Aprenda teclados e botõesMenus clicáveis, callbacks e navegação. → Teclado Intermediário
8. Aprenda banco de dadosGuarde usuários, pedidos e histórico entre reinícios. → Banco de Dados Intermediário
9. Aprenda APIs e automação avançadaConsuma serviços externos, agende tarefas, trate erros. → Avançado Avançado

Quanto tempo leva

Os três erros que todo iniciante comete

Seu primeiro bot Iniciante

Tutorial completo, do projeto vazio até o bot respondendo no seu Telegram. Reserve 30 minutos. Não pule etapas — cada uma existe por um motivo.

Antes de começar

Você vai precisar de três coisas:

• Uma conta no Telegram (no celular ou no desktop).
• Python 3.10 a 3.13 instalado no computador onde o bot vai rodar. Não use 3.14 ou superior — a biblioteca python-telegram-bot ainda não é compatível com essas versões.
• Um terminal (PowerShell no Windows, Terminal no macOS/Linux). Você só vai digitar três comandos.

Passo 1 — Criar o projeto

Abra o Dromornis. Na barra superior, clique em Novo. Um projeto em branco é criado com um workspace vazio.

Se preferir partir de algo pronto, clique em Templates e escolha um exemplo. Atenção: escolher um template substitui os blocos atuais do workspace, então faça isso antes de começar a montar.

Passo 2 — Nome e descrição

Abra o painel lateral Projeto. Preencha:

Passo 3 — Criar o bot no Telegram (BotFather)

Esta etapa acontece dentro do Telegram, não no Dromornis.

1. No Telegram, procure por @BotFather (com o selo azul de verificado).
2. Envie /newbot.
3. Ele pergunta o nome do bot — o nome de exibição, pode ter espaços e acentos. Ex.: Bot da Padaria.
4. Ele pergunta o username — precisa ser único no Telegram inteiro e terminar em bot. Ex.: padaria_do_ze_bot.
5. Ele responde com uma mensagem contendo o token, algo como 123456789:AAH-YOUR_BOT_TOKEN-example.

Detalhes completos sobre o BotFather, incluindo os comandos /setdescription, /setcommands e /setprivacy, estão em Integração com o Telegram.

Passo 4 — Conectar o token ao Dromornis

De volta ao Dromornis, no painel Projeto, campo Token do bot (do @BotFather): cole o token. Use o botão mostrar/ocultar para conferir sem deixá-lo visível na tela.

Na aba inferior Configuração você define o nome da variável de ambiente (padrão: TELEGRAM_BOT_TOKEN), o username do bot (só informativo) e o parse_mode das mensagens. Deixe o padrão por enquanto.

Passo 5 — Criar o primeiro fluxo

No toolbox à esquerda, abra a categoria Eventos (amarela). Arraste para o canvas o bloco:

Agora abra Mensagens (roxa) e arraste enviar mensagem ( ) para dentro da boca do bloco de evento. Você vai sentir o encaixe. Se o bloco não encaixar, ele ficou solto — arraste de novo até a linha de conexão aparecer.

No buraco do enviar mensagem, encaixe um bloco de texto (categoria Operadores, o bloco " ") e escreva: Olá! Eu sou o bot da padaria. 🥖

Passo 6 — Conferir o código gerado

Na aba inferior Código Python, o código aparece e se atualiza em tempo real. Você deve ver algo próximo de:

async def start_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.effective_chat.send_message("Olá! Eu sou o bot da padaria. 🥖")


def main() -> None:
    application = Application.builder().token(TOKEN).build()
    application.add_handler(CommandHandler("start", start_command))
    application.run_polling()

Você não precisa entender cada linha. Precisa apenas confirmar que existe uma função para o seu comando e que ela envia a sua mensagem. Se a aba Validação estiver limpa ("Nenhum problema encontrado"), siga em frente.

Passo 7 — Salvar

Clique em Salvar. O projeto é gravado no localStorage do navegador e aparece na lista "Projetos salvos" do painel Projeto.

Passo 8 — Exportar

Clique em Exportar. Você tem três opções:

Escolha o .zip e descompacte numa pasta.

Passo 9 — Rodar o bot

Abra o terminal na pasta descompactada. Crie um ambiente virtual (uma "caixa isolada" para as bibliotecas deste projeto):

python -m venv .venv

Ative-o. Windows (PowerShell):

.venv\Scripts\Activate.ps1

Linux / macOS:

source .venv/bin/activate

Instale as dependências:

pip install -r requirements.txt

Se o ZIP não trouxe .env (você não preencheu o token no editor), copie .env.example para .env e coloque o token:

TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN

Execute:

python bot.py

O terminal deve mostrar linhas de log e ficar parado, esperando. Isso é o certo — o bot está no ar. Fechar o terminal derruba o bot.

Passo 10 — Testar

No Telegram, procure pelo @username que você escolheu no BotFather, abra a conversa e clique em Iniciar (ou envie /start). Sua mensagem deve chegar em menos de um segundo.

Se algo deu errado

Mais sintomas e diagnósticos em Depuração e erros.

Sobre "publicar"

Publicar um bot é mantê-lo rodando 24 horas por dia. No seu computador ele fica no ar só enquanto o terminal estiver aberto. Para produção, as opções usuais são:

• VPS (servidor virtual): copie a pasta, instale as dependências e rode sob um supervisor como systemd, pm2 ou supervisor, que reinicia o bot se ele cair.
• Container: empacote com um Dockerfile simples baseado em python:3.12-slim e rode com política de reinício.
• Plataforma de apps: qualquer serviço que execute um processo Python de longa duração. Bots em polling precisam de um processo sempre ligado, não de funções serverless que dormem.

Integração com o Telegram Intermediário

Como o Telegram, o seu bot e o Dromornis conversam entre si. Entender esta seção é o que separa "consegui fazer funcionar" de "sei por que funciona".

O que é a Bot API do Telegram

Tecnicamente: a Bot API é uma API HTTP sobre https://api.telegram.org/bot<TOKEN>/<método>. Cada operação é um método — sendMessage, deleteMessage, banChatMember — chamado por GET ou POST com parâmetros JSON. A resposta é sempre um JSON com {"ok": true, "result": …} ou {"ok": false, "error_code": …, "description": …}.

O Dromornis não te faz escrever essas chamadas: cada bloco da categoria Mensagens ou Moderação corresponde, no fundo, a um desses métodos. Saber disso ajuda quando você lê uma mensagem de erro da API — ela vem exatamente com o texto que o Telegram devolveu.

O BotFather

O @BotFather é o bot oficial do Telegram que cria e configura outros bots. Ele é a única maneira de obter um token. Comandos que valem conhecer:

O token: o que é e como protegê-lo

O token tem o formato <bot_id>:<segredo>, por exemplo 123456789:AAH-YOUR_BOT_TOKEN-example. A primeira parte é o ID numérico do bot (público, aparece em vários lugares); a segunda é o segredo.

Regras práticas:

• O token equivale a uma senha com poder total sobre o bot. Trate-o como trataria a senha do seu e-mail.
• Ele não entra no código-fonte. No Dromornis, o bot.py gerado sempre lê os.getenv("TELEGRAM_BOT_TOKEN").
• Ele fica no arquivo .env, que nunca vai para o controle de versão.
• Em servidores, prefira definir a variável de ambiente no próprio serviço em vez de subir o arquivo.
• Se vazar: /revoke no BotFather. Não existe "cancelar parcialmente".

enviar mensagem [ "meu token é 123456:AAH..." ]

# ou, no código:
TOKEN = "123456789:AAH-real-token"

# bot.py gerado pelo Dromornis
TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")

# .env (fora do git)
TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN

Conectando o token ao Dromornis

1. Painel Projeto → campo Token do bot → cole o token.
2. Aba Configuração → Variável de ambiente do token → confirme o nome (padrão TELEGRAM_BOT_TOKEN). Esse é o nome que vai aparecer no os.getenv() e no .env.
3. Exporte o ZIP. Se o campo de token estava preenchido, o ZIP traz um .env pronto; se não, traz apenas o .env.example como modelo.

Como validar que o token está correto: rode python bot.py. Se o token estiver errado, a biblioteca falha imediatamente com telegram.error.InvalidToken. Se estiver certo, o bot fica rodando em silêncio, aguardando mensagens. Para uma checagem manual rápida, abra no navegador:

https://api.telegram.org/botYOUR_BOT_TOKEN/getMe

Resposta esperada:

{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "Bot da Padaria",
    "username": "padaria_do_ze_bot",
    "can_join_groups": true,
    "can_read_all_group_messages": false
  }
}

Como o Telegram entrega as mensagens: updates

Tudo o que acontece com o seu bot chega como um objeto chamado update. Um update é um envelope que contém um tipo de acontecimento: uma mensagem nova, uma mensagem editada, um clique em botão, alguém entrando no grupo, uma resposta de enquete.

Exemplo simplificado de update para uma mensagem de texto:

{
  "update_id": 874512,
  "message": {
    "message_id": 142,
    "date": 1731000000,
    "text": "/start",
    "from": {
      "id": 987654321,
      "is_bot": false,
      "first_name": "Maria",
      "username": "maria_s",
      "language_code": "pt-br"
    },
    "chat": {
      "id": 987654321,
      "type": "private",
      "first_name": "Maria"
    }
  }
}

E para um clique em botão inline:

{
  "update_id": 874513,
  "callback_query": {
    "id": "4382bfdwdsb323b2d9",
    "data": "menu_precos",
    "from": { "id": 987654321, "first_name": "Maria" },
    "message": { "message_id": 143, "chat": { "id": 987654321 } }
  }
}

Os campos que você mais vai usar

Polling × Webhook

Existem duas formas de o bot receber os updates:

A jornada completa de uma mensagem

Este é o caminho inteiro, do dedo da pessoa até a resposta na tela:

Resumido na notação da arquitetura:

Cada bloco de evento no seu workspace vira o passo 4. Cada bloco de ação vira o passo 5-6. É literalmente isso — não há mágica escondida.

Conversas privadas, grupos e canais

Comandos

Comandos são mensagens que começam com /. O Telegram os trata de forma especial: mostra autocomplete, destaca em azul e permite um menu na interface.

• Formato: /nome argumento1 argumento2. No Dromornis, os argumentos ficam disponíveis pelo bloco argumentos do comando.
• Em grupos com vários bots, o Telegram entrega /comando@seu_bot. A biblioteca já cuida disso — você registra apenas comando.
• Use o bloco definir menu de comandos (categoria Mensagens) para popular o menu "/" automaticamente ao iniciar o bot. É melhor que o /setcommands manual porque a lista fica versionada junto com o fluxo.

Telegram avançado Avançado

Referência dos recursos da Bot API que aparecem quando o bot cresce: teclados inline, callbacks, deep linking, formatação, limites e tratamento de erros.

Inline keyboards

São os botões que ficam presos à mensagem, logo abaixo do texto. Clicar não envia nada visível no chat: gera um callback_query que só o seu bot vê.

Cada botão inline tem um rótulo (o que aparece) e uma ação, que pode ser:

Callback queries

Quando alguém clica num botão inline, o Telegram envia um callback_query e mostra um relógio girando no botão. Esse relógio só some quando o bot chama answerCallbackQuery.

Editar a mensagem existente (em vez de enviar uma nova) é o que dá a sensação de "menu que navega". Veja editar mensagem em Mensagens.

Deep linking e parâmetros do /start

Um link no formato https://t.me/seu_bot?start=PARAMETRO abre a conversa e, ao clicar em Iniciar, envia /start PARAMETRO. O parâmetro chega no bloco argumentos do comando.

Usos comuns:

• Rastrear origem: ?start=instagram, ?start=panfleto — você registra de onde o usuário veio.
• Programa de indicação: ?start=ref_987654321 — o número é o user.id de quem indicou.
• Link direto para um item: ?start=produto_42 — o bot já abre a ficha do produto.
• Vincular conta: ?start=tok_ab12cd — um token de uso único gerado pelo seu site.

Restrições do parâmetro: até 64 caracteres, apenas A-Z a-z 0-9 _ -.

Formatação: MarkdownV2 × HTML

A opção parse_mode, na aba Configuração, vale para todas as mensagens de texto do bot. Três escolhas:

Tags aceitas em HTML:

<b>negrito</b>  <i>itálico</i>  <u>sublinhado</u>  <s>riscado</s>
<code>monoespaçado</code>
<pre><code class="language-python">bloco de código</code></pre>
<a href="https://exemplo.com">link</a>
<a href="tg://user?id=987654321">mencionar alguém sem username</a>
<tg-spoiler>spoiler</tg-spoiler>
<blockquote>citação</blockquote>

Em MarkdownV2, estes caracteres precisam ser precedidos de \ sempre que forem literais:

_ * [ ] ( ) ~ ` > # + - = | { } . !

Media groups (álbuns)

Um media group agrupa de 2 a 10 fotos/vídeos numa única mensagem em formato de álbum. No Dromornis use item de mídia empilhado dentro de enviar grupo de mídia.

• Não é possível misturar foto/vídeo com documento ou áudio no mesmo álbum.
• Apenas a legenda do primeiro item aparece como legenda do álbum.
• Álbuns não aceitam teclados inline. Se precisar de botões, envie o álbum e depois uma mensagem separada com os botões.

Limites da Bot API

Erros comuns da Bot API

Conhecendo a interface Iniciante

Cada região da tela, o que ela faz e quando você vai precisar dela. Leia uma vez e você nunca mais fica procurando um botão.

Visão geral

Barra superior

Toolbox — a biblioteca de blocos

A coluna esquerda lista as categorias, cada uma com sua cor. Clique numa categoria e a gaveta (flyout) abre com os blocos disponíveis; arraste dali para o canvas.

Canvas

A área central onde os blocos vivem. Comportamentos que valem saber:

• Arrastar um bloco para perto de outro mostra uma linha de conexão; solte para encaixar.
• Arrastar o fundo move a visão. A roda do mouse dá zoom.
• Clique com o botão direito num bloco: duplicar, adicionar comentário, desabilitar, recolher, apagar. No fundo do canvas: desfazer, limpar blocos, organizar.
• Desabilitar um bloco (botão direito → Desabilitar) o deixa cinza e o exclui do código gerado, sem apagá-lo. Excelente para testar variações.
• Arrastar para a lixeira (canto inferior) ou pressionar Delete remove.

Controles do workspace

Minimapa

O retângulo no canto do canvas mostra o workspace inteiro em miniatura, com um marcador da área visível. Em fluxos grandes, clicar no minimapa é a navegação mais rápida.

Painel inferior

Aba Código Python

Mostra o bot.py gerado, com realce de sintaxe, atualizado a cada mudança. Tem botão Copiar e Baixar bot.py. No topo aparece o status: "Código válido" ou "N avisos — revise antes de executar".

Aba Logs

Histórico das ações do editor: projeto salvo, template carregado, exportação concluída, exportação bloqueada por validação. Serve para responder "o que eu fiz nos últimos minutos?".

Aba Validação

Lista os problemas estruturais do workspace: nenhum evento definido, blocos obrigatórios vazios, blocos soltos, configurações incompletas. Enquanto houver problemas, a exportação fica bloqueada.

Aba Configuração

Painéis laterais

Projeto

Nome, descrição, token e a lista de Projetos salvos, onde você abre, duplica ("salvar como") e apaga projetos.

Extensões

Gerencia pacotes .dpkg que adicionam blocos novos ao construtor. Cada extensão mostra status (OK, com avisos, com erro), quantidade de blocos e se a assinatura foi verificada.

Atalhos de teclado

Uso em tablet e celular

O editor é responsivo. Em telas menores, o toolbox e os painéis laterais viram gavetas acionadas por botão, e o painel inferior pode ser expandido ou recolhido. Montar fluxos longos no celular é possível, mas trabalhoso: use telas pequenas para revisar e ajustar, e telas grandes para construir.

Pensando em fluxos Iniciante

A parte difícil de construir um bot não é achar o bloco certo — é organizar o pensamento. Este capítulo é o método.

O método das três perguntas

Antes de arrastar qualquer bloco, responda:

1. O que dispara? — vira o bloco de evento.
2. O que precisa ser decidido? — vira as condições.
3. O que deve acontecer em cada caso? — vira as ações.

Exemplo. "Quero que, quando alguém pedir o horário, o bot responda; e se for fora do expediente, avise que estamos fechados."

Isso já é o fluxo inteiro, e você ainda não tocou no editor. Traduzido em blocos:

Anatomia de um fluxo

Essa ordem — guarda, dados, decisão, resposta — não é obrigatória, mas fluxos que a seguem são muito mais fáceis de ler e depurar. O contrário (enviar mensagem, buscar dado, verificar permissão, enviar de novo) funciona, mas em três semanas nem você entende mais.

Desenhando antes de montar

Para fluxos com mais de duas decisões, desenhe. Papel, quadro branco, qualquer coisa. O padrão usado neste manual:

Um desenho revela em 30 segundos problemas que levariam uma hora para descobrir montando: caminhos que não levam a lugar nenhum, decisões redundantes, casos esquecidos (o famoso "e se o usuário mandar outra coisa?").

Quando quebrar em vários fluxos

Um fluxo deve caber, mentalmente, em uma frase. Se você precisa de "e também… e ainda… e quando…" para descrevê-lo, ele já é dois.

Vários eventos no mesmo workspace

Um projeto tem vários blocos de evento, lado a lado no canvas. Eles são independentes: cada um vira uma função separada e só roda quando o seu gatilho acontece. Organize-os espacialmente por assunto — comandos numa coluna, callbacks noutra, eventos de grupo noutra. O canvas é infinito; use isso a seu favor.

Fluxos que precisam de memória

"Qual o seu nome?" → usuário responde → "Qual seu e-mail?" → usuário responde. Isso é uma conversa com estado: o bot precisa lembrar em que etapa está.

Duas abordagens no Dromornis:

• Bloco esperar resposta — pausa o fluxo, aguarda a próxima mensagem daquele usuário e continua na linha seguinte. Ideal para sequências curtas de 2 a 4 perguntas.
• Máquina de estados no banco — você guarda etapa numa tabela e, a cada mensagem, verifica em que etapa a pessoa está. Mais trabalhoso, porém sobrevive a reinícios do bot e permite fluxos longos e ramificados.

Detalhes e exemplos completos em Conceitos avançados → Estados e no tutorial Sistema de cadastro.

Checklist antes de exportar

• Existe pelo menos um evento? Existe /start?
• A aba Validação está limpa?
• Usando "Enquadrar tudo", há algum bloco solto fora de um evento?
• Toda ação que exige permissão de admin está protegida por uma verificação?
• Todo callback tem um responder callback?
• Chamadas de API externa e envios em massa estão dentro de tentar / se der erro?
• Nenhum token, senha ou chave de API está escrito dentro de um bloco de texto?

Como ler a referência de blocos

O construtor tem 192 blocos em 14 categorias. As páginas seguintes documentam cada categoria com o mesmo formato, para você achar o que precisa sem ler tudo.

O formato de cada bloco

Os blocos mais importantes de cada categoria vêm com uma ficha completa e expansível. Clique no cabeçalho para abrir. A ficha responde sempre às mesmas perguntas:

Os demais blocos aparecem em tabelas de referência dentro da própria categoria, e todos os 192 estão na Referência rápida, pesquisável e filtrável.

Os três tipos de bloco

Tipos de dado

Atalho por objetivo

Eventos 24 blocos

Todo fluxo começa aqui. Um evento é a pergunta "quando isso deve acontecer?" — sem ele, nenhum bloco executa.

Evento × ação: a diferença que importa

Os eventos que você vai usar sempre

Todos os eventos

Blocos de leitura que acompanham eventos

Alguns eventos trazem dados que só existem dentro deles. Usá-los fora do evento correspondente devolve valores vazios:

Mensagens 42 blocos

Tudo que o bot fala, mostra ou apaga. É a categoria mais usada e a maior do construtor.

Enviar texto

Editar e apagar

Mídia

Sete blocos, todos com a mesma mecânica: você fornece uma URL pública, um caminho de arquivo local ou um file_id do Telegram.

Álbuns de mídia

Use item tipo ( ) URL ( ) empilhado dentro de enviar álbum de mídia. De 2 a 10 itens. Apenas a legenda do primeiro aparece. Não aceita botões.

Enquetes, localização e contatos

Utilitários de conversa

Configuração do bot pelo fluxo

Estes blocos alteram o próprio bot e devem ficar em quando o bot iniciar:

Demais blocos da categoria

Teclado 10 blocos

Botões transformam um bot que exige comandos decorados em um bot que qualquer pessoa usa. Esta categoria monta os dois tipos de teclado do Telegram.

Inline × Resposta: escolha certa desde o começo

Montando um teclado inline

São dois blocos que trabalham juntos: teclado inline (o container, um bloco de valor) e botão ( ) tipo ( ) valor ( ) (empilhado dentro dele).

Teclado de respostas

teclado de respostas + botão ( ) empilhados. Três botões especiais merecem destaque:

Dois blocos controlam o estado do teclado de respostas:

Consultas inline (@seubot …)

Permite usar o bot em qualquer conversa digitando @seubot algo. Três peças:

1. Evento quando alguém digitar @seubot ….
2. Leia o texto com texto da consulta inline.
3. Responda com responder consulta inline com ( ), contendo blocos resultado id ( ) título ( ) empilhados.

Regras de UX para menus

• Máximo de 6 a 8 opções por tela. Mais que isso, agrupe em submenus.
• Sempre inclua "⬅️ Voltar" em submenus. Um usuário sem saída fecha o bot.
• Emoji no começo do rótulo — o olho encontra o botão certo muito mais rápido.
• Confirme ações destrutivas com um menu de dois botões: "Sim, apagar" e "Cancelar".
• Edite a mensagem em vez de enviar outra. Um menu que se transforma parece um app; cinco mensagens empilhadas parecem um bug.

Moderação 31 blocos

Banir, silenciar, avisar, gerenciar permissões e tópicos. A categoria mais poderosa — e a que mais exige cuidado, porque quase toda ação aqui é visível para o grupo inteiro.

Blocos de verificação (use-os antes de agir)

Punições: qual usar

Sistema de avisos

Permissões do grupo

definir permissões do grupo recebe blocos permissão ( ) ( ) empilhados dentro, cada um ligando ou desligando uma capacidade dos membros comuns (admins não são afetados).

Gerenciamento do grupo

Tópicos (fóruns)

Supergrupos com "Tópicos" ativado dividem a conversa em canais internos. Seis blocos cobrem o ciclo completo:

Checklist de um bot de moderação

• Todo comando administrativo começa com a guarda se não (usuário é administrador?) → parar por aqui.
• Admins e o próprio bot estão isentos dos filtros automáticos.
• Toda ação de moderação está dentro de tentar / se der erro.
• Punições escalam por avisos, não vão direto ao banimento.
• Existe um comando para desfazer cada punição (/desbanir, /perdoar).
• Ações relevantes são registradas com registrar no log ou enviadas a um canal de auditoria.
• O bot tem apenas as permissões que realmente usa.

Usuário 16 blocos

Blocos de leitura pura: quem falou, de onde, o quê e quando. Todos são blocos de valor — encaixam dentro de outros blocos e nunca sozinhos.

Referência completa

Identificando pessoas do jeito certo

se [ @username do usuário = "joao_admin" ]
   → dar acesso de administrador

# username é opcional, pode mudar,
# e pode ser reciclado por outra pessoa

definir admins = buscar todas as linhas
                 da tabela "admins"

se [ admins contém (ID do usuário) ]
   → dar acesso de administrador

Lidando com valores ausentes

Metade dos blocos desta categoria pode devolver vazio. Uma mensagem como "Olá, !" ou "Seu contato: @" é sempre o mesmo bug: um campo opcional que não existia.

O bloco "agora"

Devolve a data/hora do servidor onde o bot roda, em vários formatos selecionáveis (data completa, hora como número, dia da semana…).

Controle e Operadores

Decidir, repetir, comparar, calcular e manipular texto. Se Eventos é quando e Mensagens é o quê, esta é a categoria do como.

Lógica booleana em cinco minutos

Três operadores combinam respostas de sim/não:

Tabela-verdade completa:

O bloco "se"

Comparações

Repetição

Tratamento de erros

Demais blocos de Controle

Operadores de texto

Operadores matemáticos

Variáveis

Variáveis são a memória de curto prazo do bot. Entender o que elas guardam — e por quanto tempo — evita a confusão número 1 de quem está começando.

O que é, de verdade

Na categoria Variáveis do toolbox você encontra:

Escopo: a parte que confunde todo mundo

quando receber /nome
  ├─ aguardar resposta → nome
  └─ (fim do fluxo)

quando receber /oi
  └─ enviar "Olá, " + nome
     ← nome está VAZIO aqui

quando receber /nome
  ├─ aguardar resposta → nome
  └─ inserir na tabela "usuarios"
       { id: ID do usuário, nome: nome }

quando receber /oi
  ├─ u = buscar 1 linha "usuarios"
         onde "id" = ID do usuário
  └─ enviar "Olá, " + obter "nome" de u

Os quatro níveis de memória

Tipos de dado nas variáveis

Uma variável não tem tipo fixo — ela guarda o que você colocar. O tipo vem do valor:

Nomes de variáveis

x
temp
dados
aux2
teste
a

saldo_usuario
resposta_api_clima
total_avisos
linha_pedido
etapa_cadastro
lista_produtos

Valores do Telegram

Você não "cria" variáveis para os dados do Telegram — eles já existem como blocos prontos na categoria Usuário. Equivalência com a notação de template que você talvez conheça de outras ferramentas:

Segurança e variáveis

definir chave para
  [ "sk-live-a1b2c3d4e5f6" ]

baixar JSON da URL
  juntar("https://api.x.com?key=", chave)

definir chave para
  [ variável de ambiente "API_KEY"
    padrão "" ]

se [ chave está vazia ] → parar por aqui

No servidor, defina API_KEY=... no arquivo .env (que nunca vai para o git) ou nas variáveis do serviço de hospedagem.

Listas e Dicionário 11 blocos

As duas formas de guardar vários valores. Escolher a certa deixa o fluxo simples; escolher a errada gera laços desnecessários.

Lista ou dicionário?

Combinando os dois: buscar todas as linhas devolve uma lista de dicionários — vários registros, cada um com seus campos. É a estrutura mais comum ao trabalhar com banco de dados.

Blocos de lista

Blocos de dicionário

Banco de Dados 12 blocos

A memória permanente do bot. Se você precisa que algo sobreviva ao fim do fluxo e ao reinício do bot, é aqui.

O que é um banco de dados

Tecnicamente: o Dromornis gera código que usa SQLite — um banco relacional que vive num único arquivo ao lado do bot.py. Não exige servidor, instalação nem senha. É a escolha certa para a grande maioria dos bots.

Quando usar banco (e quando não)

Criando tabelas

Operações

O padrão que você vai repetir sempre

Filtrar, ordenar, paginar

Os blocos visuais filtram por igualdade simples. Para o resto, use consultar SQL:

SELECT * FROM pedidos ORDER BY valor DESC LIMIT 10

SELECT * FROM pedidos ORDER BY id LIMIT 10 OFFSET 20

SELECT status, COUNT(*) AS total, SUM(valor) AS soma
FROM pedidos GROUP BY status

consultar SQL [ juntar(
  "SELECT * FROM usuarios WHERE nome = '",
  texto da mensagem, "'") ]

buscar linhas da tabela "usuarios"
  onde "nome" = [ texto da mensagem ]

// os blocos visuais usam parâmetros,
// não concatenação

Se você precisa de SQL bruto com valor do usuário, valide antes com uma regra estrita (só dígitos, só letras, tamanho máximo) e rejeite tudo que não passar.

Desempenho e índices

SQLite é rápido, mas buscar todas as linhas lê a tabela inteira para a memória. Com 100 registros é instantâneo; com 500 mil, o bot congela para todo mundo.

• Prefira buscar linhas onde a buscar tudo e filtrar no fluxo.
• Para listas grandes, pagine com LIMIT e OFFSET.
• Colunas usadas em filtros frequentes merecem um índice.

CREATE INDEX IF NOT EXISTS idx_pedidos_usuario ON pedidos(usuario)

Validação antes de gravar

O banco aceita o que você mandar. Validar é responsabilidade do fluxo:

Avançado 17 blocos

HTTP e APIs externas, JSON, agendamento de tarefas, armazenamento simples e a saída de emergência: código Python direto.

HTTP: falando com o resto do mundo

Quatro blocos, do mais simples ao mais completo:

Os verbos HTTP

Códigos de status

Os quatro que você mais vai encontrar: 401 (chave de API errada ou ausente), 403 (chave válida sem permissão), 404 (URL errada) e 429 (excedeu o limite de chamadas).

Autenticação

A maioria das APIs exige uma chave. Dois blocos trabalham juntos e mantêm o segredo fora do projeto:

JSON

Agendamento

Diferença entre delay e agendamento: esperar pausa o fluxo atual e morre com ele; agendamento cria uma tarefa independente que roda depois. Para "daqui a 5 segundos", delay; para "todo dia às 8h", agendamento.

Armazenamento simples

É o meio-termo entre variável (some) e banco (estruturado). Bom para configurações globais, contadores e cache. Ruim para dados por usuário com busca e filtro — isso é banco.

Código Python personalizado

Quando usar código

• Uma transformação que nenhum bloco cobre (cálculo específico, formatação incomum).
• Uma biblioteca Python que você precisa e que não tem bloco equivalente.
• Um algoritmo que ficaria com 40 blocos e 3 linhas de código.

Quando NÃO usar

• Quando existe um bloco que faz aquilo. O bloco é validado, legível e migra junto com o projeto.
• Quando você não entende exatamente o que a linha faz — copiar código da internet para dentro do bot é como assinar um contrato sem ler.
• Para lógica central do bot: em seis meses ninguém vai lembrar por que aquela linha existe.

expressão Python [
  eval(update.message.text)
]

# executa o que o usuário digitar
# = controle total da máquina

expressão Python [
  f"{valor:,.2f}".replace(",","·")
                 .replace(".",",")
                 .replace("·",".")
]

# formatação BR de número, determinística

Download de arquivos

baixar arquivo de ( ) para ( ) salva o conteúdo de uma URL em um caminho local.

Arquivos 8 blocos

Ler e escrever arquivos no disco do servidor onde o bot roda — incluindo CSV e mídia enviada por usuários.

Referência

Arquivo, banco ou salvar dado?

Trabalhando com CSV

Recebendo arquivos de usuários

salvar arquivo enviado pelo usuário em ( ) baixa foto, documento, vídeo, áudio ou nota de voz da mensagem recebida.

Pagamentos, Figurinhas e Jogos 18 blocos

Três categorias especializadas. Cada uma exige uma configuração externa antes de qualquer bloco funcionar.

Pagamentos Avançado

O Telegram permite cobrar dentro da conversa, com o cartão salvo no app. O dinheiro não passa pelo Telegram: ele intermedia um provedor de pagamento que você conecta no BotFather.

Antes de qualquer bloco

1. No BotFather: /mybots → seu bot → Payments.
2. Escolha um provedor disponível no seu país e conecte a conta.
3. Você recebe um provider token — que é um segredo, tratado como o token do bot.

O fluxo completo, em três atos

Figurinhas Intermediário

Seis blocos para criar e gerenciar pacotes de figurinhas pelo bot.

Jogos Avançado

Telegram Games permite abrir um jogo HTML5 dentro do app, com placar integrado. Você precisa hospedar a página do jogo por conta própria e registrá-lo no BotFather com /newgame.

Tutoriais essenciais

Oito projetos completos, do mais simples ao intermediário. Cada um segue a mesma estrutura: objetivo, blocos, fluxo, teste, erros possíveis e como melhorar.

1. Bot "Olá Mundo" Iniciante

Teste: envie /start no Telegram. Resultado: a saudação com o seu nome, em menos de um segundo.

Erros possíveis: nenhuma resposta → confira se o bot está rodando no terminal e se você está falando com o @username certo. Nome aparece vazio → você usou sobrenome em vez de primeiro nome.

Como melhorar: adicione um /ajuda e um teclado com as opções principais.

2. Bot de menu Iniciante

Teste: clique em cada botão e no "Voltar". A mesma mensagem deve se transformar, sem gerar mensagens novas.

Erros possíveis: botão gira e não faz nada → falta o evento correspondente ou o callback_data está diferente. Sem "Voltar" → usuário fica preso.

Como melhorar: extraia o menu principal para um único callback reutilizado por todas as telas.

3. FAQ automático Iniciante

Erros possíveis: a primeira condição captura tudo → coloque as regras mais específicas antes das genéricas. Não responde em grupos → modo privacidade (veja BotFather).

Como melhorar: guarde as perguntas não entendidas numa tabela; a lista vira o roteiro do que ensinar ao bot em seguida.

4. Sistema de cadastro Intermediário

Erros possíveis: cadastro duplicado → falta o teste inicial. Fluxo perdido após reinício → a espera vive na memória; para cadastros longos, use máquina de estados no banco (veja Estados).

Como melhorar: aceite /cancelar em qualquer etapa e ofereça /apagarconta para o usuário remover os próprios dados.

5. Bot de atendimento Intermediário

Como melhorar: horário de atendimento com agora (hora), e um aviso automático fora do expediente.

6. Bot de moderação Intermediário

Erros possíveis: o bot apaga mensagens de admin → falta a exceção. Nada acontece em grupo → modo privacidade ligado. Erro not enough rights → permissão específica desmarcada.

Como melhorar: lista de domínios permitidos, e envio de cada ação para um canal de auditoria.

7. Bot consumindo API externa Intermediário

Erros possíveis: 401 → chave ausente ou errada. Acentos quebrando a URL → falta codificar URL. Bot travando → API lenta; use cache.

Como melhorar: guarde o resultado por 10 minutos com salvar dado (veja cache) — economiza chamadas e responde instantaneamente.

8. Sistema de notificações Intermediário

Como melhorar: para envios em massa, insira esperar 0.05 segundos entre mensagens e envolva cada envio em tentar / se der erro, marcando como inativo quem bloqueou o bot.

Sistemas completos Avançado

Nove projetos que combinam várias categorias. Aqui a dificuldade não está nos blocos, e sim na arquitetura.

9. Sistema de tickets

Como melhorar: SLA com a cada 1 hora verificando tickets abertos há muito tempo; avaliação de atendimento por teclado inline ao fechar.

10. Vinculação de conta ("login")

11. Níveis de usuário e permissões

12. Conversa com máquina de estados

Quando a conversa tem muitas etapas ou precisa sobreviver a reinícios, aguardar próxima mensagem não basta. Guarde a etapa no banco:

13. Painel administrativo

14. Broadcast para todos os usuários

15. Tarefas agendadas persistentes

Este é o padrão que transforma agendamentos voláteis em assinaturas duráveis: a tabela é a verdade; os agendamentos são reconstruídos a partir dela toda vez que o bot sobe.

16. Loja com pagamentos

17. Integrando um modelo de IA

O construtor não tem categoria de IA dedicada. A integração se faz pelos blocos de HTTP, o que na prática dá total liberdade de provedor.

Depuração e erros

Central de solução de problemas. Encontre o sintoma, entenda a causa, aplique a correção.

O método: isole antes de consertar

Quando algo não funciona, resista à tentação de mudar cinco coisas de uma vez. Siga a ordem:

1. O bot está rodando? Olhe o terminal. Sem processo, nada funciona.
2. A mensagem chega? Coloque registrar no log como primeira ação do fluxo. Se não aparece nada no terminal, o problema é o evento, não a lógica.
3. A condição é verdadeira? Registre o valor comparado antes do se.
4. A variável tem o que você acha? Registre-a. 90% dos bugs são "a variável estava vazia" ou "era texto, não número".
5. A API respondeu? Registre o retorno bruto antes de extrair campos.

Suas quatro ferramentas

Sintomas e correções

O bot não responde a nada

O bot responde em privado, mas não em grupo

Quase sempre é o modo privacidade. Por padrão, em grupos o bot só recebe comandos, menções e respostas diretas. Correção: BotFather → /setprivacy → Disable → remova e readicione o bot ao grupo. A última etapa é obrigatória: sem ela, a mudança não vale para o grupo atual.

"not enough rights" / a ação não acontece

O bot é membro comum, ou é admin sem a permissão específica. Vá em Grupo → Administradores → seu bot e marque exatamente a permissão da ação (Apagar mensagens, Banir usuários, Fixar mensagens, Alterar informações). Ser admin não concede tudo automaticamente.

O botão gira e nada acontece

• Falta o evento quando o botão ( ) for pressionado com aquele callback_data.
• O texto do callback_data do botão e do evento diferem (um espaço, um acento, uma maiúscula).
• Falta confirmar clique do botão — o fluxo até funciona, mas o relógio nunca some.
• O callback_data passou de 64 bytes e a mensagem com o teclado nunca foi enviada.

A mensagem sai com um buraco ("Olá, !")

Uma variável ou campo veio vazio. Causas frequentes:

• Campo opcional do Telegram (username, sobrenome) que a pessoa não tem.
• Variável definida em outro fluxo — variáveis não atravessam fluxos (veja escopo).
• Bloco de leitura usado fora do evento certo (dado do callback num fluxo de comando).
• Chave de dicionário com nome errado — devolve vazio, não erro.
• Busca no banco sem resultado.

Correção padrão: teste está vazio e defina um valor padrão antes de usar.

A condição nunca executa (ou executa sempre)

A API externa dá erro

O bot ficou lento ou travou

• Laço infinito — trava tudo para todo mundo. Revise repetir enquanto.
• API lenta sem tratamento — o fluxo espera. Use mostrar status e cache.
• buscar todas as linhas numa tabela grande — filtre no banco, não no fluxo.
• Muitos envios em sequência — 429 e enfileiramento.
• esperar longo no meio de um fluxo comum.

Erros ao iniciar o bot

Como testar um fluxo direito

1. Caminho feliz: tudo certo, entrada válida.
2. Entrada faltando: comando sem argumentos, resposta vazia.
3. Entrada inválida: texto onde se espera número, e-mail sem @.
4. Sem permissão: teste como usuário comum um comando de admin.
5. Contexto errado: rode um comando de grupo numa conversa privada.
6. Repetição: execute o comando duas vezes seguidas — duplica algo?
7. Serviço fora: ponha uma URL inválida de propósito e veja se a mensagem de erro é boa.

Boas práticas

O que separa um bot que funciona hoje de um bot que ainda funciona daqui a um ano — e que outra pessoa consegue manter.

Organização dos fluxos

• Um evento, uma responsabilidade. Se o fluxo faz três coisas não relacionadas, são três fluxos.
• Agrupe espacialmente no canvas: comandos numa região, callbacks noutra, eventos de grupo noutra. O canvas é infinito.
• Comente os fluxos (botão direito → adicionar comentário) explicando o porquê, não o quê. "Verifica admin" é óbvio; "só admins porque isso apaga dados do cliente" não é.
• Ordem interna: guardas → dados → decisões → resposta.
• Fluxos curtos. Passou de ~20 blocos, divida.

Nomes

Reutilização e duplicação

Copiar e colar um trecho de fluxo é rápido, mas cada cópia é um lugar onde a correção precisa ser aplicada de novo — e um deles sempre fica esquecido.

• Callbacks genéricos: um fluxo menu:* que decide pela leitura do dado do callback, em vez de um fluxo por botão.
• Dados em tabela, não em blocos: uma tabela de produtos vale mais que 30 fluxos quase iguais.
• Regra de três: na terceira vez que você copia o mesmo trecho, pare e generalize.

Tratamento de erros

Validação de dados

Toda entrada do usuário passa por três perguntas antes de ser usada:

1. Existe? A lista de argumentos pode estar vazia.
2. É do tipo certo? Texto que deveria ser número.
3. Está na faixa aceitável? Valor negativo, data no passado, texto de 5.000 caracteres.

Limites de API e desempenho

• Respeite ~30 mensagens/s no total e ~1/s por chat. Em massa, use esperar 0.05.
• Prefira uma mensagem longa a cinco curtas.
• Reaproveite file_id em vez de reenviar a mesma mídia por URL.
• Filtre no banco (onde, LIMIT), não no fluxo.
• Cacheie respostas de API que mudam devagar.
• Evite trabalho pesado dentro de quando receber uma mensagem, que roda para tudo.

Logs

registrar no log [ "erro" ]
registrar no log [ "aqui" ]
registrar no log [ "ok" ]

registrar no log [ juntar(
  "[pedido] usuario=", ID do usuário como texto,
  " item=", item,
  " status=falha_estoque") ]

Versionamento e backup

• Exporte o .json ao fim de cada sessão de trabalho. O localStorage some ao limpar o navegador.
• Nomeie com data: bot-padaria-2026-08-13.json. Poder voltar duas versões vale ouro.
• Guarde os arquivos de dados do servidor (o .db, o data.json, a pasta de uploads) — o projeto sozinho não os contém.
• Nunca faça commit do .env. Coloque-o no .gitignore antes do primeiro commit.
• Teste o restore. Um backup que você nunca restaurou é uma esperança, não um backup.

Checklist de produção

Segurança

Um bot é um programa exposto à internet, que aceita entrada de qualquer pessoa do mundo. Estas são as regras que evitam que isso vire um problema.

Três princípios

O token do bot

Se vazou: BotFather → /revoke → escolha o bot. O token antigo morre imediatamente. Atualize o .env e reinicie. Depois, descubra como vazou — senão vai vazar de novo.

Não confie em nada que vem do usuário

Tudo isto é controlado por quem está do outro lado e pode conter qualquer coisa:

• Texto da mensagem, legendas, nome do arquivo enviado
• Argumentos de comando e parâmetro do ?start=
• Nome, sobrenome e username — podem conter <, *, emojis, 200 caracteres
• callback_data — sim, é forjável por quem inspecionar a mensagem
• Conteúdo de arquivos enviados

Seguro × inseguro

se [ @username = "admin_joao" ]
   → apagar tabela usuarios

a = buscar 1 linha "admins"
    onde "id" = ID do usuário
se [ não (a está vazio) ]
   → ação administrativa

consultar SQL [ juntar(
 "SELECT * FROM u WHERE nome='",
 texto da mensagem, "'") ]

buscar linhas da tabela "usuarios"
  onde "nome" = [ texto da mensagem ]

salvar arquivo enviado em
  [ texto da mensagem ]

// "../../bot.py" sobrescreve o bot

salvar arquivo enviado em
  juntar("uploads/",
    ID do usuário como texto, "_",
    ID da mensagem como texto, ".dat")

callback "buy:42:990"
→ enviar cobrança valor 990

// o usuário edita e paga 1 centavo

callback "buy:42"
p = buscar 1 linha "produtos" onde id=42
→ enviar cobrança valor
    obter "preco_centavos" de p

Controle de acesso

• Verifique em todo ponto de entrada. Um comando protegido e o callback equivalente desprotegido é a mesma porta aberta.
• Verifique de novo no callback. Quem descobre o callback_data pode disparar a ação sem passar pelo comando.
• Registre ações sensíveis com quem, quando e o quê.
• Confirme ações destrutivas com um passo extra de "tem certeza?".

Dados pessoais

Segredos e variáveis de ambiente

TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN
CLIMA_API_KEY=YOUR_API_KEY
PAGAMENTO_PROVIDER_TOKEN=YOUR_PROVIDER_TOKEN

.env
*.db
uploads/
data.json
.venv/
__pycache__/

No fluxo, leia com variável de ambiente ( ) padrão ( ) e sempre verifique se veio vazia — assim, um segredo mal configurado gera uma mensagem clara em vez de um erro obscuro no meio da operação.

Extensões

Conceitos avançados Avançado

Ideias de arquitetura que aparecem quando o bot cresce. Cada uma é explicada primeiro de forma simples, depois tecnicamente.

Estados e máquinas de estado

Tecnicamente: uma máquina de estados é um conjunto finito de estados, com transições disparadas por eventos. Para cada usuário você guarda o estado atual; a cada mensagem, o comportamento depende do par (estado, entrada).

Contexto

Simples: contexto é tudo o que o bot sabe no momento em que executa um fluxo — quem falou, onde, o que disse, o que já estava guardado. Tecnicamente: parte do contexto vem do update (efêmero, só naquela execução) e parte da persistência (banco, salvar dado). Confundir os dois é a causa da maioria dos "por que a variável está vazia?".

Middleware

Simples: é um porteiro que examina toda mensagem antes de ela chegar ao fluxo certo — pode barrar, registrar ou enriquecer. Tecnicamente: uma camada que intercepta o processamento entre o recebimento do update e o handler.

No Dromornis não há um bloco "middleware", mas o padrão é reproduzível: um fluxo quando receber uma mensagem que faz verificações comuns (usuário banido? em manutenção? excedeu o limite?) e usa parar por aqui para barrar. Coloque as verificações no topo de cada fluxo, ou centralize o que der.

Idempotência

Tecnicamente: em sistemas distribuídos, mensagens podem ser entregues mais de uma vez e usuários clicam duas vezes no mesmo botão. Operações que criam ou somam precisam de proteção.

quando /assinar
  → inserir "assinantes" { id }

// 3 cliques = 3 assinaturas
// = 3 mensagens diárias

quando /assinar
  a = buscar 1 linha "assinantes"
      onde "id" = ID do usuário
  se [ não (a está vazio) ] → parar
  → inserir "assinantes" { id }

Onde isso importa mais: cadastros, assinaturas, créditos, pagamentos e agendamentos.

Concorrência

Simples: várias pessoas usam o bot ao mesmo tempo. Tecnicamente: o bot processa updates de forma assíncrona; dois handlers podem estar em execução simultânea e tocar os mesmos dados.

Filas e jobs

Simples: em vez de fazer o trabalho pesado na hora, você anota a tarefa numa lista e alguém executa depois. O usuário recebe a resposta na hora; o trabalho acontece em segundo plano.

Tecnicamente: o Dromornis usa a JobQueue do python-telegram-bot para agendamento. Para "fila" no sentido de trabalho pendente, o padrão prático é uma tabela tarefas com status, e um job periódico que processa os itens pendentes em lotes.

Rate limiting

Simples: um limite de quantas vezes cada pessoa pode usar um recurso num período. Tecnicamente: protege contra abuso, contra custo descontrolado (APIs pagas) e contra você mesmo bater no limite do Telegram.

Cache

Simples: guardar a resposta de algo demorado para não precisar perguntar de novo tão cedo. Tecnicamente: troca-se atualidade por velocidade e custo. As duas perguntas do cache são por quanto tempo e quando invalidar.

Persistência

Arquitetura modular

Organize o projeto por domínio, não por tipo de bloco. Em vez de "todos os comandos aqui, todos os callbacks ali", agrupe: tudo de pedidos junto, tudo de moderação junto, tudo de cadastro junto. Cada módulo deve poder ser entendido — e removido — sem quebrar os outros. Use comentários no canvas como títulos de seção.

Plugins e extensões

O sistema de extensões (.dpkg) permite adicionar categorias e blocos ao construtor. É o caminho para encapsular integrações específicas do seu domínio e reutilizá-las entre projetos, em vez de recopiar fluxos.

Webhooks e microserviços

Webhook do Telegram: o Telegram entrega updates numa URL sua em vez de você buscá-los. Veja polling × webhook — o código gerado usa polling, e migrar exige adaptar o bot.py.

Webhook de terceiros → seu bot: quando outro sistema quer avisar o bot (pagamento aprovado, chamado criado), o caminho usual é gravar o evento em algum lugar que o bot consulta, e ter um job periódico processando os pendentes. Isso evita expor um servidor HTTP junto do bot.

Microserviços: se uma parte do sistema é pesada (processar imagem, gerar relatório), separe-a em outro serviço e converse por HTTP. O bot fica responsável apenas pela conversa, e um pico de trabalho pesado não derruba o atendimento.

Referência rápida

Todos os blocos do construtor numa tabela pesquisável. Filtre por texto, categoria ou tipo.

Além destes, o toolbox inclui os blocos nativos do Blockly nas categorias Controle, Operadores, Variáveis e Listas — se, repetir, comparações, matemática, texto e manipulação de listas.

Glossário

Cada termo tem três partes: a explicação simples, a definição técnica e um exemplo concreto.

Perguntas frequentes

As dúvidas que mais aparecem, respondidas direto.

Começando

Telegram

Dados e execução

Índice remissivo

Todos os assuntos do manual, em ordem alfabética.