# Como fazer um bot para o Telegram

{% hint style="warning" %}

#### **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

[Leia mais na fonte original](https://core.telegram.org/bots/api#sending-files)
{% endhint %}

## 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:**

1. **Inicie uma conversa** por [BotFather](https://t.me/botfather).
2. Envie o comando: `/newbot`
3. **Escolha um nome** para o seu bot (este é o nome exibido 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:** Esse token é uma senha para o seu bot. Guarde-o com segurança e **nunca o compartilhe** com ninguém.

<div data-with-frame="true"><figure><img src="/files/bdf01a52698723ab9d1ff5252e77d266b10dfbac" alt=""><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/8f7b863a1862f7f7431018d9a48543a5121e5449" alt=""><figcaption></figcaption></figure></div>

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:

<div data-with-frame="true"><figure><img src="/files/5ee6aa0d83d12fa3db7868840e2f9dd735368248" alt="" width="563"><figcaption></figcaption></figure></div>

Passo 2. Clique em **"Allow Groups?"**

<div data-with-frame="true"><figure><img src="/files/972647454141349cd540249f20f38307057b6d43" alt="" width="563"><figcaption></figcaption></figure></div>

Passo 3. Deve haver um status ativado.

<div data-with-frame="true"><figure><img src="/files/eb34ff046e38bda93b0ba69df0be3c039b000e5d" alt="" width="563"><figcaption></figcaption></figure></div>

### 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

<div data-with-frame="true"><figure><img src="/files/8c5e0e4e7fa0e32e884d7b4826b7bb5c5224af94" alt="" width="563"><figcaption></figcaption></figure></div>

Passo 2. Clique em **"Add Admin"** .

<div data-with-frame="true"><figure><img src="/files/0c74ed03fededf5ecd5c62e096a2998ec959020a" alt="" width="563"><figcaption></figcaption></figure></div>

Passo 3. Digite o nome de usuário do seu bot na caixa de pesquisa.

<div data-with-frame="true"><figure><img src="/files/cfca71ec8d50b527819c75efe2d82b743bd98d07" alt="" width="563"><figcaption></figcaption></figure></div>

Passo 4. Para funcionalidade completa, certifique-se de que o bot tenha permissão para ler e excluir mensagens.

<div data-with-frame="true"><figure><img src="/files/92a451ba1aa5bb01e09c4191e4d9dccfeccc3527" alt="" width="375"><figcaption></figcaption></figure></div>

### Variáveis para trabalhar em chats

{% hint style="warning" %}
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.
{% endhint %}

* Variáveis com informações sobre o autor da mensagem

message\_from - o ID do autor da mensagem&#x20;

message\_from\_name - o nome do autor da mensagem

message\_from\_username - o apelido do autor da mensagem no Telegram

<div data-with-frame="true"><figure><img src="/files/b26ecf9de2e8286995fa0491b0cac008f6aaf6a4" alt="" width="310"><figcaption></figcaption></figure></div>

* Variáveis com informações sobre a mensagem encaminhada

reply\_message\_id - o número da mensagem que está sendo encaminhada&#x20;

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&#x20;

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

<div data-with-frame="true"><figure><img src="/files/80ea246d8b889947061775daad840c4592b990d0" alt="" width="349"><figcaption></figcaption></figure></div>

#### Callbacks em grupos/canais

new\_chat\_member - um novo usuário foi adicionado

left\_chat\_member - o usuário saiu do canal&#x20;

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)

<div data-with-frame="true"><figure><img src="/files/87932c4e7bd542ec1e1987f71d4a9512d21852ee" alt="" width="347"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/9c5fe3fb0db21ce0e4e7af686a9c368a7a0b9422" alt="" width="333"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/53e9d484dcf24e0b5210ee8f27e519fc62da9ea6" alt="" width="322"><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/888a4a51ea29d77afcda8b306beaf68aa3ce5e35" alt="" width="358"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/03221eb6ff484ee1d14b46337c88988ee925afc1" alt="" width="326"><figcaption></figcaption></figure></div>

O número no callback (new\_like; like\_deleted) é o ID da mensagem à qual se respondeu ou da qual foi removida a curtida.

{% hint style="warning" %}
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.
  {% endhint %}

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

<div data-with-frame="true"><figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfQptKK4YrlEATINQANRDaNEnpT95W_lgIGjMfOitIn387SG1GKI_n02rgWMZUrCP6hEGEnYAPiY99aZud2Ze4iOCYSlDCpzNsyHAMFdHd_mCxP5VfBpSx2iG7HzP1lgzDDly1Ziw?key=lL8rEUrFbZeHFjWugKFnxg" alt="" width="375"><figcaption></figcaption></figure></div>

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.

<div data-with-frame="true"><figure><img src="/files/33e6ae9fdb7653eafd648203358f1b69c9ccf68c" alt="" width="337"><figcaption></figcaption></figure></div>

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.

<div data-with-frame="true"><figure><img src="/files/e30ddf57240b3f48b83089593db3444db4970455" alt="" width="188"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/efc03fc772e7b7e8eedee6041ba7b644937d29e1" alt="" width="375"><figcaption></figcaption></figure></div>

#### Callbacks com boost

* chat\_boost\_from user #{id\_user} - deu um boost ao chat (ou canal):

<div data-with-frame="true"><figure><img src="/files/44d0cc274062bf8d9a44a1288889a3c77dc5abbb" alt="" width="375"><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/21939b091436431edf41dac077a206865e03337e" alt="" width="375"><figcaption></figcaption></figure></div>

* remove\_boost\_from user #{id\_user} - retiraram o boost do chat (ou canal):

<div data-with-frame="true"><figure><img src="/files/b0006b3841492048fdb957f805f18e47f70fad9d" alt="" width="375"><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/c473c24a28b487a27d2723517fa641477294ab46" alt="" width="344"><figcaption></figcaption></figure></div>

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

<div data-with-frame="true"><figure><img src="/files/dcdd9e9c2f940906faf8022a04150812cf3bf585" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/01bf7bf72a1c1bae9431ca5bb5bf197e0bbf6e6e" alt="" width="349"><figcaption></figcaption></figure></div>

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

{% hint style="warning" %}
Por favor, observe!

Essas variáveis funcionarão apenas para grupos do Telegram, mas não para canais.
{% endhint %}

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

<div data-with-frame="true"><figure><img src="/files/29e335866ecceca5b8e2f2066e40f8df515d09e3" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
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.
{% endhint %}

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

<div data-with-frame="true"><figure><img src="/files/699bea57a7d2cda61429114107a5279708b84b41" alt="" width="375"><figcaption></figcaption></figure></div>

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**:

<div data-with-frame="true"><figure><img src="/files/1e79f10108b32970e0557bc6c32c14f3783a4424" alt="" width="563"><figcaption></figcaption></figure></div>

Como administrador, você pode criar um tópico nas configurações do grupo do fórum:

<div data-with-frame="true"><figure><img src="/files/d5f27e61d97447048a0814ac3987dc358f0d9988" alt="" width="563"><figcaption></figcaption></figure></div>

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:

<div data-with-frame="true"><figure><img src="/files/6d4276caca37dc9cebdbc633aa667e3bc7321360" alt="" width="563"><figcaption></figcaption></figure></div>

### 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](#how-to-configure-a-telegram-client-bundle-with-a-website).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/pt/chatbot/mensageiros/telegram/chatbot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.