Base de conhecimento GetMyBot

Projetos e canais

Crie um projeto, conecte um bot e acompanhe seu estado. Veja como usar vários canais, trocar o token e recuperar um bot pausado ou bloqueado pelo plano.

Nesta página

Um projeto reúne as configurações, reações e dados de um bot ou serviço. Um canal conecta o projeto a um lugar onde as pessoas conversam, como um bot do Telegram, o chat do site ou outro aplicativo de mensagens. Uma escola, por exemplo, pode ter um projeto com dois canais: Telegram e site.

Crie o projeto em Projetos e depois adicione um canal. Para conectar o Telegram, você precisará do token fornecido pelo @BotFather, que permite administrar o bot. O seletor na parte superior do painel permite alternar entre projetos.

O bot não se limita ao Telegram. Você pode conectar WhatsApp e VK ao mesmo projeto e usar as mesmas reações nos diferentes canais. Veja Canais e, para conectar o WhatsApp, WhatsApp.

Conectar um bot

  1. Se ainda não tem um projeto, abra Projetos e clique em Adicionar projeto. No cartão dele, clique em Adicionar canal e escolha Telegram. Para o primeiro bot, você também pode usar o assistente inicial.
  2. Cole o token do @BotFather e clique em Verificar. O GetMyBot exibirá o @username encontrado, para que você confirme que usou o token correto.
  3. Clique em Conectar. O token é guardado de forma criptografada, e o recebimento de mensagens começa imediatamente.

O Telegram aparecerá no cartão do projeto, junto dos demais canais. O cartão mostra o nome do projeto, o @username do bot, o número de usuários, as reações ativas e as solicitações de hoje. Veja o saldo de solicitações em Faturamento ou Estatísticas.

Vários bots

Uma conta pode administrar vários projetos e bots ao mesmo tempo. O limite depende do seu plano, no item «número máximo de bots». Alterne entre eles no seletor superior ou em Projetos. Reações, Conversas e Estatísticas mostram os dados do projeto selecionado.

Como o bot recebe mensagens

Após a conexão, o GetMyBot recebe automaticamente os eventos do Telegram, como mensagens, cliques em botões, entradas em conversas e pagamentos. Não é preciso configurar o recebimento separadamente: basta manter o token válido. Dependendo da configuração do servidor, o Telegram envia os eventos para a plataforma por um webhook, ou a plataforma consulta o Telegram regularmente, por long polling.

Ligar e desligar

Cada bot tem uma opção ligado / desligado no cartão Estado do bot, em Configurações. Um bot desligado não responde às mensagens. A mudança entra em vigor imediatamente, sem precisar reconectar o canal.

Estado do projeto e disponibilidade do canal

Em Projetos, o estado do projeto aparece separadamente: Ativo, Pausado ou Congelado. Isso não confirma a entrega de mensagens pelo Telegram. Cada canal tem sua própria indicação: Online, Sem sinal, Configurado, Desativado ou Projeto inativo. Assim, um projeto ativo com chat no site e sem Telegram não aparece como parado.

Se um projeto ativo tiver exatamente um canal de Telegram ligado, Online significa que o processo que atende ao bot enviou um sinal recente. Se o sinal faltar, aparece Sem sinal. Com vários canais de Telegram ligados, aparece Configurado, pois o sinal compartilhado do projeto não pode confirmar o estado de cada canal. Para outros canais, Configurado indica que a conexão foi feita, mas não garante a entrega de cada mensagem.

A plataforma usa vários processos para atender aos bots. Cada um registra um sinal a cada 30 segundos para os bots sob seus cuidados. O sinal é considerado recente por um minuto e meio; um único sinal perdido não deve fazer o estado oscilar.

Na prática:

  • O indicador pode demorar a mudar. Depois de conectar o bot ou reiniciar a plataforma, Online pode levar até esse intervalo para aparecer.
  • Se Sem sinal continuar por mais de alguns minutos em um canal de Telegram ligado, confira o token e o cartão Bot health (saúde do bot) nas Configurações. O projeto continua ativo até que você o pause ou o plano cause seu congelamento.
  • O sinal é compartilhado entre os processos e não depende do servidor que respondeu à sua solicitação. Se houver vários canais de Telegram, ele não confirma individualmente cada um.

O que acontece quando o bot fica offline

A cada minuto, a plataforma verifica os sinais. Se um bot ligado não tiver nenhum sinal recente, abre um incidente, identifica a causa uma vez e tenta restabelecer o serviço automaticamente.

O cartão Bot health, nas Configurações, mostra uma destas quatro causas:

  • Webhook: o Telegram não entrega as atualizações à plataforma, que registra o webhook novamente.
  • Token revogado: getMe retorna 401. Não há reinício automático nesse caso. Gere outro token no @BotFather e insira-o em Trocar token.
  • Nenhum servidor atendendo ao bot: as atualizações não estão sendo processadas, e a plataforma reinicia o bot.
  • Causa não identificada: o Telegram não respondeu à verificação.

O reinício faz o mesmo que o botão Sincronizar: verifica o token com getMe e registra o webhook novamente. As tentativas têm intervalos cada vez maiores. O histórico de reinícios do incidente mostra o horário, o resultado, a mensagem de erro, se houver, e o horário da próxima tentativa.

Quando o bot fica sem sinal por mais tempo que o limite indicado no cartão Bot health (cinco minutos por padrão), o proprietário recebe um aviso «Bot offline» no painel e por email. As conversas incluídas na lista de destinatários de avisos recebem uma mensagem do próprio bot. O aviso é enviado uma vez por incidente. Quando os sinais voltam, chega outro aviso, «Bot online novamente», com a duração da interrupção. O cartão mantém o histórico de incidentes e suas causas.

Congelamento por limite do plano

Além da opção ligado / desligado, um bot pode ficar congelado. A plataforma faz isso automaticamente quando o plano atual não cobre mais a quantidade de bots conectados. Há duas causas:

  • Limite de bots excedido: você mudou para um plano que permite menos bots do que já estão conectados.
  • Assinatura não renovada: o plano pago terminou e passou a valer o limite do plano gratuito.

Um bot congelado não recebe mensagens: a plataforma interrompe o recebimento, em vez de apenas mostrar uma indicação. Dados, reações e assinantes são preservados, portanto o congelamento pode ser revertido.

Como descongelar: ative um plano pago que comporte a quantidade de bots necessária. A plataforma restaura os bots automaticamente, começando pelos mais antigos, até atingir o limite do novo plano. Não é possível escolher quais voltam primeiro. Se você precisa manter outros bots, remova as conexões desnecessárias antes de pagar pelo plano.

O congelamento da conta inteira é diferente: todos os bots e envios ficam pausados, e o painel mostra «Conta congelada». Para resolver esse caso, procure o suporte. Veja também Pagamentos e saldo.

Perfil e sincronização

O botão Sincronizar, em Configurações, atualiza o nome do bot a partir do Telegram caso você o tenha alterado no @BotFather. A foto do bot é atualizada automaticamente.

Trocar o token

Se você gerou um novo token no @BotFather (Bot Settings → Revoke / New token), atualize-o em Configurações → Canais → Telegram 🔑. O novo token deve pertencer ao mesmo bot (ter o mesmo ID interno do Telegram) — assim todas as reações, assinantes e dados são preservados. Se o canal do Telegram não aparecer, escolha «Alterar token» na mesma janela.

Transferir o bot para outra conta

Configurações → Trocar proprietário envia um convite por email para transferir o projeto a outra conta do GetMyBot. O convite é válido por 72 horas. Até que a outra pessoa o aceite, o projeto continua com você e é possível cancelar a transferência. Depois da aceitação, o proprietário muda e você perde o acesso ao projeto. Use essa opção ao entregar um projeto a um cliente ou colega.

Modelos de bot

Um modelo guarda uma cópia das configurações e de todas as reações do bot para aplicação em outro:

  • Criar modelo, em Configurações, salva o bot atual como um modelo com nome.
  • Aplicar modelo substitui as configurações do bot escolhido pelas do modelo e acrescenta as reações do modelo às existentes.

Isso ajuda a criar bots semelhantes para vários projetos.

O catálogo de soluções prontas usa um assistente de instalação. Informe os dados pedidos, confira a compatibilidade e as conexões necessárias, e revise os recursos que serão criados. Depois de instalar, conclua os passos restantes e teste o fluxo com uma solicitação de exemplo.

Esse assistente é diferente de aplicar uma cópia do bot, descrita acima. A verificação anterior à instalação aponta parâmetros ou recursos ausentes. Marcar um passo como concluído não comprova que um serviço externo esteja funcionando.

Resultados de uma solução pronta

Escolha o período que deseja analisar. Para comparar os resultados, selecione um modo disponível e confira o tamanho da amostra e os avisos de diagnóstico. Ter dados insuficientes ou não ter uma comparação é diferente de obter um resultado igual a zero.

Próximos passos