Como criar um bot no Telegram
Este artigo explica como conectar seu bot do Telegram e apresenta os fundamentos para trabalhar com canais e grupos.
Requisitos e limites do Telegram
1. Limites de mensagens
Mensagem somente de texto: Máximo de 4.096 caracteres.
Mensagem com imagem: Máximo de 1.024 caracteres (para uma imagem de 1080x1080 px).
2. Requisitos de imagem
Formato: Imagens quadradas são preferíveis.
Tamanho ideal: 900x900 pixels, máximo 5 MB.
3. Requisitos de arquivo
A API do Telegram tem requisitos específicos para arquivos enviados:
Bots podem enviar arquivos de até 2 GB.
Você pode usar file_id para trabalhar com arquivos enviados anteriormente. Nesse caso, os limites de arquivo seguem a documentação do Telegram.
Os arquivos podem ser enviados usando um URL (o bot baixa e envia):
Fotos: ≤ 5 MB
Outros arquivos: ≤ 20 MB
Limites diferentes se aplicam para publicação:
Fotos: 10 MB
Outros arquivos: 2 GB
Criação de bot no Telegram
Um bot do Telegram é criado por meio do BotFather, o sistema oficial de gerenciamento de bots do Telegram. Esta ferramenta verificada (indicada por um tique azul) permite criar um bot sem nenhum conhecimento de programação e protege você de imitadores fraudulentos.
Etapas de criação:
Inicie uma conversa por BotFather.
Envie o comando:
/newbotEscolha um nome para o seu bot (este é o nome exibido para os usuários).
Escolha um nome de usuário para o seu bot. Ele deve terminar com
botou_bot(por exemplo,my_test_bot).
Se o nome de usuário estiver disponível, o BotFather enviará uma mensagem de confirmação contendo um "token"—uma chave única para acesso à API.
Importante: Esse token é uma senha para o seu bot. Guarde-o com segurança e nunca o compartilhe com ninguém.
Navegue até a seção Mensageiros seção, selecione Telegram, e cole o token do seu bot no campo fornecido.
Clique no Concluído botão para concluir a configuração do bot e ativar a conexão com o seu projeto.
Trabalhando com grupos/canais do Telegram
Informações úteis
Um grupo do Telegram é um canal de comunicação entre participantes: todos os participantes podem escrever nele.
O canal do Telegram é um meio de comunicação unilateral. Apenas o proprietário ou os administradores podem enviar mensagens, enquanto o restante dos participantes pode apenas visualizá-las e deixar comentários.
Como adicionar um bot a um grupo/canal do Telegram
Esse recurso para o bot está incluído no BotFather:
Passo 1. Vá para as configurações do bot:
Passo 2. Clique em "Allow Groups?"
Passo 3. Deve haver um status ativado.
Adicione um bot como administrador em um grupo/canal
Para automatizar o trabalho em chats e canais, você precisa adicionar seu próprio bot como Administrador.
Como fazer isso?
Passo 1. Vá para o gerenciamento de Grupo/Canal e selecione a Administradores aba
Passo 2. Clique em "Add Admin" .
Passo 3. Digite o nome de usuário do seu bot na caixa de pesquisa.
Passo 4. Para funcionalidade completa, certifique-se de que o bot tenha permissão para ler e excluir mensagens.
Variáveis para trabalhar em chats
Por favor, observe!
Salvar variáveis em chats de grupo para eventos como entrar em um chat, sair de um chat, novo like etc. não está disponível.
As variáveis estarão disponíveis apenas dentro do bloco que foi executado. Você pode exibir essas variáveis no bloco para acompanhar o funcionamento.
Isso NÃO afetará o funcionamento dos chatbots de forma alguma; será impossível rastrear quem entrou/saiu na seção de clientes.
Variáveis com informações sobre o autor da mensagem
message_from - o ID do autor da mensagem
message_from_name - o nome do autor da mensagem
message_from_username - o apelido do autor da mensagem no Telegram
Variáveis com informações sobre a mensagem encaminhada
reply_message_id - o número da mensagem que está sendo encaminhada
reply_from - quem é o autor da mensagem encaminhada
reply_from_name - o nome da pessoa cuja mensagem está sendo encaminhada
reply_from_username - o apelido da pessoa cuja mensagem está sendo encaminhada
reply_from_chat_id - o número da conversa de onde a mensagem foi encaminhada
Adição e remoção de um grupo
Nesse caso, os callbacks new_chat_member e left_chat_member são acionados (as variáveis não são salvas no cartão do cliente):
chat_member_name - nome de usuário
chat_member_username - apelido do usuário
chat_member_id - número do usuário
Callbacks no Telegram
client_unsubscribed - o cliente cancelou a inscrição, bloqueou o bot
client_returned - o cliente desbloqueou o bot
Callbacks em grupos/canais
new_chat_member - um novo usuário foi adicionado
left_chat_member - o usuário saiu do canal
kicked_chat_member - o usuário foi excluído pelo administrador
chat_join_request - foi recebida uma solicitação para entrar no canal
edited_channel_post - a publicação no canal foi editada (edited_channel_post + data e hora da edição)
Os callbacks são exibidos na Clientes seção
bot_added_to_group - um bot foi adicionado ao chat (não importa qual, ele responderá a qualquer um, mesmo que o bot conectado tenha sido adicionado ao próprio grupo);
bot_left_group - um callback semelhante é a remoção do bot do canal;
new_like - curtiu a publicação
like_deleted - removeu uma curtida da publicação
O número no callback (new_like; like_deleted) é o ID da mensagem à qual se respondeu ou da qual foi removida a curtida.
Por favor, observe!
Os callbacks de reações não são exibidos nos canais do Telegram! Os callbacks de reações aparecem apenas em grupos.
Se uma pessoa colocou várias curtidas e depois excluiu 1 delas, não é mostrado qual foi excluída.
Quando callbacks com reações aparecem em grupos, variáveis ficam disponíveis no bloco:
reaction_on_message_id - contém o ID da mensagem à qual foi respondida
reaction_from - id de quem houve a reação
message_from_username - nome de usuário de quem houve a reação (se houver)
reaction_from_name - nome de quem foi a reação
Além disso, se o Telegram responder a uma mensagem, a variável reply_text no cartão conterá o texto completo da mensagem que foi respondida.
Se uma mensagem foi enviada como resposta (citando uma mensagem anterior), o sistema também gerará a tg_quote variável, que contém o texto citado.
Callbacks com boost
chat_boost_from user #{id_user} - deu um boost ao chat (ou canal):
Quando esse callback é acionado, as variáveis são geradas:
remove_boost_from user #{id_user} - retiraram o boost do chat (ou canal):
Quando esse callback é acionado, as variáveis são geradas:
chat_boost from giveaway - concedido durante o sorteio de estrelas no canal
remove_chat_boost from giveaway - o período de boost para o sorteio de estrelas no canal terminou
Como automatizar a remoção de notificações do sistema em grupos
Para excluir automaticamente todas as mensagens do sistema, basta atribuir qualquer valor à variável del_tg_system_messages (a variável pode ser uma constante do projeto ou uma variável de transação) e dar ao bot permissão para excluir mensagens.
A variável del_tg_system_messages só pode ser usada em grupos. Em canais, atribuir qualquer valor a essa variável não levará a nenhum resultado.
Direitos de administrador nas configurações de grupos do Telegram
Os seguintes tipos de notificações do sistema são removidos:
- O nome do grupo foi alterado
- A foto do grupo foi alterada
- Foto do grupo excluída
- A mensagem está fixada
- O usuário entrou no grupo
- O usuário saiu do grupo
Se você quiser excluir apenas tipos selecionados de notificações do sistema, em vez da variável del_tg_system_messages, crie a variável del_tg_chosen_messages e coloque nela uma matriz com os tipos de notificações a serem excluídos, separados por vírgulas.
Por favor, observe!
Essas variáveis funcionarão apenas para grupos do Telegram, mas não para canais.
Opções de notificação do sistema:
'new_chat_member' – o usuário entrou no grupo,
'left_chat_member' – o usuário saiu do grupo,
'pinned_message' – a mensagem está fixada,
'delete_chat_photo' – foto do grupo excluída,
'new_chat_photo' – a foto do grupo foi alterada,
'new_chat_title' – o nome do grupo foi alterado
Por exemplo, você precisa excluir todos os tipos de mensagens do sistema, exceto a entrada em um grupo; então você precisa adicionar todos os tipos de callbacks à variável (constante) do projeto, exceto "new_chat_member".
Por favor, observe!
Excluir notificações do sistema não afetará os callbacks. Apenas a mensagem do sistema da conversa do Telegram será excluída.
Fórum no Telegram
Um fórum é um grupo no qual você pode criar tópicos separados para discussão. Você pode usar funções padrão no fórum: anexar arquivos de mídia, publicar enquetes e configurar notificações. Também é possível fixar mensagens e adicionar bots individuais a cada chat.
O principal objetivo de um fórum é estruturar a comunicação dentro de uma comunidade grande.
Em um chat de grupo padrão com muitos participantes, acompanhar conversas e encontrar mensagens relevantes se torna difícil. Os fóruns resolvem isso organizando as discussões em tópicos temáticos dedicados. Isso segmenta automaticamente a comunidade por tópico e interesse, tornando a comunicação mais focada e gerenciável.
Somente o proprietário do grupo pode criar um tópico se houver mais de 100 membros no grupo. Se o grupo estiver vinculado a um canal, então você não conseguirá criar um tema. Os tópicos são ativados nas Configurações do grupo:
Como administrador, você pode criar um tópico nas configurações do grupo do fórum:
Após conectar os Tópicos, o avatar mudará de redondo para quadrado, o que permite distinguir o fórum de outros chats do Telegram:
Como configurar um pacote Telegram-client com um site?
Leia mais sobre como vincular um cliente do Telegram e um cliente do site após um pagamento bem-sucedido aqui.
Atualizado