Suporte do X Bot: Solução de Problemas, FAQ & Guia de Contato

A maioria dos problemas se resolve com uma única ação no /setup. A primeira metade desta página conduz você pelo fluxo de autodiagnóstico; a segunda metade é um FAQ. Se nenhuma delas resolver, o formulário de contato no final leva diretamente ao canal de suporte de desenvolvedores da BWS.

Primeiro — fluxo de autodiagnóstico

Open /setup → ℹ️ About in your chat.
└─ Copy that text. It's everything support needs to triage.

Then ask yourself, in order:

  1. Does the bot reply to /setup at all?
     ├─ No  → bot was kicked or demoted from admin → re-promote and retry
     └─ Yes → continue.

  2. Did /setup → 📊 Reports → ⚡ Generate report now produce something
     within 3 minutes?
     ├─ No DM, no post → check next question.
     ├─ DM "no posts found"  → filter too narrow or no on-topic posts;
                                /setup → 🎯 Filters to see
                                the literal X API query.
     ├─ DM "credit exhausted" → /setup → 💳 Buy Credits → 💰 Buy.
     ├─ Post landed but image looks wrong → re-fire; if persistent,
                                contact support with the chat ID.
     └─ Post landed correctly → you're fine.

  3. Are scheduled reports arriving?
     ├─ No  → /setup top screen shows the cron. Compare to actual UTC time.
              The bot's first scheduled fire happens AFTER the next cron tick,
              not immediately after setup.
     └─ Yes → all good.

Se nada disso te levar a uma solução, role além do FAQ até o link de contato.

FAQ

Configuração & instalação

P. O bot não responde quando eu o adiciono. Confirme que ele foi promovido a admin, não apenas "membro". Telegram → configurações do grupo → Administradores. A repromoção é instantânea; o bot não precisa ser reinstalado.

P. Posso mover o bot para outro grupo? Sim — adicione-o ao novo grupo, execute /setup lá. Os dois chats são independentes (IDs de chat diferentes = configurações, cronogramas e pontuações diferentes). Não há migração de dados entre chats.

P. O bot relata na thread principal, mas meu grupo tem tópicos — posso redirecionar? De dentro do tópico de fórum desejado, envie:

/set_topic Reports

Relatórios futuros são roteados para esse tópico. Reinicie com /set_topic clear.

P. Como eu desinstalo?

• Pare os relatórios primeiro: /setup → ⏰ Cronograma → ✕ Desativar cronograma.
• Remova o bot: Telegram → grupo → admins → expulse @BWS_X_Bot.
• As configurações permanecem no banco de dados. Readicionar o bot ao mesmo ID de chat retoma tudo. Peça ao suporte uma exclusão definitiva.

Relatórios & filtragem

P. Por que meus números são diferentes dos rastreadores de terceiros? O X Bot busca diretamente da API oficial do X. A maioria dos rastreadores de terceiros faz scraping ou extrapola — já medimos discrepâncias de 20–50%. O número da API do X é a fonte da verdade.

P. O leaderboard mostra usuários que eu não esperava rastrear. Filtros são aditivos. Se um chat rastreia o cashtag $SEU_TOKEN, qualquer um que tuitar esse cashtag é ranqueado, não só as contas que você listou. Para exigir tanto uma conta quanto um cashtag, use a forma from:@x cashtags:$SEU_TOKEN via /set_x_filtering (a semântica de E-de-tudo dos filtros nomeados).

P. O relatório diz "0 posts" — e agora? Três possibilidades, em ordem de probabilidade:

1. Filtro muito restrito — /setup → 🎯 Filtros mostra a query literal da API do X. Erro comum: $BTC (espaço no final) vs. $BTC.
2. Período muito restrito — se você definiu um período personalizado, posts fora dessa janela não contam. /setup → 📊 Relatórios → 🗑 Limpar período reverte para 24h contínuas.
3. As contas rastreadas realmente não postaram nada no tema em 24h — amplie com cashtags ou palavras-chave como sinal alternativo.

P. Posso rastrear uma conta privada/protegida do X? Não — a API do X só retorna posts públicos.

P. Posso excluir usuários específicos do leaderboard de um chat (ex.: bots de spam)? Sim: /setup → 🎯 Filtros → 🙈 Ignorar → ➕ Adicionar. Os handles listados são removidos dos resultados após a busca.

P. Por que meu chat tem múltiplos disparos de relatório por dia? Ou você definiu um cron com múltiplos disparos (cron(0 14,22 ? * * *)) ou você tem múltiplos filtros nomeados rodando no mesmo cronograma. Cada filtro nomeado produz seu próprio relatório.

P. A escolha do "Melhor Tweet" parece estranha. O seletor de IA escolhe o post de maior engajamento que não foi escolhido recentemente. Se os resultados parecerem consistentemente estranhos, contate o suporte — o prompt é ajustável.

Auto-relay de Posts do X

P. O relay encaminhou uma thread de 6 posts de uma vez. Eu só queria o primeiro. Isso é porque o exclude=replies da API do X só filtra respostas a outros usuários; respostas próprias (continuações de thread) contornam isso. /setup → 📡 Auto-relay de Posts do X → @conta → desative ☐ Continuações de thread. O bot então mantém apenas o início de cada thread.

P. O relay parou de encaminhar no meio do dia. Verifique a tela por relay — se Today: 10/10 forwarded, você atingiu o limite diário. Toque em ✏️ Limite para aumentar. O limite reinicia à meia-noite UTC.

P. O relay mostra ⏸ Pausado mas eu nunca pausei. O bot pausa automaticamente em erros de chat-inexistente do Telegram (expulso / bloqueado / chat atualizado) e para o cronograma de consultas. /setup → 📡 Auto-relay de Posts do X mostra a linha caso você readicione o bot.

Faturamento & créditos

P. O que é exatamente um "crédito"? Um crédito = um post retornado pela API do X. Chats FREE recebem 100 créditos grátis/mês; chats PRO são cobrados via Stripe (assinatura) ou ETH (pacote de créditos).

P. Onde vejo meu saldo de créditos?/setup → 💳 Comprar Créditos. Mostra usado / restante / data de reinicialização.

P. Acabei de pagar mas meu saldo / plano não atualizou.

• Caminho Stripe (assinatura por cartão): o webhook geralmente ativa o PRO em segundos. Se depois de 5+ minutos você não vir PRO ✓ em /setup → 💳 Comprar Créditos, contate o suporte com seu recibo do Stripe e o ID do chat.
• Caminho ETH (pacote de créditos): a confirmação on-chain pode levar de 1 a 3 minutos. Se depois de 10 minutos os créditos não aparecerem, contate o suporte com o hash da transação e o ID do chat.

P. Posso ter uma assinatura Stripe E créditos ETH no mesmo chat? Sim — eles se combinam. Um chat PRO·créditos que assina mantém seu saldo ETH existente, e o faturamento por busca esgota os créditos ETH primeiro antes que a concessão mensal da assinatura entre em ação. Efeito prático: se você tem 5.000 créditos ETH e assina, as primeiras 5.000 buscas não tocam no Stripe de jeito nenhum; buscas seguintes usam a concessão de 1.000/mês da assinatura; o que passar disso é excedente medido de $0,02/post. O saldo ETH nunca expira.

A única restrição: um chat já em PRO·assinatura não pode adicionar um pacote ETH novo pelo mesmo fluxo de compra hoje (o comando de compra bloqueia). Cancele a assinatura primeiro se quiser voltar para faturamento somente em créditos.

P. O que acontece quando meu saldo de PRO·créditos chega a zero? A licença é automaticamente rebaixada para FREE. O bot continua buscando sob o limite FREE de 100/mês até que esse também se esgote. O próximo /setup → 💳 → 💰 Comprar então oferece novamente os dois caminhos.

P. O saldo de créditos é por chat ou por usuário? Por chat. Cada grupo do Telegram tem seus próprios créditos e licença.

Dashboard público

P. Meu projeto não aparece no xbot.ninja. Três limites precisam ser atingidos, todos no mês corrente:

• Pontuação do melhor usuário ≥ 300
• Posts rastreados ≥ 5
• Usuários ativos ≥ 2

O primeiro mês costuma ser o gargalo. A URL direta https://xbot.ninja/?chatId=<seu-id> funciona independentemente.

P. Como encontro o ID do meu chat?/setup → ℹ️ Sobre. O número inteiro longo com prefixo negativo.

P. Posso personalizar o card público do xbot.ninja?/setup → 🎨 Personalização. Defina Nome, Descrição, Logo, URLs. O card atualiza no próximo ciclo de relatório.

Peculiaridades da API do X

P. Por que alguns posts mais antigos do que o esperado são contados? O bot usa tweets/search/all (endpoint de arquivo completo). Quando você define um período, o bot pode buscar posts de qualquer momento dentro dele. O padrão é 24h contínuas, mas um período personalizado pode ser retroativo.

P. Às vezes um post leva mais de 5 minutos para aparecer em um relay. O Auto-relay de Posts do X consulta a cada 5 minutos. A latência é de até um intervalo de consulta (~2,5 min em média / ~5 min no pior caso). Mais uma pequena latência da API do X + entrega pelo Telegram.

P. A API do X retornou um erro — o que o operador vê? Contadores internos de erro sobem; admins designados recebem uma DM privada (/setup → 👥 Admins para configurar quem). Códigos 4xx comuns: 401/403 (credenciais do lado do operador), 402 (créditos esgotados), 429 (limite de taxa — o bot tenta novamente com backoff).

O que incluir em uma solicitação de suporte

Copie e cole este modelo:

Project: <your project name>
Chat ID: <from /setup → ℹ️ About>
Plan: FREE / PRO·credits / PRO·sub
What's wrong: <1–2 sentences>
What you tried: </setup → … → … steps you ran>
When it broke: <approx UTC time>
Recent change: <any new filter / schedule / payment in the last 24 h>

O ID do chat sozinho já dá ao suporte 80% das informações de triagem — por favor, sempre inclua-o.

Tempos de resposta esperados

• Crítico: bot offline em toda a plataforma, falhas de faturamento → resposta em 1 hora útil durante a sobreposição de horário comercial EU+EUA
• Alto: relatório não sendo entregue para um único chat → no mesmo dia útil
• Normal: perguntas sobre recursos, ajuda de configuração → 1–2 dias úteis

Links úteis

• Bot do Telegram: @BWS_X_Bot
• Dashboard público: xbot.ninja
• Documentação: /docs/
• Issues no GitHub: blockchain-web-services/bws-api-telegram-xbot
• Suporte direto: bws.ninja — o formulário de contato leva ao suporte de desenvolvedores da BWS

Antes de contatar o suporte, percorra o fluxo de autodiagnóstico em Solução de problemas — a maioria dos problemas se resolve nas duas primeiras verificações.