# Configurações de chat e mensageiro do Telegram

**Trabalhando com IDs de plataforma no MaviBot**

No MaviBot, todas as entidades do Telegram (usuários, grupos, canais) são identificadas por uma `platform_id` variável genérica. Essa variável não distingue entre tipos de entidade.

**Problema:** Para usar funções como `aceitar` ou `rejeitar` que exigem tipos específicos de entidade, você precisa saber tanto o *chat* ID quanto o *usuário* ID separadamente.

**Solução:** Quando você receber um callback ou mensagem, armazene imediatamente o `platform_id` valor em duas variáveis distintas e com nomes que indiquem sua finalidade:

* **`chat_id`** – para armazenar o ID do grupo/canal.
* **`user_id`** – para armazenar o ID do usuário individual.

Isso permite referenciar o ID correto mais tarde na lógica da sua aplicação.

## Como alterar o nome do chat via bot do Telegram

<details>

<summary>Descrição</summary>

**tg\_set\_group\_title(platform\_id, title)** -&#x20;

Parâmetros:

<table><thead><tr><th width="294.828125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td> <mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>o ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a>  </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> title</strong></td><td>novo nome do chat</td></tr></tbody></table>

</details>

## Como alterar a descrição do chat via bot do Telegram

<details>

<summary>Descrição</summary>

**tg\_set\_chat\_description(platform\_id, description)**

<table><thead><tr><th width="294.828125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td> <mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>o ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a>  </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> description</strong></td><td>novo nome do chat</td></tr></tbody></table>

</details>

## Como definir um avatar em um grupo/chat no Telegram

<details>

<summary>Descrição</summary>

**tg\_set\_chat\_photo(platform\_id, photo)**

<table><thead><tr><th width="294.828125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td> <mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a><strong>,</strong> no qual você deseja definir um avatar</td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong>  foto</strong></td><td>link da foto</td></tr></tbody></table>

</details>

## Como excluir um avatar em um grupo/chat no Telegram

<details>

<summary>Descrição</summary>

**tg\_delete\_chat\_photo(platform\_id)**

<table><thead><tr><th width="294.828125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td> <mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a><strong>,</strong> no qual você precisa definir um avatar</td></tr></tbody></table>

</details>

## Como banir um grupo do Telegram

<details>

<summary>Descrição</summary>

**tg\_ban\_chat\_sender\_chat(platform\_id, sender\_chat\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="294.828125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td> <mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a><strong>, que você precisa banir</strong></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> sender_chat_id</strong></td><td>ID do chat que vai banir</td></tr></tbody></table>

Ao mesmo tempo, o proprietário do chat banido não pode escrever em nome de seus outros chats até que seja desbanido.

</details>

## Como desbanir um grupo do Telegram

<details>

<summary>Descrição</summary>

**tg\_unban\_chat\_sender\_chat(platform\_id, sender\_chat\_id)**

Parâmetro:

<table><thead><tr><th width="294.828125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td> <mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a><strong>,</strong> no qual você desbane </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> sender_chat_id</strong></td><td>ID do chat que você desbane </td></tr></tbody></table>

</details>

## Como criar um link de convite para entrar em um chat do Telegram

<details>

<summary>Descrição</summary>

**tg\_create\_chat\_invite\_link(platform\_id, member\_limit, hours, request, name)**&#x20;

Parâmetro:

<table><thead><tr><th width="282.87109375">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr><tr><td><strong>member_limit</strong></td><td>limite no número de participantes</td></tr><tr><td><strong>hours</strong></td><td>Tempo de expiração do link (em horas)</td></tr><tr><td><strong>request</strong></td><td>um parâmetro que, após clicar no link, deve gerar uma solicitação para entrar no chat.</td></tr><tr><td><strong>name</strong> </td><td>nome do link</td></tr></tbody></table>

{% hint style="info" %}
Ao passar o **member\_limit** parâmetro, o valor do **request** parâmetro é alterado automaticamente para **Falso**. Se você precisar aceitar solicitações de entrada, deixe o **member\_limit** parâmetro em branco.
{% endhint %}

**Criando link de convite do chat**

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

</details>

## Como excluir um link de convite do chat no Telegram

<details>

<summary>Descrição</summary>

**tg\_revoke\_chat\_invite\_link(platform\_id, invite\_link)**

Parâmetros:

<table><thead><tr><th width="294.828125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td> <mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td> <mark style="color:vermelho;"><strong>!</strong></mark><strong> invite_link</strong></td><td>link que você precisa excluir</td></tr></tbody></table>

</details>

## Como inativar todos os links existentes e substituí-los por um link&#x20;

<details>

<summary>Descrição</summary>

&#x20;**tg\_export\_chat\_link(platform\_id)**

Parâmetros:

<table><thead><tr><th width="294.828125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td> <mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td> <mark style="color:vermelho;"><strong>!</strong></mark><strong> invite_link</strong></td><td>link que você precisa excluir</td></tr></tbody></table>

O resultado é que um link será a única forma de entrar no grupo até que links adicionais sejam criados de outras maneiras.

{% hint style="warning" %}
Use com cautela. Todos os links de login existentes para o seu grupo se tornarão inativos.
{% endhint %}

</details>

## Como aceitar solicitação e adicionar usuário no canal/chat do Telegram

<details>

<summary>Descrição</summary>

**tg\_approve\_chat\_join\_request(chat\_id, user\_id)**

Parâmetros:

<table><thead><tr><th width="279.9765625"></th><th></th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> chat_id</strong></td><td>ID do grupo/canal no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> user_id</strong></td><td>ID do usuário no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr></tbody></table>

Aceitação da solicitação:

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

</details>

## Como recusar solicitação no canal/chat do Telegram

<details>

<summary>Descrição</summary>

**tg\_decline\_chat\_join\_request(chat\_id, user\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="279.9765625"></th><th></th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> chat_id</strong></td><td>ID do grupo/canal no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> user_id</strong></td><td>ID do usuário no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr></tbody></table>

Recusa da solicitação

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

</details>

## Como bloquear usuário no Telegram

<details>

<summary>Descrição</summary>

**tg\_ban\_chat\_member(chat\_id, user\_id, hours)**&#x20;

Parâmetros:

<table><thead><tr><th width="283.67578125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> chat_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> user_id</strong></td><td>ID do usuário no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> para bloquear</td></tr><tr><td><strong>hours</strong></td><td>Duração do bloqueio em horas. Por padrão, o bloqueio é permanente. Se você especificar uma duração de bloqueio superior a 366 dias, o bloqueio será definido como permanente.</td></tr></tbody></table>

</details>

## Como desbloquear usuário no Telegram&#x20;

<details>

<summary>Descrição</summary>

**tg\_unban\_chat\_member(chat\_id, user\_id)** &#x20;

Parâmetros:

<table><thead><tr><th width="283.67578125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> chat_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> user_id</strong></td><td>ID do usuário no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a><strong>,</strong>  que você precisa desbloquear</td></tr></tbody></table>

</details>

## Como verificar o status da assinatura no Telegram

<details>

<summary>Descrição</summary>

**tg\_get\_chat\_member(chat\_id, user\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="283.67578125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> chat_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> user_id</strong></td><td>ID do usuário no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a><strong>,</strong> de quem estamos verificando a assinatura</td></tr></tbody></table>

</details>

## Como determinar o número de membros no canal/chat&#x20;

<details>

<summary>Descrição</summary>

**tg\_get\_chat\_member\_count(platform\_id)**

Parâmetros:

<table><thead><tr><th width="283.67578125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr></tbody></table>

</details>

## Como verificar se um membro do chat está em uma lista específica

<details>

<summary><strong>some_client_in_list(list_id, recepient)</strong></summary>

Parâmetros:

<table><thead><tr><th width="283.67578125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> list_id</strong></td><td>número da lista</td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> recepient</strong></td><td> ID do usuário no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a>. Para clientes de chat, esse valor está na variável chat_member_id.</td></tr></tbody></table>

</details>

## Como mostrar as ações do bot ao usuário (digitar/selecionar um sticker etc.)

<details>

<summary>Descrição</summary>

**tg\_send\_chat\_action(platform\_id, bot\_action,  message\_thread\_id)**

<mark style="color:padrão;background-color:green;">**! Trabalhe com conta empresarial do Telegram**</mark>

Parâmetros:

<table><thead><tr><th width="286.74609375">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a>  </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> bot_action</strong></td><td>ação do bot a partir da lista</td></tr><tr><td><strong>message_thread_id</strong> </td><td>ID do tópico (disponível para supergrupos se a funcionalidade de fórum estiver disponível).</td></tr></tbody></table>

</details>

<details>

<summary><mark style="color:laranja;">Lista de ações disponíveis <strong>bot_action</strong></mark></summary>

***typing*** para mensagens de texto, \
\&#xNAN;***upload\_photo*** para fotos, \
\&#xNAN;***record\_video*** ou ***upload\_video*** para vídeos, \
\&#xNAN;***record\_voice*** ou ***upload\_voice*** para mensagens de voz, \
\&#xNAN;***upload\_document*** para documentos comuns, \
\&#xNAN;***choose\_sticker*** para stickers, \
\&#xNAN;***find\_location*** para dados de localização, \
\&#xNAN;***record\_video\_note*** ou ***upload\_video\_note*** para vídeo-mensagem.&#x20;

</details>

{% hint style="info" %}
Essa notificação será exibida até que qualquer resposta seja recebida do bot, mas por no máximo 5 segundos.
{% endhint %}

## Como mostrar notificação de alerta ao usuário

<details>

<summary>Descrição</summary>

**tg\_answer\_callback\_query(callback\_query\_id, text,show\_alert,cache\_time)**&#x20;

<table><thead><tr><th width="309.5234375">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> callback_query_id</strong> <strong>(obrigatório)</strong></td><td>Este ID permite identificar a pessoa que clicou no botão e mostrar a ela a notificação de alerta.</td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> text (obrigatório)</strong> </td><td>Texto da notificação de alerta.</td></tr><tr><td><strong>show_alert</strong></td><td>Indicação de notificação que desaparece (False — notificação em estilo tooltip que some, True — notificação persistente em janela)</td></tr><tr><td><strong>cache_time</strong></td><td>A quantidade máxima de tempo, em segundos, durante a qual o resultado de uma solicitação de callback pode ser armazenado em cache no lado do cliente. Os aplicativos do Telegram oferecerão suporte ao cache a partir da versão 3.14. O valor padrão é 0</td></tr></tbody></table>

</details>

<details>

<summary>Exemplo</summary>

As notificações de alerta são mostradas apenas como resultado de clicar no botão de callback no Telegram.

\
Por exemplo, usamos os seguintes botões:

\[{"line":0,"index\_in\_line":0,"text":"111","type":"inline","callback":"first"}, {"line":1,"index\_in\_line":0,"text":"222","type":"inline","callback":"second"}, {"line":2,"index\_in\_line":0,"text":"333","type":"inline","callback":"third"}]&#x20;

<figure><img src="/files/ad39c2f94cd145b993f5999bb6fe28ae4d340269" alt="" width="563"><figcaption></figcaption></figure>

Depois de clicar em um botão, chega um callback com o texto contido no campo correspondente. Quando você clicar no botão “111”, você receberá um callback com o texto “first".

<figure><img src="/files/9f6bfdee122a710dd72f696ae28fc30ef9810a58" alt="" width="563"><figcaption></figcaption></figure>

Vamos criar um bloco Start e especificar o texto desejado no gatilho. No nosso caso: **"first**

<figure><img src="/files/068d8dece276da437bf094b48a2d7e6f0d168a9c" alt=""><figcaption></figcaption></figure>

Se no **Matches** campo você selecionar **Ignorando erros e imprecisões**, este bloco poderá ser reutilizado posteriormente para todas as variantes semelhantes que diferem em 1–2 caracteres. Por exemplo, para agradecer ao usuário por fornecer uma avaliação com esse botão.

Em seguida, na calculadora, use a **tg\_answer\_callback\_query** função e passe os seguintes parâmetros:\
**callback\_query\_id** - este ID permite identificar o usuário que pressionou o botão e exibir a notificação de alerta para ele              \
**text** - texto da notificação de alerta.

<figure><img src="/files/53d39f6b9591ca331456ac756f24c88123865226" alt="" width="563"><figcaption></figcaption></figure>

Exemplo de código para copiar:

`tg_answer_callback_query('#{callback_query_id}', "Você pressionou o botão 111")`&#x20;

{% hint style="warning" %}
Atenção! O parâmetro callback\_query\_id deve ser passado exatamente como mostrado no exemplo, ou seja, dentro de '#{}'
{% endhint %}

Se tudo estiver configurado corretamente, pressionar o botão resultará em uma notificação de alerta com o texto especificado. Na versão mobile, o nome do bot aparecerá como cabeçalho acima do texto.

<figure><img src="/files/51fa33b9eba53d572f21d77b7abbba17c0709e6e" alt="" width="563"><figcaption></figcaption></figure>

Se você quiser mostrar uma simples **mensagem pop-up** em vez disso, passe **Falso** como terceiro parâmetro, como mostrado no exemplo abaixo:\
tg\_answer\_callback\_query('#{callback\_query\_id}', "Você passou pelo botão 222", False)

<figure><img src="/files/fa1e0a2eca056cf2ca6f8f650a788b19dc58b015" alt="" width="563"><figcaption><p>Quando o botão é pressionado<br>com esses parâmetros, uma notificação desse tipo<br>aparecerá por alguns segundos.</p></figcaption></figure>

</details>

## Adicionando um redirecionamento de bot com uma tag como resposta de botão de callback

<details>

<summary>Descrição</summary>

**tg\_callback\_url\_open(callback\_query\_id, url, cache\_time)**

Parâmetros:

<table><thead><tr><th width="309.5234375">Parâmetros</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> callback_query_id</strong></td><td>Este ID permite identificar a pessoa que clicou no botão e mostrar a ela a notificação de alerta.</td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> url</strong> </td><td>URL apontando para o bot e um parâmetro (formato: t.me/seu_bot?start=XXXX, onde your_bot - é o nome do bot)</td></tr><tr><td><strong>cache_time</strong></td><td>A quantidade máxima de tempo, em segundos, durante a qual o resultado de uma solicitação de callback pode ser armazenado em cache no lado do cliente. Os aplicativos do Telegram oferecerão suporte ao cache a partir da versão 3.14. O valor padrão é 0</td></tr></tbody></table>

</details>

<details>

<summary>Exemplo</summary>

ВNa resposta do botão de callback, você pode adicionar uma transição para o bot usando a tag thetg\_callback\_url\_open('#{callback\_query\_id}', 't.me/bot\_name?start=XXXX')

Por exemplo, vamos usar os seguintes botões:

\[{"line":0,"index\_in\_line":0,"text":"111","type":"inline","callback":"first"}, {"line":1,"index\_in\_line":0,"text":"222","type":"inline","callback":"second"}, {"line":2,"index\_in\_line":0,"text":"333","type":"inline","callback":"third"}]

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

Depois de clicar em um botão, chega um callback com o texto contido no campo correspondente. Quando você clicar no botão “111”, você receberá um callback com o texto “first".

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

Crie um bloco com uma verificação de condição primária e especifique o texto desejado na condição. No nosso caso: “first”:

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

Se no **Opção correspondente** campo você selecionar **Ignorar erros e imprecisões**, este bloco poderá ser reutilizado posteriormente para todas as variantes semelhantes que diferem em 1–2 caracteres. Por exemplo, para agradecer ao usuário por fornecer uma avaliação com esse botão.

Em seguida, na calculadora do bloco, especifique tg\_callback\_url\_open('#{callback\_query\_id}', 't.me/bot\_name?start=XXXX'):

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

</details>

## Como promover um usuário a administrador em um supergrupo ou canal

<details>

<summary>Descrição</summary>

**tg\_promote\_user(platform\_id, user\_id, promote\_options\_list)**

Parâmetros:

<table><thead><tr><th width="269.9765625">Parâmetro</th><th width="515.17578125">Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>o identificador de um supergrupo ou, se usado em um canal, o nome de usuário do canal no formato @channelusername no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> user_id</strong></td><td>o identificador de um usuário no Telegram. <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> promote_options_list</strong></td><td>lista de permissões a serem ativadas. </td></tr></tbody></table>

</details>

<details>

<summary><mark style="color:vermelho;">Parâmetro obrigatório: <strong>promote_options_list</strong></mark></summary>

As seguintes permissões podem ser especificadas em **promote\_options\_list** :

1. **is\_anonymous** — oculta a presença do administrador no chat,&#x20;
2. **can\_manage\_chat** — o administrador pode acessar o log de eventos do chat, estatísticas do chat, estatísticas de mensagens em canais, visualizar membros do canal, visualizar administradores anônimos em supergrupos e contornar o modo lento. Esse nível de permissão é concedido por padrão se algum dos privilégios subsequentes for especificado
3. **can\_post\_messages** — o administrador pode criar postagens no canal <mark style="color:vermelho;">(apenas canais)</mark>
4. **can\_edit\_messages** — o administrador pode editar mensagens de outros usuários e fixar mensagens <mark style="color:vermelho;">(apenas canais)</mark>&#x20;
5. **can\_delete\_messages** — o administrador pode excluir mensagens de outros usuários
6. **can\_manage\_video\_chats** — o administrador pode gerenciar chats de vídeo,
7. **can\_restrict\_members** — o administrador pode restringir membros, banir/desbanir no chat,&#x20;
8. **can\_promote\_members** — o administrador pode nomear novos administradores com um subconjunto dos seus próprios privilégios ou rebaixar administradores que tenha nomeado direta ou indiretamente (por exemplo, administradores nomeados por ele)
9. **can\_change\_info** — o administrador pode alterar o título, a foto e outras configurações do chat
10. **can\_invite\_users** — o administrador pode convidar novos usuários para o chat
11. **can\_pin\_messages** — o administrador pode fixar mensagens <mark style="color:vermelho;">(apenas supergrupos).</mark>

</details>

<details>

<summary>Exemplo</summary>

Exemplo: promovendo um usuário a administrador em um supergrupo:

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

Neste exemplo, além das permissões especificadas, a permissão can\_manage\_chat será concedida por padrão.

<div data-with-frame="true"><figure><img src="/files/b20d311edad6e9ab8d95c0f40c4f415ec8c5d83d" alt="" width="563"><figcaption><p>Atribuindo permissões a um usuário</p></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/bbeb08678199476301a8271e75c778227da63a3c" alt="" width="563"><figcaption><p>Definindo um título personalizado de administrador</p></figcaption></figure></div>

Exemplo de código para copiar

<pre data-full-width="false"><code><strong>Exemplo 1. 
</strong><strong>promote_options_list = ‘[“can_promote_members”,”can_change_info”,”can_invite_users”]’ 
</strong>tg_promote_user(platform_id, user_id, promote_options_list)

Exemplo 2. 
promote_options_list = '["can_manage_chat","can_post_messages","can_edit_messages","can_delete_messages","can_manage_video_chats","can_promote_members","can_restrict_members","can_invite_users","can_pin_messages"]' 
result=tg_promote_user(platform_id, reply_from, promote_options_list)  
</code></pre>

</details>

## Como alterar o título de um administrador usando um bot no Telegram

<details>

<summary>Descrição</summary>

**tg\_set\_administrator\_title(platform\_id, user\_id, title)** &#x20;

Parâmetros:&#x20;

<table><thead><tr><th width="303.94921875">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>identificador do supergrupo no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> user_id</strong></td><td>identificador do usuário no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a>  </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> title</strong></td><td><p>título de administrador</p><p>Restrições para o título:</p><p>Comprimento: 0–16 caracteres, emojis não são permitidos</p></td></tr></tbody></table>

{% hint style="warning" %}
IMPORTANTE!&#x20;

Isso funciona apenas para usuários que foram promovidos a administradores no supergrupo pelo bot
{% endhint %}

Exemplo de código para copiar:

```
result=tg_set_administrator_title(platform_id, reply_from, "firetitle")
```

</details>

## Restrições gerais para membros regulares do chat ou usuários específicos do Telegram

<details>

<summary>Descrição</summary>

**tg\_chat\_permission(platform\_id, permission, media\_permissions)**

Parâmetros:

<table><thead><tr><th width="318.76171875">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>identificador do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> permission</strong></td><td><p>um array de valores da lista de restrições (veja abaixo).</p><p>1 = ação permitida</p><p>0 = ação proibida</p><p>O índice do array corresponde à posição na lista de restrições</p></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> media_permissions</strong></td><td><p>um array de valores que define permissões relacionadas a mídia (detalhes abaixo).</p><p>1 = ação permitida</p><p>0 = ação proibida</p><p>O índice do array corresponde à posição na lista de permissões de mídia</p></td></tr></tbody></table>

</details>

<details>

<summary><strong>Lista de restrições para o parâmetro obrigatório </strong><mark style="color:vermelho;"><strong>permission</strong></mark></summary>

**Lista de restrições para** **permission:**\
1\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_send\_messages** - permissão para enviar mensagens de texto, contatos, locais e estabelecimentos.\
2\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_send\_media\_messages** - permissão para enviar áudio, documentos, fotos, vídeos, vídeo-mensagens e mensagens de voz. Ela requer **can\_send\_messages**\
3\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_send\_polls** - permissão para enviar enquetes. Ela requer **can\_send\_messages**\
4\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_send\_other\_messages** - permissão para enviar animações, jogos, stickers e usar bots inline. Ela requer **can\_send\_media\_messages**\
5\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_add\_web\_page\_previews** - permissão para adicionar prévias de páginas da web às mensagens. Ela requer **can\_send\_media\_messages**\
6\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_change\_info** - permissão para alterar o título, a foto e outras configurações do chat. Isso é ignorado em supergrupos públicos.\
7\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_invite\_users** - permissão para convidar usuários\
8\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_pin\_messages** - permissão para fixar mensagens. Isso é ignorado em supergrupos públicos.\
9\. **can\_manage\_topics** - permissão para criar tópicos em grupos de fórum. Se usada em um grupo do tipo incorreto, a função falhará e retornará um erro.

</details>

<details>

<summary><strong>Lista de valores para o parâmetro obrigatório </strong><mark style="color:vermelho;"><strong>media_permissions</strong></mark></summary>

#### Valores para conceder permissões relacionadas à mídia **media\_permissions:**&#x20;

1\. **can\_send\_audios** - permissão para enviar arquivos de áudio\
2\. **can\_send\_documents** -permissão para enviar documentos\
3\. **can\_send\_photos** - permissão para enviar fotos\
4\. **can\_send\_videos**  - permissão para enviar vídeos\
5\. **can\_send\_video\_notes** - permissão para enviar mensagens de vídeo redondas\
6\. **can\_send\_voice\_notes** - permissão para enviar mensagens de vozя

</details>

## Restrições pessoais do Telegram para usuários regulares do chat ou para usuários específicos do Telegram

<details>

<summary>Descrição</summary>

**tg\_restrict\_chat\_member(platform\_id, user\_id, minutes, permission, media\_permissions).**

Parâmetros:

| Parâmetro                                                        | Descrição                                                                                                                                                                                                     |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:vermelho;">**!**</mark>**&#x20;platform\_id** | ID do chat no Telegram [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)                                                                                                                             |
| <mark style="color:vermelho;">**!**</mark>**&#x20;user\_id**     | ID do usuário no Telegram [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)                                                                                                                          |
| **minutes**                                                      | o número de minutos durante os quais a restrição ficará ativa. Se você não definir um valor, o padrão será **3600**, que equivale a **60 horas**. Se você definir como **0**, a restrição se torna permanente |
| **permission**                                                   | um array de valores da [lista de restrições de permissão](#list-of-restrictions-for-the-required-parameter-permission).                                                                                       |
| **media\_permissions**                                           | uma lista de valores para conceder permissões relacionadas à mídia                                                                                                                                            |

</details>

<details>

<summary><strong>Lista de restrições para o parâmetro obrigatório </strong><mark style="color:vermelho;"><strong>permission</strong></mark></summary>

**Lista de restrições para** **permission:**\
1\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_send\_messages** - permissão para enviar mensagens de texto, contatos, locais e estabelecimentos.\
2\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_send\_media\_messages** - permissão para enviar áudio, documentos, fotos, vídeos, vídeo-mensagens e mensagens de voz. Ela requer **can\_send\_messages**\
3\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_send\_polls** - permissão para enviar enquetes. Ela requer **can\_send\_messages**\
4\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_send\_other\_messages** - permissão para enviar animações, jogos, stickers e usar bots inline. Ela requer **can\_send\_media\_messages**\
5\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_add\_web\_page\_previews** - permissão para adicionar prévias de páginas da web às mensagens. Ela requer **can\_send\_media\_messages**\
6\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_change\_info** - permissão para alterar o título, a foto e outras configurações do chat. Isso é ignorado em supergrupos públicos.\
7\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_invite\_users** - permissão para convidar usuários\
8\. <mark style="color:vermelho;">**!**</mark>**&#x20;can\_pin\_messages** - permissão para fixar mensagens. Isso é ignorado em supergrupos públicos.\
9\. **can\_manage\_topics** - permissão para criar tópicos em grupos de fórum. Se usada em um grupo do tipo incorreto, a função falhará e retornará um erro.&#x20;

</details>

<details>

<summary>Lista de valores para o parâmetro obrigatório <mark style="color:vermelho;"><strong>media_permissions</strong></mark></summary>

#### Valores para conceder permissões relacionadas à mídia **media\_permissions:**&#x20;

1\. **can\_send\_audios** - permissão para enviar arquivos de áudio\
2\. **can\_send\_documents** -permissão para enviar documentos\
3\. **can\_send\_photos** - permissão para enviar fotos\
4\. **can\_send\_videos**  - permissão para enviar vídeos\
5\. **can\_send\_video\_notes** - permissão para enviar mensagens de vídeo redondas\
6\. **can\_send\_voice\_notes** - permissão para enviar mensagens de vozя

</details>

<details>

<summary>Exemplo</summary>

Exemplo de uso da função, onde o usuário fica restrito de tudo por 3 minutos:

<figure><img src="/files/d68fd9f8b210c167c2fa1131d88d77c5f11d1846" alt="" width="563"><figcaption></figcaption></figure>

Quando o usuário entra no chat, ele verá uma notificação informando que não pode enviar mensagens no chat.\
Se um limite de tempo for definido, ele também verá a duração dessa restrição.

<figure><img src="/files/5cb4b8bffd620733b5718e8dd9a5ca79672e6b14" alt=""><figcaption></figcaption></figure>

Exemplo de código para copiar:

```
permission = [0, 0, 0, 0, 0, 0, 0, 0] 
tg_restrict_chat_member(-1001607137668, 473737685, 3, permission)
```

</details>

## Como fixar mensagem

<details>

<summary>Descrição</summary>

**tg\_pin\_chat\_message(platform\_id, message\_id, disable\_notification)**&#x20;

Parâmetros:

<table><thead><tr><th width="311.3359375">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram  <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><strong>message_id</strong></td><td>ID da mensagem que precisa ser fixada</td></tr><tr><td><strong>disable_notification</strong></td><td>O parâmetro define se uma notificação deve ser enviada a todos os membros do chat sobre uma nova mensagem fixada (as notificações são sempre desativadas em canais e chats privados).<br>Se você não quiser enviar notificações, defina o parâmetro <strong>disable_notification</strong> como <strong>1</strong>.<br>Caso contrário, defina como <strong>0</strong>.</td></tr></tbody></table>

</details>

## Como desafixar mensagem

<details>

<summary>Descrição</summary>

**tg\_unpin\_chat\_message(platform\_id, message\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="311.3359375">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><strong>message_id</strong></td><td>ID da mensagem que deve ser desafixada. Se message_id não for fornecido, a mensagem fixada mais recente (pela data de envio) será desafixada</td></tr></tbody></table>

</details>

## Como desafixar todas as mensagens fixadas

<details>

<summary>Descrição</summary>

**tg\_unpin\_all(platform\_id)**

Parâmetros:

<table><thead><tr><th width="311.3359375">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr></tbody></table>

{% hint style="warning" %}
ATENÇÃO!

O Telegram tem uma limitação para as funções de fixar/desafixar mensagens.&#x20;

Os limites de tempo para usar **tg\_pin\_chat\_message / tg\_unpin\_chat\_message / tg\_unpin\_all&#x20;**<mark style="color:vermelho;">**NÃO são definidos pelo sistema MaviBot.**</mark>&#x20;

**Se o tempo permitido para fixar uma mensagem já tiver passado, a função ainda retornará true, mas o Telegram não aplicará a alteração.**

Também é importante observar que mensagens fixadas podem permanecer em cache, então elas podem não desaparecer visualmente imediatamente.
{% endhint %}

</details>

## Como criar uma enquete no Telegram

<details>

<summary>Descrição</summary>

**tg\_send\_poll(platform\_id, question, options, is\_anonymous, allows\_multiple\_answers, reply\_markup, disable\_notification, protect\_content, token, reply\_to\_message\_id,  message\_thread\_id, business\_connection\_id)**

Parâmetros:

<table><thead><tr><th width="311.3359375">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram  <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a> </td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> question</strong> </td><td>question</td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> options</strong></td><td>um array de opções de resposta</td></tr><tr><td><strong>is_anonymous</strong></td><td>1 - enquete anônima , '' - não anônima </td></tr><tr><td><strong>allows_multiple_answers</strong></td><td>1 - múltiplas respostas disponíveis, '' - uma resposta</td></tr><tr><td><strong>reply_markup</strong> </td><td>teclado ou '' - sem teclado </td></tr><tr><td><strong>disable_notification</strong></td><td>flag para envio com notificação sonora (padrão 0)<br>1 – desativar notificação no recebimento, 0 – enviar com notificação</td></tr><tr><td><strong>protect_content</strong></td><td>1 para proteger contra cópia e capturas de tela, '' sem proteção</td></tr><tr><td><strong>token</strong></td><td>token do bot; se não fornecido, o atual será usado</td></tr><tr><td>r<strong>eply_to_message_id</strong></td><td>ID da mensagem citada</td></tr><tr><td><strong>message_thread_id</strong></td><td>ID do tópico (disponível para supergrupos se a funcionalidade de fórum existir)</td></tr><tr><td><strong>business_connection_id</strong></td><td>valor ao conectar um bot (Business ID). Aparece em canais. Deve ser fornecido se o token do bot for usado e a mensagem precisar ser enviada por meio de uma conta de usuário conectada ao bot</td></tr></tbody></table>

</details>

<details>

<summary>Importante saber!</summary>

Observações

1\. A função retorna uma resposta do Telegram com **message\_id**. É melhor salvá-la. Usando message\_id, você pode parar a enquete com **tg\_stop\_poll** (veja a descrição abaixo) e obter o resultado.

2\. Se um usuário adiciona uma enquete em um mensageiro, um callback é enviado ao chat:

**poll\_added** - parte imutável \
YOUR QUESTION - texto da pergunta da enquete

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

Exemplo de callback ao adicionar uma enquete ao canal

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

Exemplo de callback ao adicionar uma enquete ao chat

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

O segundo callback após poll\_added contém números - isso nada mais é do que o identificador do usuário no Telegram que adicionou a enquete.

{% hint style="warning" %}
**Quando a enquete é criada pelo bot, o callback não chega.**
{% endhint %}

&#x33;**.** No canal, só é possível criar enquetes anônimas

{% hint style="info" %}
**Atenção, recomenda-se enviar para o grupo apenas enquetes anônimas!**
{% endhint %}

4\. Após criar a enquete, salve seu identificador na variável para entender de qual enquete o callback chegou.

</details>

<details>

<summary>Exemplo</summary>

O feedback do cliente é fundamental para o nosso crescimento. As enquetes oferecem um método simples para capturar esse feedback e traduzi-lo em conclusões de negócios concretas.

Exemplo de código para copiar:

```
/* Exemplo de criação de uma enquete simples */
options = ["white", "red", "blue", "green"]
poll1 = tg_send_poll(platform_id, 'Qual é a sua cor favorita?', options, 1, '', '', 1, '')
```

**Função para criar uma enquete no Telegram:**

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

**A enquete que criamos no Telegram**

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

</details>

## Como criar um quiz no Telegram

<details>

<summary>Descrição</summary>

**tg\_send\_quiz\_poll(platform\_id, question, options, explanation, correct\_option\_id, is\_anonymous, reply\_markup, parse\_mode, protect\_content, disable\_notification, token, reply\_to\_message\_id, message\_thread\_id )**

Parâmetros:&#x20;

<table><thead><tr><th width="311.25">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> question</strong> </td><td>question</td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> options</strong></td><td>um array de opções de resposta</td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> explanation</strong></td><td>texto exibido quando um usuário seleciona uma resposta errada ou clica no ícone da lâmpada em uma enquete no estilo quiz, 0–200 caracteres com no máximo duas quebras de linha após a análise de entidades.</td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> correct_option_id</strong></td><td>número da resposta correta, a numeração começa em 1</td></tr><tr><td><strong>is_anonymous</strong></td><td>1 - enquete anônima , '' - não anônima </td></tr><tr><td><strong>reply_markup</strong></td><td>teclado ou '' - sem teclado </td></tr><tr><td><strong>parse_mode</strong></td><td>formato da explicação: <code>markdown</code>, <code>html</code>, ou <code>''</code> (string vazia para sem formatação)</td></tr><tr><td><strong>protect_content</strong></td><td>1 para proteger contra cópia e capturas de tela, '' sem proteção</td></tr><tr><td><strong>disable_notification</strong></td><td>flag para envio com notificação sonora (padrão 0)<br>1 – desativar notificação no recebimento, 0 – enviar com notificação</td></tr><tr><td><strong>token</strong></td><td>token do bot; se não fornecido, o atual será usado</td></tr><tr><td><strong>reply_to_message_id</strong></td><td>ID da mensagem citada</td></tr><tr><td><strong>message_thread_id</strong></td><td>ID do tópico (disponível em supergrupos com recursos de fórum ativos)</td></tr></tbody></table>

</details>

<details>

<summary><mark style="color:laranja;">Importante saber!</mark></summary>

#### **Observações**

**1. Salve o `message_id`**

A função da API retorna uma resposta do Telegram contendo um **`message_id`**. Sempre salve este ID, pois ele é necessário para:

* Encerrar o quiz usando a `tg_stop_poll` função (veja a descrição abaixo).
* Obter os resultados finais.

**2. Callback `poll_added`**

Se um usuário adiciona uma enquete a um **canal**, o bot recebe um callback:

* **Formato:** `poll_added` + **Pergunta da enquete**
* **Se adicionado a um chat em grupo:** o callback também inclui o **ID de Usuário do Telegram** da pessoa que adicionou a enquete.

{% hint style="warning" %}
**Se criado pelo bot:** Nenhum `poll_added` callback é enviado.
{% endhint %}

**3. Restrição de canal**

Somente **quizzes anônimos** podem ser criados em canais.

**4. Callback `poll_answer` (Voto do usuário)**

Quando um usuário vota em um quiz enviado para um **chat privado** ou **group**, um callback é enviado para a conversa do bot com esse cliente:

* **Formato:** `poll_answer` + **ID da enquete** + **\[Índice da resposta]**
* **Exemplo:** `poll_answer 5325838371359031648 [3]`
* **Observação:** a numeração das respostas começa em **0**. `[3]` significa que o usuário selecionou a quarta opção de resposta.

**5. Webhook para enquetes não anônimas em grupos**

Para **enquetes não anônimas** em grupos onde o bot é administrador, um webhook é enviado para *cada voto*. Ao recebê-lo, o bot encaminhará o `poll_answer` callback (como no ponto 4) para sua conversa com o cliente correspondente.

**6. Requisito de ativação e melhor prática**

* **Requisito:** um bot não pode iniciar uma conversa. Se um cliente nunca contatou o bot, você não pode enviar uma mensagem direta em resposta ao voto dele até que ele **ative o bot primeiro** (por exemplo, enviando um `/start` comando).

{% hint style="info" %}
**Recomendação:** para evitar essa limitação, é **altamente recomendado enviar apenas quizzes anônimos para grupos.**
{% endhint %}

**7. Acompanhe suas enquetes**

Logo após criar um quiz, salve seu **ID da enquete** único em uma variável. Isso permite identificar a qual enquete específica um callback recebido se refere.

</details>

<details>

<summary>Exemplo</summary>

Exemplo de código para copiar.

```
options = ["white", "red", "blue", "green"] 
r = tg_send_quiz_poll(platform_id, "Qual cor é um crocodilo?", options, "Essa é a explicação", 4, '', '', '', '', 1)
```

Exemplo: criação de quiz.

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

</details>

## Como encerrar uma enquete

<details>

<summary>Descrição</summary>

**tg\_stop\_poll(platform\_id, message\_id)**

Parâmetros:

<table><thead><tr><th width="303.45703125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> message_id</strong></td><td>ID da mensagem da enquete/quiz. Ele pode ser obtido do webhook</td></tr></tbody></table>

{% hint style="info" %}
Chamar esta função para encerrar uma enquete/quiz retorna um dicionário contendo os resultados finais.
{% endhint %}

</details>

## Como trabalhar com tópicos no Telegram

{% hint style="warning" %}
Importante: o tópico principal do grupo não tem ID e requer funções separadas para trabalhar com ele.
{% endhint %}

### Como renomear o Tópico Geral do grupo

<details>

<summary>Descrição</summary>

**tg\_edit\_general\_forum\_topic(platform\_id, topic\_name)**

Parâmetros:

<table><thead><tr><th width="303.1171875">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> topic_name</strong></td><td>novo nome do tópico</td></tr><tr><td>bot_name</td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

</details>

<details>

<summary>Exemplo</summary>

O Tópico Geral dos grupos pode ser alterado usando a `tg_edit_general_forum_topic()` função. Ela requer dois parâmetros obrigatórios: o ID do chat e o novo nome do Tópico do Grupo:

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

</details>

<details>

<summary>Exemplo de código para copiar</summary>

*renomear o chat do Tópico Geral*/\
`answer = tg_edit_general_forum_topic(-1001839380031, 'General')`

</details>

### Como fechar o Tópico Geral

<details>

<summary>Descrição</summary>

**tg\_close\_general\_forum\_topic(platform\_id)**

Parâmetros:

<table><thead><tr><th width="315.3203125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td>bot_name</td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

</details>

<details>

<summary>Exemplo de código para copiar</summary>

/*fechar o chat do Tópico Geral*/\
`answer = tg_close_general_forum_topic(-1001839380031)`

</details>

### Como reabrir um Tópico Geral anteriormente fechado

<details>

<summary>Descrição</summary>

**tg\_reopen\_general\_forum\_topic(platform\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="315.3203125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td>bot_name</td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

</details>

<details>

<summary>Exemplo de código para copiar</summary>

/*reabrir o chat do Tópico Geral*/\
`answer = tg_reopen_general_forum_topic(-1001839380031)`

</details>

### Como ocultar o Tópico Geral

<details>

<summary>Descrição</summary>

**tg\_hide\_general\_forum\_topic(platform\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="315.3203125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td>bot_name</td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

O chat do Tópico Geral pode ser fechado para os participantes do Tópico (eles podem ler, mas não escrever) e ocultado da lista geral de chats do Telegram para novos usuários.

</details>

<details>

<summary>Exemplo de código para copiar</summary>

/ocultar o chat do Tópico Geral/\
`answer = tg_hide_general_forum_topic(-1001839380031)`

</details>

### **Como exibir o Tópico Geral ou restaurar sua visibilidade**

<details>

<summary>Descrição</summary>

**tg\_unhide\_general\_forum\_topic(platform\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="315.3203125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong> </td><td>ID do tópico dentro do Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td>bot_name</td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

{% hint style="warning" %} <mark style="color:vermelho;">**Importante!**</mark>&#x20;

Esta função não reabre o Tópico Geral; ela apenas o torna visível.
{% endhint %}

</details>

<details>

<summary>Exemplo de código para copiar</summary>

/*exibir o chat do Tópico Geral*/\
`answer = tg_unhide_general_forum_topic(-1001839380031)`

</details>

### Como criar um novo tópico no Telegram

<details>

<summary>Descrição</summary>

**tg\_create\_forum\_topic(platform\_id, name, icon, icon\_color)**&#x20;

Parâmetros:

<table><thead><tr><th width="312.953125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> name</strong></td><td>novo nome do tópico</td></tr><tr><td><strong>icon</strong></td><td>ID do emoji a ser definido para o tópico. Passado como uma string. Você só pode usar emojis da lista recuperada pela <code>tg_get_forum_icon</code> função.</td></tr><tr><td><strong>icon_color</strong></td><td>cor do emoji a partir da lista: 7322096, 16766590, 13338331, 9367192, 16749490, 16478047. Nem todos os emojis suportam mudanças de cor.</td></tr><tr><td>bot_name </td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

{% hint style="info" %}
A cor definida não pode ser alterada; a cor só pode ser atribuída ao criar o tópico.
{% endhint %}

Quando executada, a função retornará uma resposta contendo os parâmetros do novo tópico, incluindo o ID do tópico (necessário para várias funções).

</details>

<details>

<summary>Exemplo de código para copiar</summary>

Para criar um chat de tópico adicional\
`answer = tg_create_forum_topic(-1001839380031, 'second_bot_topic', None, 7322096)`

Para salvar o ID do chat de tópico adicional criado\
`answer={"ok":true,"result":{"message_thread_id":254,"name":"second_bot_topic","icon_color":7322096}}/`\
`idtema1=answer['result']['message_thread_id']`

</details>

### Como editar um tópico. Como renomear e/ou alterar o emoji de um tópico

<details>

<summary>Descrição</summary>

**tg\_edit\_forum\_topic(platform\_id, message\_thread\_id, name, icon)**&#x20;

Parâmetros:

<table><thead><tr><th width="301.7578125">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> message_thread_id</strong></td><td>ID do chat de tópico adicional</td></tr><tr><td><strong>name</strong></td><td>novo nome do tópico</td></tr><tr><td><strong>icon</strong></td><td>ID do emoji a ser definido para o tópico. Passado como uma string. Você só pode usar emojis da lista recuperada pela <code>tg_get_forum_icon</code> função.</td></tr><tr><td>bot_name</td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

</details>

<details>

<summary>Exemplo de código para copiar</summary>

`answer = tg_edit_forum_topic(-1001839380031, 254)`

</details>

### Como fechar um tópico selecionado

<details>

<summary>Descrição</summary>

Fechar um tópico significa torná-lo somente leitura; não é permitido escrever em um tópico fechado.

**tg\_close\_forum\_topic(platform\_id, message\_thread\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="300.9765625">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> message_thread_id</strong></td><td>ID do chat de tópico adicional</td></tr><tr><td>bot_name</td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

</details>

<details>

<summary>Exemplo de código para copiar</summary>

`answer = tg_close_forum_topic(-1001839380031, 254)`

</details>

### Como reabrir um tópico fechado anteriormente

<details>

<summary>Descrição</summary>

**tg\_reopen\_forum\_topic(platform\_id, message\_thread\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="300.9765625">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> message_thread_id</strong></td><td>ID do chat de tópico adicional</td></tr><tr><td>bot_name</td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

</details>

<details>

<summary>Exemplo de código para copiar</summary>

`answer = tg_reopen_forum_topic(-1001839380031, 254)`

</details>

### Como excluir um tópico e todas as suas mensagens

<details>

<summary>Descrição</summary>

**tg\_delete\_forum\_topic(platform\_id, message\_thread\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="300.9765625">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> message_thread_id</strong></td><td>ID do chat de tópico adicional</td></tr><tr><td>bot_name</td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

</details>

<details>

<summary>Exemplo de código para copiar</summary>

`answer = tg_delete_forum_topic(-1001839380031, 254)`

</details>

### Como desafixar todas as mensagens em um tópico

<details>

<summary>Descrição</summary>

**tg\_unpin\_topic\_messages(platform\_id, message\_thread\_id)**&#x20;

Parâmetros:

<table><thead><tr><th width="300.9765625">Parâmetro</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID do chat no Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><mark style="color:vermelho;"><strong>!</strong></mark><strong> message_thread_id</strong></td><td>ID do chat de tópico adicional</td></tr><tr><td>bot_name</td><td><p>parâmetro opcional: nome do bot.</p><p>Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se o seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Channels", no campo "Group ID".</p></td></tr></tbody></table>

</details>

<details>

<summary>Exemplo de código para copiar</summary>

`answer = tg_unpin_topic_messages(-1001839380031, 254)`

</details>

### Como obter a lista de emojis para um Tópico do Telegram

<details>

<summary>Descrição</summary>

<mark style="color:padrão;background-color:blue;">**Como obter a lista de emojis**</mark>

`tg_get_forum_icon()` – esta função retorna uma lista de emojis disponíveis para uso como ícones de tópicos do fórum. O resultado deve ser atribuído a uma variável, pois ela retorna um dicionário em que cada chave é um emoji e seu valor correspondente é o identificador exclusivo do emoji (`id`).

Parâmetros: <mark style="color:verde;">**nenhum.**</mark>&#x20;

</details>

<details>

<summary>O conteúdo da lista de emojis</summary>

Para obter a lista de emojis de um chat de Tópico, envie o comando para o chat relevante.

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

A função retornará a lista de emojis em sua resposta. Isso significa que a variável `answer` conterá um dicionário como seu valor.

{'📰': '5434144690511290129', '💡': '5312536423851630001', '⚡️': '5312016608254762256', '🎙': '5377544228505134960', '🔝': '5418085807791545980', '🗣': '5368697802761185083', '🆒': '5420216386448270341', '❗️': '5379748062124056162', '📝': '5357193964787081133', '📆': '5433614043006903194', '📁': '5357315181649076022', '🔎': '5309965701241379366', '📣': '5309984423003823246', '🔥': '5312241539987020022', '❤️': '5312138559556164615', '❓': '5377316857231450742', '📈': '5350305691942788490', '📉': '5350713563512052787', '💎': '5309958691854754293', '💰': '5350452584119279096', '💸': '5309929258443874898', '\U0001fa99': '5377690785674175481', '💱': '5310107765874632305', '⁉️': '5377438129928020693', '🎮': '5309950797704865693', '💻': '5350554349074391003', '📱': '5409357944619802453', '🚗': '5312322066328853156', '🏠': '5312486108309757006', '💘': '5310029292527164639', '🎉': '5310228579009699834', '‼️': '5377498341074542641', '🏆': '5312315739842026755', '🏁': '5408906741125490282', '🎬': '5368653135101310687', '🎵': '5310045076531978942', '🔞': '5420331611830886484', '📚': '5350481781306958339', '👑': '5357107601584693888', '⚽️': '5375159220280762629', '🏀': '5384327463629233871', '📺': '5350513667144163474', '👀': '5357121491508928442', '\U0001fae6': '5357185426392096577', '🍓': '5310157398516703416', '💄': '5310262535021142850', '👠': '5368741306484925109', '✈️': '5348436127038579546', '\U0001f9f3': '5357120306097956843', '🏖': '5310303848311562896', '⛅️': '5350424168615649565', '🦄': '5413625003218313783', '🛍': '5350699789551935589', '👜': '5377478880577724584', '🛒': '5431492767249342908', '🚂': '5350497316203668441', '🛥': '5350422527938141909', '🏔': '5418196338774907917', '🏕': '5350648297189023928', '🤖': '5309832892262654231', '\U0001faa9': '5350751634102166060', '🎟': '5377624166436445368', '🏴\u200d☠️': '5386395194029515402', '🗳': '5350387571199319521', '🎓': '5357419403325481346', '🔭': '5368585403467048206', '🔬': '5377580546748588396', '🎶': '5377317729109811382', '🎤': '5382003830487523366', '🕺': '5357298525765902091', '💃': '5357370526597653193', '\U0001fa96': '5357188789351490453', '💼': '5348227245599105972', '\U0001f9ea': '5411138633765757782', '👨\u200d👩\u200d👧\u200d👦': '5386435923204382258', '👶': '5377675010259297233', '🤰': '5386609083400856174', '💅': '5368808634392257474', '🏛': '5350548830041415279', '\U0001f9ee': '5355127101970194557', '🖨': '5386379624773066504', '👮\u200d♂️': '5377494501373780436', '\U0001fa7a': '5350307998340226571', '💊': '5310094636159607472', '💉': '5310139157790596888', '\U0001f9fc': '5377468357907849200', '\U0001faaa': '5418115271267197333', '🛃': '5370947704199323325', '🍽': '5350344462612570293', '🐟': '5384574037701696503', '🎨': '5310039132297242441', '🎭': '5350658016700013471', '🎩': '5357504778685392027', '🔮': '5350367161514732241', '🍹': '5350520238444126134', '🎂': '5310132165583840589', '☕️': '5350392020785437399', '🍣': '5350406176997646350', '🍔': '5350403544182694064', '🍕': '5350444672789519765', '\U0001f9a0': '5312424913615723286', '💬': '5417915203100613993', '🎄': '5312054580060625569', '🎃': '5309744892677727325'}

</details>

<details>

<summary>Exemplo de código para copiar</summary>

```
answer = tg_get_forum_icon()
```

</details>


---

# 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/api/chat.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.