Telegram
Como criar um agente no Telegram e conectar ao QuickClaw.
Pre-requisitos
- Uma conta no Telegram
- O app do Telegram instalado no celular ou desktop
- Um agente criado no QuickClaw (qualquer tier)
Criando o agente no BotFather
O @BotFather e o agente oficial do Telegram para criar e gerenciar bots:
Abra o Telegram e busque @BotFather
Na barra de busca, digite @BotFather e abra a conversa com o agente oficial (selo de verificado azul).
Envie /newbot
Envie o comando /newbot. Ele guiara voce no processo.
Escolha nome e username
Escolha um nome de exibicao (ex: "Meu Agente IA").
Escolha um username unico que termine em "bot" (ex: meu_agente_ia_bot).
Copie o token gerado
O BotFather retornara o token do agente (formato: 123456789:ABCDefGH...).
Seguranca
Guarde o token em local seguro. Qualquer pessoa com ele pode controlar seu agente. Se vazar, use /revoke no BotFather para gerar um novo.
Cole o token no QuickClaw
No dashboard, va na aba Canais do seu agente, expanda o card Telegram e cole o token. Clique em Habilitar Telegram.
Formato do token
O token do Telegram segue este formato:
123456789:ABCDefGHIjklMNOpqrSTUvwxYZID numerico + dois pontos + sequencia alfanumerica.
Controle de acesso (Allowlist)
A allowlist define quem pode conversar com o agente.
Politicas disponiveis
- Apenas quem eu permitir (recomendado) — Somente IDs cadastrados
- Qualquer pessoa — Todos podem falar (consome creditos!)
- Pareamento (avancado) — Usuarios se pareiam com codigo
Como descobrir seu ID do Telegram
- Pesquise por @userinfobot
- Envie
/start - Ele responde com seu ID numerico (ex:
123456789)
Dica
Configure a allowlist ANTES de tornar o agente publico para evitar uso nao autorizado de creditos.
Grupos Telegram
O agente pode participar de grupos:
- Adicione o agente ao grupo pelo username (@seu_bot)
- Na aba Canais > Telegram > Controle de Acesso, mude para modo Grupo
- Adicione o ID do grupo (numero negativo, ex:
-1001234567890)
Como descobrir o ID do grupo
- Adicione @RawDataBot ao grupo
- Ele mostra o ID do chat (ex:
-1001234567890) - No QuickClaw, digite a parte numerica (sem o sinal de menos)
Mencao requerida
Por padrao, o agente so responde em grupos quando mencionado (@bot). Desative para que responda a todas as mensagens.
Grupos grandes
Mantenha mencao ativada em grupos grandes para evitar consumo excessivo de creditos.
Modo de streaming
Dois modos de envio de resposta (avancado):
- Progressivo (padrao) — Edita a mensagem em tempo real enquanto processa
- Completo — Envia a resposta inteira de uma vez, sem edicoes
Configuracoes avancadas
Disponiveis em Canais > Telegram > Configuracoes Avancadas:
Mensagens
- Preview de links — Pre-visualizacao de URLs
- Prefixo nas respostas — Texto antes de cada resposta
- Reacao de leitura — Emoji ao comecar a processar
- Limite por mensagem — Caracteres maximos antes de dividir
Midia e Historico
- Midia maxima — Tamanho max de arquivos (1-50 MB)
- Historico grupos/DMs — Mensagens mantidas no contexto
Acoes permitidas
- Enviar mensagens, Reagir com emoji, Criar enquetes
- Deletar mensagens, Editar mensagens, Enviar stickers
- Criar topicos (modo forum)
Sistema
- Escrita de config pelo canal — Comandos no chat alteram config
- Timeout API — Tempo maximo para chamadas (5-120s)
Reinicio do gateway
Salvar configuracoes reinicia o gateway. O agente pode levar 30-60 segundos para voltar a responder.
Testando
- Abra o Telegram
- Busque o username do agente (ex:
@meu_agente_ia_bot) - Envie "Ola"
- Aguarde a resposta (primeiras mensagens podem demorar mais)
Dicas
- Use
/setdescriptionno BotFather para descricao do perfil - Use
/setuserpicpara foto de perfil - Use
/setcommandspara menu de comandos rapidos - Se o token vazar, use
/revokee atualize no QuickClaw - Configure a allowlist ANTES de tornar o agente publico
