Solução de Problemas do X Bot: Relatórios, Filtros, Cronogramas, Faturamento

Um índice consolidado de todo caminho "algo parece errado, e agora?". As matrizes de instalação / menu-setup / suporte também vivem aqui, para você pesquisar em uma página em vez de três.

Comece aqui: abra /setup → ℹ️ Sobre no seu grupo. As quatro linhas dessa tela (ID do chat, plano, cronograma, nome do projeto) são o que o suporte precisa para triagem. Copie-as antes de fazer qualquer outra coisa.

Fluxo de autodiagnóstico

Percorra estas perguntas em ordem. A maioria dos problemas se resolve em uma das duas primeiras verificações.

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

2.  Does /setup → 📊 Reports → ⚡ Generate report now produce a post
    within 3 minutes?
    ├─ No DM, no post                  → check matrix in §"Reports not arriving"
    ├─ DM "no posts found"              → see §"Filter / no posts"
    ├─ DM "credit exhausted"            → see §"Billing & credits"
    ├─ Post landed but renders wrong    → see §"Render quality"
    └─ Post landed correctly            → you're fine.

3.  Are scheduled reports arriving on time?
    ├─ No  → see §"Schedule not firing"
    └─ Yes → all good.

4.  X Posts Auto-relay issues?
    └─ See §"X Posts Auto-relay"

Se nenhuma das matrizes abaixo te levar a uma solução, role até Escalonamento.

Relatórios não chegam

Sintoma	Causa provável	Solução
Bot estava ativo antes, de repente silencioso	Bot foi rebaixado de admin / expulso silenciosamente	Telegram → admins do grupo → repromova. Se ainda estiver em silêncio, contate o suporte — a desativação automática por chat-inexistente pode ter sido acionada.
Gerar-agora manual não produz nada	Bot é admin mas está com zero créditos	/setup → 💳 Comprar Créditos. Se FREE "100/100 usados" — aguarde a reinicialização mensal (dia 1º do mês UTC). Se PRO·créditos com REMAINING=0 — o chat já foi rebaixado automaticamente para FREE; /setup → 💳 → 💰 Comprar para recarregar.
Gerar-agora manual: DM de admin "nenhum post encontrado"	Filtro muito restrito OU nenhum post na janela	/setup → 🎯 Filtros. Verifique a query literal da API do X em busca de erros de digitação. Tente ampliar ou remover o período.
Imagem renderiza mas o texto está vazio	Comentário de IA expirou	Execute novamente; é transitório. Persistente = contate o suporte.
Imagem falha ao renderizar completamente	Falha transitória de renderização	Execute novamente. Se falhar repetidamente para um chat, contate o suporte com o ID do chat.
Erro "Unauthorized" / "Forbidden" na DM de admin	Problema de token da API do X (lado do operador)	Contate o suporte; não há nada que o usuário possa corrigir.

Filtro / sem posts

Sintoma	Causa provável	Solução
Relatório mostra "0 posts" em tudo	Filtro não corresponde a nada no período configurado	Passo 1: /setup → 🎯 Filtros — confirme a query. Passo 2: /setup → 📊 Relatórios → 🗑 Limpar período (24h contínuas é mais tolerante). Passo 3: amplie os filtros (adicione um cashtag alternativo, remova grupos de palavras-chave restritivos).
Leaderboard mostra usuários que eu não adicionei ao filtro	Filtros são aditivos — qualquer um que tuitar um cashtag/palavra-chave rastreado conta	Para exigir tanto uma conta quanto um cashtag, use /set_x_filtering name from:@x cashtags:$Y (filtro nomeado, E-de-categorias).
Mesmo usuário dominou o leaderboard	O bot pontuou legitimamente cada post	/setup → 🎯 Filtros → 🙈 Ignorar → ➕ Adicionar @spammer — eles são removidos dos resultados após a busca.
Cashtag com caracteres estranhos não corresponde	A API do X normaliza maiúsculas/minúsculas; espaços à direita/esquerda importam na entrada do filtro	Readicione via /setup → 🎯 Filtros → 💵 Cashtags → ➕ Adicionar → sem precisar de $, sem espaços.
Cashtag com número no início (ex.: $1INCH) não é rastreado	O comportamento de busca da API do X com números no início pode ser inconsistente	Use como palavra-chave em vez de cashtag: "$1INCH" em 🔍 Palavras-chave com aspas.
Escolha de "Melhor Tweet" parece estranha	A deduplicação por IA recentemente escolheu um tweet similar	Aguarde um ciclo. Se a estranheza persistir, reporte — o prompt é ajustável.

Cronograma não dispara

Sintoma	Causa provável	Solução
Cronograma "rejeitado" com FREQUENCY_ERROR	O cron tenta disparar mais do que a cada 12h	A verificação de espaçamento impõe intervalos ≥ 12h. A mensagem de erro nomeia o par de horários problemático. Escolha um intervalo maior.
Cronograma definido, mas o relatório não chegou na hora	O cron agendado dispara dentro de ~1–2 min do horário marcado	Aguarde 5 min após o horário configurado antes de assumir que houve falha. Atrasos raros a montante acontecem, mas se resolvem sozinhos.
Cron com múltiplos disparos só dispara uma vez	Lista de horas fora de ordem ou duplicada	cron(0 14,22 ? * * *) — horas em ordem crescente. cron(0 22,14 ? * * *) é rejeitado.
Cronograma no staging dispara a cada 5 min, produção não	Namespace de RULE_NAME diferente	Confirme se você está verificando o ambiente correto. /setup → ℹ️ Sobre mostra o ambiente.
Fuso horário parece errado	O cronograma é em UTC por design	Converta seu horário local para UTC. A entrada de definição de horário também aceita fusos horários nomeados em alguns casos específicos — verifique o docstring da entrada.
Auto-relay de Posts do X dispara mas os relatórios não	Cronogramas cron diferentes	O Auto-relay de Posts do X usa uma consulta de 5 min por relay; relatórios usam o cron do cronograma principal do chat (tipicamente diário). São independentes.

Qualidade de renderização

Sintoma	Causa provável	Solução
Título / cor personalizados revertidos durante a noite	Cache invalidado, a próxima busca mostra o novo valor	Aguarde um ciclo de relatório (~1 dia). O cache de renderização é reconstruído na próxima busca.
Logo desfocado / cortado	Imagem de origem muito pequena ou não quadrada	Reenvie em ≥ 512×512 PNG, proporção quadrada. /setup → 🎨 Personalização → 🖼 Logo.
Nome de usuário transborda na imagem do leaderboard	Nome de exibição longo	O bot trunca com reticências; sem necessidade de correção a menos que persista.
Texto do melhor tweet mostra HTML bruto <a href>	Incompatibilidade de modo de parse do Telegram	Bug — por favor reporte com a URL do tweet.
Imagem de relatório diferente da preview do Telegram	O Telegram armazena em cache os primeiros bytes da imagem por URL; URLs pré-assinadas incluem um timestamp, então cada busca é única	Não deveria acontecer; se acontecer, gire via /recreate.

Auto-relay de Posts do X

Sintoma	Causa provável	Solução
Relay encaminha uma thread de 6 tweets 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.
Relay parou no meio do dia	Limite diário atingido	A tela por relay mostra Today: N/N forwarded. Toque em ✏️ Limite e aumente. Reinicia à meia-noite UTC.
Relay mostra ⏸ Pausado mas eu nunca pausei	Auto-pausado por chat-inexistente do Telegram (expulso / bloqueado / chat atualizado)	O bot também parou o cronograma de consultas. Para restaurar: /setup → 📡 Auto-relay de Posts do X → @conta → ▶️ Retomar. Se ainda falhar, o próprio chat pode ter mudado de ID (upgrade para supergrupo) — readicione o bot no novo chat.
A primeira consulta do relay encaminhou 50 posts	O bootstrap não deveria fazer isso — só deveria semear o LAST_POST_ID sem encaminhar	Se você ver isso, por favor reporte. A correção adicionada em 2026-04 deveria evitar isso.
Quote tweets continuam aparecendo apesar do toggle	A API do X não tem exclude=quotes do lado do servidor — o bot filtra do lado do cliente após a busca	O toggle funciona, mas você ainda paga pelos quote tweets retornados pela API. Economia apenas cosmética.
Relay continua consultando apesar do chat ter sido deletado	Relay de versão antiga — limpeza automática adicionada em 2026-05	Peça ao suporte para forçar a parada do relay. Novos deploys se autolimpam.

Faturamento & créditos

Sintoma	Causa provável	Solução
Comprei créditos, saldo sem alteração	Webhook do Stripe atrasado	Aguarde 5 min. Se ainda estiver errado, contate o suporte com o recibo do Stripe + ID do chat.
Contagem de créditos maior do que eu esperava	Um relay consultou várias vezes durante um período em que a conta rastreada estava ativa	O Auto-relay de Posts do X cobra por post. Toque no relay → verifique o contador Today.
Cobrança de excedente no PRO·assinatura mesmo tendo postado pouco	Outro uso no chat (relays, relatórios, novas tentativas de busca)	/setup → 💳 Comprar Créditos → Uso deste mês. Compare com a cobrança medida.
Chat FREE foi cobrado	Não deveria acontecer — FREE não tem cliente Stripe	Reporte imediatamente; isso é um bug de faturamento.
Assinatura mostra "cancelada" mas eu não cancelei	O cancelamento do Stripe pode ser acionado por falha na renovação automática do cartão	Verifique o e-mail em busca de recibos do Stripe, atualize o cartão via /setup → 💳 → 🛠 Gerenciar assinatura (Portal do Cliente Stripe).
Cancelei a assinatura, ainda PRO	Cancelamento no fim do período: PRO até o fim do período pago	Esperado. Reverte para FREE no fim do próximo ciclo de faturamento.

Dashboard público

Sintoma	Causa provável	Solução
Projeto não aparece no xbot.ninja	Não atinge os limites (≥ 300 de pontuação máxima, ≥ 5 posts, ≥ 2 usuários ativos neste mês)	A URL direta ainda funciona. Aguarde a métrica atingir o limite. Configurações de KOL independente são intencionalmente ocultadas do showcase.
Projeto no xbot.ninja mas o logo está faltando	Logo nunca foi enviado, ou o envio falhou	/setup → 🎨 Personalização → 🖼 Logo. Envie um PNG quadrado.
URL pública mostra o nome antigo do projeto	Atualização no próximo ciclo de relatório	Renomeie via /setup → 🎨 Personalização → 🏷 Nome. O slug da URL + o card atualizam assim que o próximo relatório disparar.
URL retorna 404	Chat foi excluído permanentemente, OU os limites ainda não foram atingidos, então o showcase o oculta	Confirme o ID do chat via /setup → ℹ️ Sobre. Teste a URL direta https://xbot.ninja/?chatId=<id>.

Escalonamento

Quando as matrizes acima não resolverem, contate o suporte com o modelo abaixo.

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.

Para onde enviar:

• Suporte geral: formulário de contato do bws.ninja
• Issues no GitHub (aberto à comunidade): bws-api-telegram-xbot/issues
• Telegram direto: @BlockchainWebServices

Tempos de resposta por severidade:

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

Comandos de diagnóstico úteis

Comando	O que mostra
/setup → ℹ️ Sobre	ID do chat, plano, cronograma, projeto — copie isso literalmente no suporte
/setup → 🎯 Filtros	String literal da query da API do X
/setup → 💳 Comprar Créditos → 📊 Uso deste mês	Contadores diários e mensais de fetched_posts — identifica falhas silenciosas (muitas tentativas, zero posts → provavelmente 402s)
/setup → 📡 Auto-relay de Posts do X → @conta	Estado por relay (ativo / pausado, encaminhamentos de hoje, limite diário)
/get_chatid	Apenas o ID do chat (uma linha, se Sobre for demais)

Para onde ir depois

• Instalação — reinstalação limpa se tudo mais falhar
• O menu /setup — referência completa do menu
• Preços — solução de problemas do lado do faturamento
• Suporte — FAQ + escalonamento de contato