Criar um bot no Telegram é gratuito e pode ser feito em poucos minutos: você registra o bot no BotFather, recebe um token de acesso e usa a Bot API para testar uma mensagem. Não é preciso começar com um servidor ou uma biblioteca de programação.
Neste tutorial, o caminho será o mais simples: criar o bot, descobrir o chat_id da conversa e enviar uma mensagem com uma requisição HTTPS. No fim, também mostro o que muda quando a ideia é transformar o teste em uma automação recorrente.
O que você precisa antes de começar
- Uma conta no Telegram;
- um navegador ou terminal para fazer requisições HTTPS;
- um chat seu para testar o envio;
- um local seguro para guardar o token do bot.
O token funciona como a credencial que autentica o bot na API. Por isso, trate-o como uma senha: não publique em artigo, planilha compartilhada, repositório ou mensagem. Se ele escapar, o BotFather permite revogá-lo e gerar outro.
1. Crie o bot pelo BotFather
- Abra o Telegram e procure por @BotFather, conferindo se é o perfil oficial.
- Envie o comando
/newbot. - Informe o nome que aparecerá para as pessoas.
- Escolha um username terminado em
bot, comoavisos_da_loja_bot. - Copie o token fornecido pelo BotFather e guarde-o em local protegido.
O nome e o username têm funções diferentes: o primeiro é o rótulo exibido na conversa; o segundo é o identificador usado para encontrar o bot. Se o username escolhido já existir, o Telegram pedirá outro.
2. Inicie a conversa e descubra o chat_id
Um bot precisa saber para qual conversa a mensagem será enviada. Para um teste privado, abra o link do bot ou procure o username criado e toque em Iniciar. Depois, envie uma mensagem curta, como /start.
Agora faça uma chamada ao método getUpdates. Troque apenas SEU_TOKEN pelo valor real:
curl "https://api.telegram.org/botSEU_TOKEN/getUpdates"A resposta vem em JSON. Procure por message, depois por chat e, dentro dele, pelo campo id. Esse número é o chat_id do destino. Em grupos e canais, o identificador e as permissões podem ser diferentes, então faça o primeiro teste em uma conversa privada.
chat_id aponta para o destino da mensagem. Imagem: arte original JSMS.Atenção: colocar o token diretamente na URL do navegador pode deixá-lo no histórico. Para um teste rápido, prefira um terminal e, em uma automação real, use variável de ambiente ou o armazenamento seguro da ferramenta escolhida.
3. Envie a primeira mensagem
O método sendMessage exige dois dados: chat_id e text. Esta chamada usa POST e envia os parâmetros em JSON:
curl -X POST "https://api.telegram.org/botSEU_TOKEN/sendMessage" \
-H "Content-Type: application/json" \
-d '{"chat_id":"SEU_CHAT_ID","text":"Mensagem enviada pelo meu bot"}'Se tudo estiver certo, a API responderá com um objeto JSON cujo campo ok será true e a mensagem aparecerá na conversa. O texto enviado pode ter entre 1 e 4.096 caracteres depois do processamento de entidades, conforme a documentação da API.
4. Transforme o teste em automação
O comando acima é útil para validar o acesso, mas não é uma automação por si só. Para enviar avisos de estoque, lembretes ou alertas, coloque a mesma requisição dentro de uma rotina que seja executada quando algo acontecer.
- n8n: use um gatilho, monte o texto e faça uma chamada HTTP para o método
sendMessage. O guia do JSMS sobre como criar e testar um webhook no n8n ajuda a entender a parte de entrada do fluxo. - Script: guarde token e
chat_idem variáveis de ambiente e execute a chamada quando um sistema gerar um evento. - Agendamento: rode o script em um servidor, computador ligado ou serviço de automação no horário desejado. O Telegram apenas entrega a mensagem; a agenda pertence à ferramenta que dispara a chamada.
Em qualquer opção, registre a resposta da API e trate falhas. Um fluxo que ignora erros pode parecer automático, mas deixa de avisar justamente quando o serviço está indisponível ou quando o chat foi configurado errado.
getUpdates ou webhook: qual escolher?
O getUpdates usa long polling: o seu programa consulta a API para buscar novas atualizações. É simples para testes locais e pequenos scripts. Já o setWebhook informa ao Telegram uma URL HTTPS para que ele envie as atualizações ao seu sistema.
Os dois métodos são alternativas para receber atualizações e não devem ser usados ao mesmo tempo no mesmo bot. Para apenas enviar alertas, você pode chamar sendMessage sem montar um webhook. O webhook passa a fazer sentido quando o bot também precisa reagir a mensagens recebidas em tempo real.
Erros comuns no primeiro teste
O campo ok veio como false
Confira se o token foi copiado inteiro, sem espaços, e se o endpoint começa com https://api.telegram.org/bot. Não compartilhe o token para pedir ajuda; substitua-o por um marcador antes de enviar qualquer captura.
O bot não encontrou nenhuma atualização
Abra a conversa correta e envie uma mensagem ao bot antes de chamar getUpdates. Se um webhook já estiver configurado, esse método não funcionará até que a integração anterior seja removida ou alterada.
A API respondeu, mas a mensagem não chegou
Veja se o chat_id pertence ao destino esperado e se o bot ainda está na conversa. No primeiro diagnóstico, use um chat privado e uma mensagem curta; depois adicione grupos, canais e regras de negócio um de cada vez.
Perguntas frequentes
Preciso pagar para criar um bot no Telegram?
O cadastro pelo BotFather e o acesso básico à Bot API não exigem a contratação de um plano. O custo pode aparecer na infraestrutura que executa sua automação, como um servidor ou uma plataforma externa.
Posso colocar o token no código?
Funciona tecnicamente, mas é uma má prática. Use variável de ambiente, cofre de segredos ou recurso equivalente. Se o token for exposto, revogue-o no BotFather e substitua a credencial.
Quando devo usar webhook?
Use webhook quando o bot precisar receber atualizações em uma aplicação com URL HTTPS pública. Para um teste local ou para consultar mensagens ocasionalmente, getUpdates costuma ser o caminho mais simples.