Requisitos e limites do Telegram

1. Limites de mensagens

  • Mensagem apenas 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 preferidas.
  • Tamanho ideal: 900x900 pixels, máximo 5 MB.

3. Requisitos de arquivo

A API do Telegram tem requisitos específicos para arquivos enviados:

  • Os 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 uma URL (o bot baixa e envia):
    • Fotos: ≤ 5 MB
    • Outros arquivos: ≤ 20 MB
  • Limites diferentes se aplicam para postagem:
    • Fotos: 10 MB
    • Outros arquivos: 2 GB

Leia mais na fonte original

Criação do bot do Telegram

Um bot do Telegram é criado através do BotFather, o sistema oficial de gerenciamento de bots do Telegram. Esta ferramenta verificada (indicada por uma marca de seleção azul) permite criar um bot sem qualquer conhecimento de programação e protege você de imitadores fraudulentos.

Etapas de criação:

  1. Inicie uma conversa com BotFather.
  2. Envie o comando: /newbot
  3. Escolha um nome para o seu bot (este é o nome de exibição para os usuários).
  4. Escolha um nome de usuário para o seu bot. Ele deve terminar com bot ou _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: Este token é uma senha para o seu bot. Salve-o com segurança e nunca o compartilhe com ninguém.

Navegue até a seção Messengers, selecione Telegram e cole o token do seu bot no campo fornecido.

Clique no botão Done 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 os participantes: todos os participantes podem escrever nele.

O canal do Telegram é um meio de comunicação unidirecional. Apenas o proprietário ou administradores podem enviar mensagens, enquanto os demais participantes só podem visualizá-las e deixar comentários.

Como adicionar um bot a um grupo/canal do Telegram

Este 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.

Adicionar 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?

Passo 1. Vá para Gerenciamento de Grupo/Canal e selecione a guia Administradores

Passo 2. Clique no botão "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 direitos para ler e deletar mensagens.

Variáveis para trabalhar em chats

Por favor, note!

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 funcionou. Você pode gerar essas variáveis no bloco para rastrear o trabalho.

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 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 do diálogo do qual a mensagem foi encaminhada

  • Adicionar e remover de um grupo

Neste 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 removido pelo administrador

chat_join_request - uma solicitação foi recebida para adicionar ao canal

edited_channel_post - a postagem no canal foi editada (edited_channel_post + data e hora da edição)

Os callbacks são exibidos na seção Clients

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 postagem

like_deleted - removeu uma curtida da postagem

O número no callback (new_like; like_deleted) é o ID da mensagem que foi respondida ou removida.

Por favor, note!

  • Callbacks para reações não são exibidos em canais do Telegram! Callbacks para reações vêm apenas em grupos.
  • Se uma pessoa colocou várias curtidas e depois removeu 1 delas, não mostra qual foi removida.

Quando callbacks com reações aparecem em grupos, as variáveis estão disponíveis no bloco:

reaction_on_message_id - contém o ID da mensagem que foi respondida

reaction_from - id de quem houve uma reação

message_from_username - nome de usuário de quem houve uma reação (se houver)

reaction_from_name - nome de quem houve 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 variável tg_quote, que contém o texto citado.

Callbacks com boost

  • chat_boost_from user #{id_user} - deu um boost ao chat (ou canal):

Quando este callback é acionado, as variáveis são geradas:

  • remove_boost_from user #{id_user} - eles tiraram o boost do chat (ou canal):

Quando este callback é acionado, as variáveis são geradas:

  • chat_boost from giveaway - emitido 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 deletar 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 deletar mensagens.

A variável del_tg_system_messages só pode ser usada em grupos. Em canais, atribuir qualquer valor a esta variável não levará a nenhum resultado.

Direitos de administrador nas configurações do grupo 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 deletada

- A mensagem está fixada

- O usuário entrou no grupo

- O usuário saiu do grupo

Se você quiser deletar apenas tipos selecionados de notificações do sistema, então, em vez da variável del_tg_system_messages, crie a variável del_tg_chosen_messages e coloque nela um array com os tipos de notificações a serem deletadas, separados por vírgulas.

Por favor, note!

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 deletada,
  • 'new_chat_photo' – a foto do grupo foi alterada,
  • 'new_chat_title' – o nome do grupo foi alterado

Por exemplo, você precisa deletar todos os tipos de mensagens do sistema, exceto entrar no grupo; então você precisa adicionar todos os tipos de callbacks à variável do projeto (constante), exceto "new_chat_member".

Por favor, note!

Deletar notificações do sistema não afetará os callbacks. Apenas a mensagem do sistema do diálogo do Telegram será deletada.

Fórum no Telegram

Um fórum é um grupo onde você pode criar tópicos separados para discussão. Você pode usar funções padrão no fórum: anexar arquivos de mídia, postar enquetes e configurar notificações. Você também pode fixar mensagens e adicionar bots individuais a cada chat.

O objetivo principal de um fórum é estruturar a comunicação dentro de uma grande comunidade.

Em um chat de grupo padrão com muitos participantes, seguir conversas e encontrar mensagens relevantes se torna difícil. Os fóruns resolvem isso organizando as discussões em threads temáticas dedicadas. Isso segmenta automaticamente a comunidade por tópico e interesse, tornando a comunicação mais focada e gerenciável.

Apenas 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, você não poderá 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 de cliente do Telegram com um site?

Leia mais sobre como vincular um cliente do telegram e um cliente do site após um pagamento bem-sucedido aqui.