O Menu /setup: Guia Completo da Interface do X Bot no Telegram

A forma mais rápida de configurar o X Bot é o menu interativo /setup. Ele encapsula todo comando de admin em uma interface clicável, editável no local — sem comandos de barra para decorar.

Caminho mais rápido: adicione o bot ao seu grupo, digite /setup, toque em 🚀 Início Rápido e siga quatro perguntas. Você terá um cronograma de relatório diário rodando com um filtro real em menos de dois minutos.

Como é o /setup

╔══════════════════════════════════════════════╗
║ ⚙️  Bot Setup                                ║
║                                              ║
║ Pick a section. Settings save instantly.     ║
║                                              ║
║ Current state                                ║
║ ─ Project:  MyToken                          ║
║ ─ Filter:   3 keywords · 2 cashtags          ║
║ ─ Schedule: daily 18:00 UTC                  ║
║ ─ Plan:     FREE — 47/100 credits left       ║
╠══════════════════════════════════════════════╣
║ [ 🚀 Quick Start ]                           ║
║ [ 🎯 Filters     ] [ ⏰ Schedule       ]      ║
║ [ 📊 Reports     ] [ 🎨 Customization  ]      ║
║ [ 👥 Admins      ] [ 💳 Buy Credits   ]      ║
║ [ ℹ️  About       ]                          ║
║ [ ✕ Close ]                                  ║
╚══════════════════════════════════════════════╝

Cada tela mostra o seu estado atual no topo, para que você saiba o que está configurado antes de mudar qualquer coisa. Cada alteração salva instantaneamente no banco de dados — não há botão de "salvar" para esquecer.

Assistente de Início Rápido

Toque em 🚀 Início Rápido para um fluxo linear de quatro passos que leva um chat novo de "nada configurado" a "primeiro relatório agendado" com o mínimo de perguntas. Pular e Sair estão sempre disponíveis — um assistente parcialmente concluído nunca te bloqueia, as configurações simplesmente permanecem nos valores padrão.

Os quatro passos:

Passo	Pergunta	Salva em
1	Nome do projeto	Configuração ProjectName (usada em relatórios, cards de leaderboard, DMs de admin)
2	O que rastrear no X — contas, cashtags ou palavras-chave	O array from, cashtags ou keywords do filtro padrão
3	Quando postar o relatório diário — 4 horários predefinidos ou HH:MM personalizado	Um job agendado vinculado ao seu chat
4	Concluído — tela de resumo com dica do /recreate para pré-visualizar agora	(nenhum)

O menu completo

Cada botão de nível superior abre uma tela focada. Navegue livremente — cada tela tem ← Voltar para o nível anterior e ✕ Fechar para dispensar.

🎯 Filtros

Quais posts do X o bot busca em cada execução agendada.

Toque em qualquer categoria para explorar. Excluir é do tipo caixa de seleção — um toque alterna "excluir retweets / respostas / quote tweets".

Filtros nomeados (avançado) permite manter múltiplos filtros rodando no mesmo chat — útil quando você gerencia vários clientes em um único grupo. Cada filtro nomeado tem seu próprio botão de exclusão por linha com um toque de confirmação. Toque em ➕ Adicionar filtro nomeado para enviar uma definição em uma linha através do menu (name from:@x keywords:y cashtags:$Z mention:@m exclude:retweet ignore:@spam). É necessário pelo menos um entre from / keywords / cashtags / mention.

Uma tela de categoria se parece com isto — uma breve descrição do que a categoria faz, o valor atual e as ações Adicionar / Remover / Limpar tudo:

Quando você toca em ➕ Adicionar, o menu entra em modo de entrada — digite sua resposta como uma mensagem normal, e a tela é redesenhada automaticamente com um banner de confirmação ("✓ Added 2 cashtags: $BTC, $ETH").

➕ Add cashtags

Send the cashtags to track, space-separated.
The $ is optional.

Example:  $BTC $ETH SOL

Type your reply as a normal message,
or tap Cancel to go back.

[✕ Cancel]

⏰ Cronograma

Quando o bot roda e posta o relatório diário.

Quatro horários diários predefinidos cobrem a maioria das comunidades. O horário atualmente ativo recebe um prefixo ✓ em seu rótulo. Horário personalizado pede HH:MM. Dias específicos aceita 14:30 Mon Wed Fri. Cron aceita expressões cron padrão (ex.: cron(0 12 ? * MON-FRI *)). O bot impõe uma frequência mínima de 12 horas para manter os custos previsíveis.

Se você tocar em um horário predefinido em um chat sem filtros, o menu recusa com um erro amigável apontando de volta para 🎯 Filtros — o bot não agenda um chat que não tem nada para buscar.

📊 Relatórios & Período

📊 Reports & Period

Period: 01/05/2026 7days
Start:  2026-05-01
End:    2026-05-07

The bot fetches X posts inside this window on
every scheduled run. Without a period
configured, the bot uses a rolling 24-hour
window.

[📆 Set period]   [🗑 Clear period]
[⚡ Generate report now]
[📰 Show last report]

Definir período restringe os relatórios a uma janela específica (ex.: uma competição de uma semana). Formato DD/MM/AAAA Ndias ou Nsemanas. Limpar período reverte para o padrão contínuo de 24h. Gerar relatório agora dispara a mesma Step Function que o cron usa — útil para pré-visualizações instantâneas. Mostrar último relatório aponta para /report (que reposta a imagem em cache mais recente sem custo de crédito).

🎨 Personalização

Metadados do projeto que aparecem nos relatórios e no leaderboard público.

🎨 Customization

🏷 Name:        MyToken
✏️ Description: A community-driven DeFi project
📝 Long desc.:  (multi-paragraph project pitch…)
🖼 Logo:        ✓ uploaded
🔗 URLs:        2 URLs
💬 Topic:       Forum topic "Reports"

[🏷 Name]      [✏️ Description]
[📝 Long desc.][🖼 Logo]
[🔗 URLs]      [💬 Topic]
[📈 Leaderboard customization]

A subárvore de Leaderboard expõe:

Configuração	Formato
🏆 Pontos	Cinco números, separados por espaço: curtidas retweets respostas citações visualizações (ex.: 5 1 20 10 0.01)
🎨 Cores	Cinco cores em hexadecimal, na mesma ordem
🔢 Contagem do top	Número inteiro de 1 a 10 — quantos usuários no leaderboard
📛 Título do top	Texto livre. Sufixo opcional |#hex define uma cor personalizada (ex.: Principais contribuidores|#FF8800)
🥇 Título do melhor tweet	Mesmo formato
📊 Título de engajamento	Mesmo formato

Uploads de logo usam o handler de fotos existente do bot — toque em 🖼 Logo, depois envie a imagem como uma foto do Telegram (não como arquivo). O bot redimensiona e envia para a CDN do site.

Tópico instrui você a enviar /set_topic de dentro do tópico de fórum desejado. O menu não consegue capturar message_thread_id de um botão de callback, então isso continua sendo uma superfície de comando de barra.

👥 Admins & Notificações

Lista os usuários do chat designados para receber DMs privadas sobre esgotamento de crédito, erros de busca e avisos de chat-não-encontrado. Adicionar admins ainda requer /add_admin @user1 @user2 no chat — o parser de menções @ do Telegram só é acionado em mensagens reais, não em callbacks.

👥 Admins & Notifications

Currently:
  • Alice (@alice_admin)
  • Bob (@bob_dev)

To add admins, send /add_admin @user1 @user2
in this chat.

[🗑 Clear notification list]

💳 Comprar Créditos & Plano

Exibição de plano + saldo, além dos botões que conduzem os fluxos de compra e gerenciamento. A tela é renderizada de forma diferente dependendo do plano atual do chat:

Chat FREE:

💳 Buy Credits & Plan

Plan: FREE
Used this month: 47 / 100
Remaining:        53
Resets: 2026-06-01

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

Chat com assinatura PRO:

💳 Buy Credits & Plan

Plan: PRO (subscription) ✓
Unlimited fetching with Stripe metering above 1 000 / month free.

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

Chat com créditos PRO (comprados em ETH):

💳 Buy Credits & Plan

Plan: PRO (credits)
Credits remaining: 4 152
Total purchased:   5 000

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

O botão 💰 Comprar créditos / upgrade posta um card de opções de pagamento abaixo do menu. As opções que o bot oferece dependem do plano atual:

• FREE → ambos 💳 Pagar com Cartão de Crédito (assinatura Stripe) e 🪙 Pagar com ETH (pacote de créditos).
• PRO créditos → ambas as opções são mostradas. ETH complementa o saldo existente; Stripe adiciona uma assinatura por cima (os créditos ETH existentes permanecem e são gastos primeiro em cada busca).
• PRO assinatura → sem opções de compra. O bot responde com uma mensagem de "assinatura já existe" e aponta para 🛠 Gerenciar para ir ao portal Stripe.

O botão 🛠 Gerenciar assinatura abre o Portal do Cliente Stripe no seu navegador — é lá que você atualiza seu cartão, cancela ou baixa faturas. Só faz sentido quando você tem uma assinatura Stripe ativa.

A subtela 📊 Uso deste mês detalha fetched_posts e fetch_attempts para o mês corrente e para hoje — útil para identificar falhas silenciosas (muitas tentativas, zero posts → provavelmente 402s ou queries vazias) e para prever sua próxima fatura Stripe quando você estiver se aproximando do limite de 1.000 posts.

Comprar + gerenciar também são acessíveis pelos comandos de barra legados /buy e /subscription. O comportamento é idêntico; os botões do menu só economizam sua digitação.

📡 Auto-relay de Posts do X

Encaminha posts de contas do X selecionadas para o chat assim que são publicados — separado do relatório agendado. Útil quando um projeto quer que admins da comunidade vejam tweets da conta oficial em tempo real sem precisar checar o X.

📡 X Posts Auto-relay

Forward posts from X accounts to this chat as soon
as they're published. Posts can take up to 5
minutes to appear here after the original was
posted on X.

3 active relays:
▶️ @MyTokenOfficial    (4/10 today)
▶️ @MyTokenCEO         (1/10 today)
⏸ @MyTokenSupport     (0/10 today)

[ ▶️ @MyTokenOfficial ]
[ ▶️ @MyTokenCEO ]
[ ⏸ @MyTokenSupport ]
[ ➕ Add Account ]

Cada relay consulta a cada 5 minutos via a API do X. Posts novos (desde o último encaminhamento bem-sucedido) são enviados ao chat como URLs simples — o Telegram renderiza automaticamente o card de preview do X, então o corpo do post fica visível.

A tela de gerenciamento por relay permite ao operador ajustar o comportamento:

📡 X Posts Auto-relay › @MyTokenOfficial

State: ▶️ Active
Today: 4/10 forwarded
Polls every: 5 min

Post types to forward
☐ Retweets
☐ Replies (to other users)
✅ Quote tweets
✅ Thread continuations (self-replies)

Topic: (default — top of chat)

[ ⏸ Pause ] [ ✏️ Cap: 10/day ]
[ ☐ Retweets ] [ ☐ Replies ]
[ ✅ Quote tweets ] [ ✅ Thread ]
[ 💬 Set topic ] [ 🧹 Clear topic ]
[ 🗑 Delete relay ]

Configuração	O que faz
Limite (1–100/dia)	Máximo de encaminhamentos por chat por dia UTC — quando atingido, o relay para de encaminhar silenciosamente até a meia-noite UTC. Padrão 10.
Pausar / Retomar	Desativa o cronograma de consultas desse relay; restaurar o recria instantaneamente.
Retweets	Quando ✅, retweets feitos pela conta relayed são encaminhados. Desligado por padrão.
Respostas	Quando ✅, respostas a outros usuários são encaminhadas. Desligado por padrão.
Quote tweets	Quando ✅, quote tweets são encaminhados. Ligado por padrão.
Continuações de thread	Quando ✅, respostas próprias (um usuário respondendo aos seus próprios tweets) são encaminhadas — cobre threads do Twitter. Ligado por padrão. Desligue isso se você só quiser o início de cada thread.
Tópico	ID de tópico de fórum do Telegram, opcional. Quando definido, o relay posta apenas nesse tópico em vez da thread principal.

Limpeza automática: se o Telegram retornar um erro de "chat inexistente" (o bot foi expulso / bloqueado), o relay remove automaticamente seu cronograma de consultas e a configuração armazenada. Sem vazamento.

Limite rígido: 10 relays por chat. Ajuste a constante subjacente se precisar de mais.

ℹ️ Sobre

ℹ️ About this chat

Chat ID: -1002593612414
Plan: PRO ✓
Schedule: daily 18:00 UTC
Project: MyToken

Um painel de diagnóstico para solicitações de suporte.

Como o /setup se relaciona com os comandos de barra

O /setup é aditivo — todo comando de barra existente continua funcionando exatamente como antes. O menu encapsula as mesmas primitivas (buildQueryFromComponents, saveXBotSetting, createScheduleRule, etc.), então o comportamento é idêntico entre as duas superfícies. Usuários avançados podem continuar digitando /add_keywords DeFi airdrop pela velocidade da memória muscular; recém-chegados ganham uma superfície clicável e amigável.

Três comandos fundamentalmente não podem ser movidos para botões de menu porque precisam de texto puro + contexto de entidades de mensagem do Telegram que callbacks não carregam:

Comando	Por que permanece
/set_topic [name]	Captura o message_thread_id do tópico em que a mensagem foi enviada — um botão não tem contexto de thread
/add_admin @user	Depende das entidades de menção verificadas do Telegram para verificação de admin do chat
/set_x_filtering	Comando de barra legado para adicionar um filtro nomeado; o ⤴ Filtros nomeados → ➕ Adicionar filtro nomeado do menu faz o mesmo

Receitas de configuração

Objetivos comuns → caminhos exatos do menu. Cada receita leva um ou dois minutos de cliques.

"Rastrear apenas posts originais (sem retweets, sem respostas)"

A maioria das comunidades quer que o leaderboard recompense conteúdo original, não republicações.

/setup → 🎯 Filtros → 🚫 Excluir → toque em Retweets e Respostas para que ambos mostrem ✅. Pronto. Buscas futuras enviam -is:retweet -is:reply para a API do X e quote tweets continuam contando.

"Recompensar respostas mais do que curtidas (construção de comunidade)"

Pontos padrão: curtidas 1×, retweets 2×, respostas 1,5×, citações 3×, visualizações 0,001. Para favorecer a conversa:

/setup → 🎨 Personalização → 📈 Personalização do leaderboard → 🏆 Pontos → envie:

1 1 5 3 0.001

As respostas agora pesam 5× — discussões substanciais superam curtidas de passagem.

"Rodar relatórios duas vezes ao dia"

O cronograma dispara no máximo uma vez por dia por padrão. Para ter um relatório de fim de expediente na Europa e um nos EUA:

/setup → ⏰ Cronograma → 🔧 Expressão cron → envie:

cron(0 14,22 ? * * *)

Dois disparos/dia às 14:00 + 22:00 UTC. A verificação de frequência mínima de 12 horas impõe automaticamente um espaçamento ≥ 12h — janelas mais estreitas são rejeitadas com um erro claro.

"Rastrear múltiplas campanhas simultaneamente em um grupo"

Três campanhas de clientes simultâneas, um grupo do Telegram, um relatório por campanha a cada disparo.

/setup → 🎯 Filtros → ⤴ Filtros nomeados → ➕ Adicionar filtro nomeado, depois envie um destes a cada vez:

campaign_a from:@kol1,@kol2 keywords:"#CampaignALaunch"
campaign_b from:@kol3,@kol4,@kol5 cashtags:$CBT
campaign_c from:@kol6 mention:@CampaignC_Official

Cada um dispara no mesmo cronograma e posta um relatório separado marcado com o nome do filtro.

"Encaminhar os tweets de uma conta em tempo real, entre os relatórios"

Uma notícia importante de @MyTokenOfficial não deveria esperar pelo relatório das 22:00 UTC.

/setup → 📡 Auto-relay de Posts do X → ➕ Adicionar Conta → envie:

@MyTokenOfficial 5

(O 5 opcional é o limite diário; padrão 10.) O bot consulta a cada 5 minutos, encaminha a URL de um post novo, o Telegram renderiza o card de preview.

"Restringir relatórios a uma janela de campanha (ex.: empurrão de 7 dias)"

Não quero que o ruído pré-campanha contamine o leaderboard.

/setup → 📊 Relatórios → 📆 Definir período → envie:

01/05/2026 7days

Os relatórios agora buscam posts estritamente dentro dessa janela. 🗑 Limpar período reverte para o padrão contínuo de 24h.

"Fazer os relatórios postarem em um tópico de fórum, não na thread principal"

O grupo usa tópicos; os relatórios devem cair em um tópico dedicado Relatórios.

Abra o tópico Relatórios, depois de dentro dele envie:

/set_topic Reports

Relatórios futuros são roteados para esse tópico. Para reverter: /set_topic clear de qualquer lugar do grupo.

"Notificar dois admins específicos quando os créditos acabarem"

O bot envia DM aos admins designados em erros de crédito / busca / chat-inexistente. Por padrão, ele recorre a todos os admins do chat — restrinja para uma lista selecionada.

/add_admin @alice @bob

As DMs agora vão apenas para @alice e @bob. Para limpar: /setup → 👥 Admins → 🗑 Limpar lista de notificação.

"Ocultar o chat do showcase público do xbot.ninja"

Portfólios de KOL independente são ocultados automaticamente (usuário único falha no limite de ≥ 2 usuários ativos). Para projetos de comunidade que devem permanecer privados:

Não há um botão explícito de ocultar — a listagem pública é controlada por limites de métricas. Duas formas de permanecer privado:

• Rode um chat pequeno / discreto que não atinja os limites (pontuação do melhor usuário < 300, posts < 5/mês, ou usuários ativos < 2).
• Contate o suporte para marcar o chat como isento — o dashboard público o ignora independentemente das métricas.

A URL direta do chat (https://xbot.ninja/?chatId=…) continua acessível independentemente. Compartilhe-a apenas com pessoas que deveriam ver os dados.

Problemas comuns

Sintoma	Motivo	Solução
Cronograma "rejeitado" com FREQUENCY_ERROR	O cron tenta disparar mais do que a cada 12h	Verificação de espaçamento — escolha intervalos de pelo menos 12 horas. A mensagem de erro nomeia o par de horários problemático.
/setup não aparece no autocompletar	Lista de comandos do BotFather desatualizada	O bot aceita /setup independentemente do autocompletar. Atualize o BotFather → /setcommands se a descoberta importar.
Preview do filtro mostra parênteses vazios ou query estranha	Algum componente está vazio	/setup → 🎯 Filtros mostra a query literal. Adicione pelo menos um entre contas / cashtags / palavras-chave / menções.
Auto-relay de Posts do X encaminha os posts de uma thread inteira de uma vez	Respostas próprias contornam o exclude=replies da API do X	/setup → 📡 Auto-relay de Posts do X → @conta → desative ☐ Continuações de thread. O bot então mantém apenas o início da thread.
Limite diário atingido mas eu quero mais	Atingiu o MAX_POSTS_PER_DAY do relay	Toque em ✏️ Limite e aumente. Cada post encaminhado conta como um crédito.
Título / cor personalizados revertidos durante a noite	Atualização de configuração funcionou mas o incremento de UPDATED_AT invalidou o cache de renderização; a próxima busca mostra o novo valor	Aguarde um ciclo de relatório. O cache de renderização é reconstruído na próxima busca.
Relatório tem "0 posts" em todo lugar	Nenhum post correspondeu ao filtro no período configurado	Remova o período (24h contínuas é mais tolerante), ou amplie os filtros. Muitas vezes é um erro de digitação em um cashtag.
Bot "online" mas os relatórios param de chegar	Bot foi rebaixado de admin / expulso silenciosamente	Verifique Telegram → admins do grupo. Repromova se estiver faltando. O bot se autodesativa em erros de chat-inexistente.

Concluído

A tela final do assistente resume tudo o que foi salvo e aponta para /setup → 📊 Relatórios → ⚡ Gerar relatório agora para uma pré-visualização imediata:

Esse é o tour completo. Digite /setup no seu grupo para começar.

Teve algum problema configurando um item do menu? Veja Solução de problemas para matrizes de sintoma-para-solução cobrindo filtros, cronogramas e faturamento.