Trabalhando com IDs de plataforma no MaviBot
No MaviBot, todas as entidades do Telegram (usuários, grupos, canais) são identificadas por uma variável genérica platform_id. Esta variável não distingue entre tipos de entidade.
Problema: Para usar funções como accept ou reject que exigem tipos de entidade específicos, você precisa saber o ID do chat e o ID do usuário separadamente.
Solução: Ao receber um callback ou mensagem, armazene imediatamente o valor de platform_id em duas variáveis distintas com nomes específicos:
-
chat_id– para armazenar o ID do grupo/canal. -
user_id– para armazenar o ID do usuário individual.
Isso permite que você referencie o ID correto posteriormente na lógica da sua aplicação.
Como alterar o nome do chat via bot do Telegram
Descrição
tg_set_group_title(platform_id, title)
Altera o título de um grupo do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat dentro do Telegram. |
| title | Novo nome do chat. |
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | o ID do chat dentro do Telegram * |
| **!** title | novo nome do chat |
Como alterar a descrição do chat via bot do Telegram
Descrição
tg_set_chat_description(platform_id, description)
Altera a descrição de um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat dentro do Telegram. |
| description | Nova descrição do chat. |
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | o ID do chat dentro do Telegram * |
| **!** description | novo nome do chat |
Como definir um avatar em um grupo/chat no Telegram
Descrição
tg_set_chat_photo(platform_id, photo)
Define uma nova foto de perfil para um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat dentro do Telegram onde você deseja definir uma nova foto de perfil. |
| photo | Link direto para a foto. |
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat dentro do Telegram *, no qual você deseja definir um avatar |
| **!** photo | link da foto |
Como excluir um avatar em um grupo/chat no Telegram
Descrição
tg_delete_chat_photo(platform_id)
Remove a foto de perfil atual de um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat dentro do Telegram do qual você deseja remover a foto de perfil. |
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat dentro do Telegram *, no qual você precisa definir um avatar |
Como banir um grupo do Telegram
Descrição
tg_ban_chat_sender_chat(platform_id, sender_chat_id)
Bane um chat remetente de postar mensagens em um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat do Telegram onde o chat remetente será banido. |
| sender_chat_id | O ID do chat remetente a ser banido. |
Nota
Uma vez banido, o proprietário do chat remetente não poderá mais postar mensagens em nome desse chat no chat do Telegram especificado até que o banimento seja removido.
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat dentro do Telegram *, que você precisa banir |
| **!** sender_chat_id | ID do chat que será banido |
Ao mesmo tempo, o proprietário do chat banido não pode escrever em nome de seus outros chats até que seja banido.
Como desbloquear um grupo do Telegram
Descrição
tg_unban_chat_sender_chat(platform_id, sender_chat_id)
Desbane um chat remetente previamente banido em um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat do Telegram onde o chat remetente será desbanido. |
| sender_chat_id | O ID do chat remetente a ser desbanido. |
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat dentro do Telegram *, no qual você desbloqueia |
| **!** sender_chat_id | ID do chat que você desbloqueia |
Como criar um link de convite para entrar no chat do Telegram
Descrição
tg_create_chat_invite_link(platform_id, member_limit, hours, request, name)
Cria um novo link de convite para um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat do Telegram. |
| member_limit | Número máximo de usuários que podem entrar usando este link de convite. |
| hours | Tempo de expiração do link de convite, em horas. |
| request | Se definido como True, os usuários que clicarem no link devem enviar uma solicitação de entrada que um administrador pode aprovar. |
| name | Nome personalizado para o link de convite. |
Importante
Se o parâmetro member_limit for especificado, o parâmetro request é automaticamente definido como
False.Para exigir que os usuários enviem solicitações de entrada, deixe o parâmetro member_limit vazio.
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| member_limit | limite no número de participantes |
| hours | Tempo de expiração do link (em horas) |
| request | um parâmetro que, após clicar no link, uma solicitação para entrar no chat deve ser gerada. |
| name | nome do link |
Ao passar o parâmetro member_limit, o valor do parâmetro request é automaticamente alterado para False. Se você precisar aceitar solicitações de adesão, deixe o parâmetro member_limit vazio.
Criando link de convite do chat

Como excluir link de convite do chat no Telegram
Descrição
tg_revoke_chat_invite_link(platform_id, invite_link)
Revoga um link de convite existente para um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat do Telegram. |
| invite_link | O link de convite a ser revogado. |
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat dentro do Telegram * |
| **!** invite_link | link que você precisa excluir |
Como inativar todos os links existentes e substituí-los por um link
Descrição
tg_export_chat_link(platform_id)
Cria um novo link de convite principal para um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat do Telegram. |
Aviso
Este método gera um novo link de convite principal para o chat.
Todos os links de convite principais gerados anteriormente se tornarão inativos. O link recém-gerado será o único link de convite principal ativo até que links de convite adicionais sejam criados.
Use este método com cautela.
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat dentro do Telegram * |
| **!** invite_link | link que você precisa excluir |
Como aceitar solicitação e adicionar usuário no canal/chat do Telegram
Descrição
tg_approve_chat_join_request(chat_id, user_id)
Aprova uma solicitação de entrada pendente para um grupo ou canal do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| chat_id | O ID do grupo ou canal do Telegram. |
| user_id | O ID do usuário do Telegram cuja solicitação de entrada deve ser aprovada. |
| **!** chat_id | ID do grupo/canal dentro do Telegram * |
| **!** user_id | ID do usuário dentro do Telegram * |
Aceitação da solicitação:

Como recusar solicitação no canal/chat do Telegram
Descrição
tg_decline_chat_join_request(chat_id, user_id)
Recusa uma solicitação de entrada pendente para um grupo ou canal do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| chat_id | O ID do grupo ou canal do Telegram. |
| user_id | O ID do usuário do Telegram cuja solicitação de entrada deve ser recusada. |
| **!** chat_id | ID do grupo/canal dentro do Telegram * |
| **!** user_id | ID do usuário dentro do Telegram * |

Como bloquear usuário no Telegram
Descrição
tg_ban_chat_member(chat_id, user_id, hours)
Bane um usuário de um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| chat_id | O ID do chat do Telegram. |
| user_id | O ID do usuário do Telegram a ser banido. |
| hours | Duração do banimento, em horas. Se omitido, o banimento é permanente. |
Nota
Se o valor de hours exceder 366 dias, o usuário será banido permanentemente.
| Parâmetro | Descrição |
|---|---|
| **!** chat_id | ID do chat no Telegram * |
| **!** user_id | ID do usuário no Telegram * para bloqueio |
| hours | 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. |
Como desbloquear usuário no Telegram
Descrição
tg_unban_chat_member(chat_id, user_id)
Desbloqueia um usuário de um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| chat_id | O ID do chat do Telegram. |
| user_id | O ID do usuário do Telegram a ser desbloqueado. |
| Parâmetro | Descrição |
|---|---|
| **!** chat_id | ID do chat no Telegram * |
| **!** user_id | ID do usuário no Telegram *, que você precisa desbloquear |
Como verificar o status de assinatura no Telegram
Descrição
tg_get_chat_member(chat_id, user_id)
Recupera informações sobre o status de associação de um usuário em um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| chat_id | O ID do chat do Telegram. |
| user_id | O ID do usuário do Telegram cujo status de associação será verificado. |
| Parâmetro | Descrição |
|---|---|
| **!** chat_id | ID do chat no Telegram * |
| **!** user_id | ID do usuário no Telegram *, cuja assinatura estamos verificando |
Como determinar o número de membros no canal/chat
Descrição
tg_get_chat_member_count(platform_id)
Retorna o número total de membros em um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat do Telegram. |
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
Como verificar se um membro do chat está em uma lista específica
some_client_in_list(list_id, recepient)
Verifica se um usuário do Telegram está incluído na lista especificada.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| list_id | O ID da lista a ser verificada. |
| recepient | O ID do usuário do Telegram. Para membros do chat, use a variável chat_member_id. |
| Parâmetro | Descrição |
|---|---|
| **!** list_id | número da lista |
| **!** recepient | ID do usuário no Telegram *. Para clientes de chat, este valor está na variável chat_member_id. |
Como mostrar as ações do bot ao usuário (digitar/selecionar um sticker, etc.)
Descrição
tg_send_chat_action(platform_id, bot_action, message_thread_id)
Envia uma ação de chat (como digitar ou enviar um arquivo) para um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat do Telegram. |
| bot_action | A ação de chat a ser exibida. Escolha uma das ações de chat suportadas pelo Telegram. |
| message_thread_id | O ID do tópico. Disponível apenas para supergrupos com Tópicos (Fóruns) ativados. |
Nota
Esta função é suportada ao trabalhar com contas Telegram Business.
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** bot_action | ação do bot da lista |
| message_thread_id | ID do tópico (disponível para supergrupos se a funcionalidade de fórum estiver disponível). |
**Lista de ações disponíveis bot_action**
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 notas 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 nota de vídeo.
Esta notificação será exibida até que qualquer resposta seja recebida do bot, mas não mais que 5 segundos.
Como mostrar notificação de Alerta ao usuário
Descrição
tg_answer_callback_query(callback_query_id, text, show_alert, cache_time)
Envia uma resposta a uma consulta de callback acionada quando um usuário clica em um botão inline no Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| callback_query_id | O ID da consulta de callback recebido quando o usuário clica em um botão inline. Isso identifica qual callback responder. |
| text | O texto a ser exibido na notificação. |
| show_alert | Controla como a notificação é exibida. Defina como False para mostrar uma notificação temporária no estilo tooltip, ou True para exibir uma caixa de diálogo de alerta persistente. |
| cache_time | O tempo máximo, em segundos, que a resposta do callback pode ser armazenada em cache no lado do cliente. O padrão é 0. Os clientes Telegram suportam cache a partir da versão 3.14. |
Importante
Esta função só pode ser usada em resposta a um usuário clicando em um botão de callback inline no Telegram.
Exemplo
O seguinte teclado inline envia diferentes valores de callback quando cada botão é clicado:
[{"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"}]

Após clicar em um botão, um callback chega com o texto contido no campo correspondente. Quando você clica no botão “111”, receberá um callback com o texto “first”.

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

Se no campo Correspondências você selecionar Ignorar erros e imprecisões, este bloco pode 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 tal botão.
Em seguida, na calculadora, use a função tg_answer_callback_query e passe os seguintes parâmetros:
callback_query_id - este ID permite identificar o usuário que pressionou o botão e exibir uma notificação de Alerta para ele
text - texto da notificação de Alerta.

Exemplo de código para copiar:
tg_answer_callback_query('#{callback_query_id}', "Você pressionou o botão 111")
Preste atenção! O parâmetro callback_query_id deve ser passado exatamente como mostrado no exemplo, ou seja, dentro de '#{}'
Se tudo estiver configurado corretamente, pressionar o botão resultará em uma notificação de Alerta com o texto especificado. Na versão móvel, o nome do bot aparecerá como cabeçalho acima do texto.

Se você quiser mostrar uma mensagem popup simples, passe False como o terceiro parâmetro, conforme mostrado no exemplo abaixo:
tg_answer_callback_query('#{callback_query_id}', "Você passou o botão 222", False)

Adicionando um redirecionamento do bot com uma tag como resposta do botão de callback
Descrição
tg_callback_url_open(callback_query_id, url, cache_time)
Abre um bot do Telegram usando um link profundo em resposta a um callback de botão inline.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| callback_query_id | O ID da consulta de callback recebido quando o usuário clica em um botão inline. Isso identifica qual callback responder. |
| url | Um link profundo para o bot no formato https://t.me/your_bot?start=XXXX, onde your_bot é o nome de usuário do bot e XXXX é o parâmetro de início. |
| cache_time | O tempo máximo, em segundos, que a resposta do callback pode ser armazenada em cache no lado do cliente. O padrão é 0. Os clientes Telegram suportam cache a partir da versão 3.14. |
Importante
Esta função só pode ser usada em resposta a um usuário clicando em um botão de callback inline no Telegram.
Exemplo
Na resposta do botão de callback, você pode adicionar uma transição para o bot usando a tag tg_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"}]

Após clicar em um botão, um callback chega com o texto contido no campo correspondente. Quando você clica no botão “111”, receberá um callback com o texto “first”.

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

Se no campo Opção de correspondência você selecionar Ignorar erros e imprecisões, este bloco pode 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 tal botão.
Em seguida, na calculadora do bloco, especifique tg_callback_url_open('#{callback_query_id}', 't.me/bot_name?start=XXXX'):

Como promover um usuário a administrador em um supergrupo ou canal
Descrição
tg_promote_user(platform_id, user_id, promote_options_list)
Promove um usuário do Telegram a administrador em um supergrupo ou canal com as permissões especificadas.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O identificador do supergrupo do Telegram, ou o nome de usuário do canal no formato @channelusername ao promover um usuário em um canal. |
| user_id | O ID do usuário do Telegram a ser promovido. |
| promote_options_list | Uma lista de permissões de administrador a serem concedidas ao usuário. |
Nota
Apenas as permissões incluídas em promote_options_list serão concedidas ao usuário.
**Parâmetro obrigatório: promote_options_list**
As seguintes permissões podem ser especificadas em promote_options_list :
- is_anonymous — oculta a presença do administrador no chat,
- can_manage_chat — o administrador pode acessar o registro 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 ignorar o modo lento. Este nível de permissão é concedido por padrão se algum dos privilégios subsequentes for especificado
- can_post_messages — o administrador pode criar postagens no canal (apenas canais)
- can_edit_messages — o administrador pode editar mensagens de outros usuários e fixar mensagens (apenas canais)
- can_delete_messages — o administrador pode excluir mensagens de outros usuários
- can_manage_video_chats — o administrador pode gerenciar videochats,
- can_restrict_members — o administrador pode restringir membros, banir/desbanir no chat,
- can_promote_members — o administrador pode nomear novos administradores com um subconjunto de seus próprios privilégios, ou rebaixar administradores que nomeou direta ou indiretamente (por exemplo, administradores nomeados por ele)
- can_change_info — o administrador pode alterar o título, foto e outras configurações do chat
- can_invite_users — o administrador pode convidar novos usuários para o chat
- can_pin_messages — o administrador pode fixar mensagens (apenas supergrupos).
Exemplo
Exemplo: Promovendo um usuário a administrador em um supergrupo:

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


Exemplo de código para copiar
Exemplo 1.
promote_options_list = '["can_promote_members","can_change_info","can_invite_users"]'
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)
Como alterar um título de administrador usando um bot no Telegram
Descrição
tg_set_administrator_title(platform_id, user_id, title)
Define um título de administrador personalizado para um administrador de supergrupo do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do supergrupo do Telegram. |
| user_id | O ID do usuário do Telegram do administrador. |
| title | O título personalizado do administrador. |
Importante
- O título deve ter entre 0 e 16 caracteres de comprimento.
- Emojis não são permitidos no título.
- Esta função funciona apenas para administradores que foram promovidos pelo bot.
Exemplo
result = tg_set_administrator_title(platform_id, reply_from, "firetitle")
Restrições gerais para membros comuns do chat ou usuários específicos do Telegram
Descrição
tg_chat_permission(platform_id, permission, media_permissions)
Define as permissões padrão para membros em um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat do Telegram. |
| permission | Um array de permissões gerais do chat. Cada elemento corresponde a uma permissão na lista de permissões suportadas. Use 1 para permitir a ação e 0 para proibi-la. |
| media_permissions | Um array de permissões relacionadas a mídia. Cada elemento corresponde a uma permissão na lista de permissões de mídia suportadas. Use 1 para permitir a ação e 0 para proibi-la. |
Nota
A ordem dos valores em ambos os arrays deve corresponder à ordem das listas de permissões correspondentes. Cada elemento do array controla uma permissão específica:
1— Permissão concedida.0— Permissão negada.
Lista de restrições para o parâmetro obrigatório **permission**
Lista de restrições para permission:
1. ! can_send_messages - permissão para enviar mensagens de texto, contatos, localizações e locais.
2. ! can_send_media_messages - permissão para enviar áudio, documentos, fotos, vídeos, notas de vídeo e notas de voz. Requer can_send_messages
3. ! can_send_polls - permissão para enviar enquetes. Requer can_send_messages
4. ! can_send_other_messages - permissão para enviar animações, jogos, adesivos e usar bots inline. Requer can_send_media_messages
5. ! can_add_web_page_previews - permissão para adicionar pré-visualizações de páginas da web a mensagens. Requer can_send_media_messages
6. ! can_change_info - permissão para alterar o título, foto e outras configurações do chat. Isso é ignorado em supergrupos públicos.
7. ! can_invite_users - permissão para convidar usuários
8. ! 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 usado em um grupo do tipo errado, a função falhará e retornará um erro.
Lista de valores para o parâmetro obrigatório **media_permissions**
Valores para conceder permissões relacionadas a mídia media_permissions:
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
Restrições pessoais do Telegram para usuários regulares do chat ou para usuários específicos do Telegram
Descrição
tg_restrict_chat_member(platform_id, user_id, minutes, permission, media_permissions).
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| ! platform_id | ID do chat no Telegram * |
| ! user_id | ID do usuário no Telegram * |
| minutes | o número de minutos durante os quais a restrição permanecerá ativa. Se você não definir um valor, o padrão é 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. |
| media_permissions | uma lista de valores para conceder permissões relacionadas a mídia |
Lista de restrições para o parâmetro obrigatório **permission**
Lista de restrições para permission:
1. ! can_send_messages - permissão para enviar mensagens de texto, contatos, localizações e locais.
2. ! can_send_media_messages - permissão para enviar áudio, documentos, fotos, vídeos, notas de vídeo e notas de voz. Requer can_send_messages
3. ! can_send_polls - permissão para enviar enquetes. Requer can_send_messages
4. ! can_send_other_messages - permissão para enviar animações, jogos, adesivos e usar bots inline. Requer can_send_media_messages
5. ! can_add_web_page_previews - permissão para adicionar pré-visualizações de páginas da web a mensagens. Requer can_send_media_messages
6. ! can_change_info - permissão para alterar o título, foto e outras configurações do chat. Isso é ignorado em supergrupos públicos.
7. ! can_invite_users - permissão para convidar usuários
8. ! 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 usado em um grupo do tipo errado, a função falhará e retornará um erro.
Lista de valores para o parâmetro obrigatório **media_permissions**
Valores para conceder permissões relacionadas a mídia media_permissions:
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
Exemplo
Exemplo de uso da função, onde o usuário é restrito de tudo por 3 minutos:

Quando o usuário entra no chat, verá uma notificação de 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.

Exemplo de código para copiar:
permission = [0, 0, 0, 0, 0, 0, 0, 0]
tg_restrict_chat_member(-1001607137668, 473737685, 3, permission)
Como fixar mensagem
Descrição
tg_pin_chat_message(platform_id, message_id, disable_notification)
Fixa uma mensagem em um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat do Telegram. |
| message_id | O ID da mensagem a ser fixada. |
| disable_notification | Controla se os membros do chat são notificados sobre a mensagem fixada. Defina como 1 para fixar a mensagem silenciosamente, ou 0 para enviar uma notificação. |
Nota
As notificações estão sempre desabilitadas em canais e chats privados, independentemente do valor de disable_notification.
Como desafixar mensagem
Descrição
tg_unpin_chat_message(platform_id, message_id)
Desfixa uma mensagem em um chat do Telegram.
Parâmetros
| Parâmetro | Descrição |
|---|---|
| platform_id | O ID do chat do Telegram. |
| message_id | O ID da mensagem a ser desafixada. Se omitido, a mensagem fixada mais recentemente é desafixada. |
Nota
Se message_id não for especificado, a função desafixa a mensagem fixada mais recente com base no seu horário de envio.
Como desafixar todas as mensagens fixadas
Descrição
tg_unpin_all(platform_id)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
ATENÇÃO!
O Telegram tem uma limitação para as funções de fixar/desafixar mensagens.
Os limites de tempo para usar **tg_pin_chat_message / tg_unpin_chat_message / tg_unpin_all **NÃO são definidos pelo sistema MaviBot.
Se o tempo permitido para fixar uma mensagem tiver passado, a função ainda retornará true, mas o Telegram não aplicará a alteração.
Também é importante notar que as mensagens fixadas podem permanecer em cache, então podem não desaparecer visualmente imediatamente.
Como criar uma enquete no Telegram
Descrição
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:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** question | pergunta |
| **!** options | um array de opções de resposta |
| is_anonymous | 1 - enquete anônima , '' - não anônima |
| allows_multiple_answers | 1 - múltiplas respostas disponíveis, '' - uma resposta |
| reply_markup | teclado ou '' - sem teclado |
| disable_notification | flag para envio com notificação sonora (padrão 0) 1 – desabilitar notificação ao receber, 0 – enviar com notificação |
| protect_content | 1 para proteger contra cópia e capturas de tela, '' sem proteção |
| token | token do bot; se não fornecido, o atual é usado |
| reply_to_message_id | ID da mensagem citada |
| message_thread_id | ID do tópico (disponível para supergrupos se a funcionalidade de fórum existir) |
| business_connection_id | valor ao conectar um bot (Business ID). Mostra em canais. Deve ser fornecido se o token do bot for usado e a mensagem precisar ser enviada através de uma conta de usuário conectada ao bot |
Importante saber!
Notas
-
A função retorna uma resposta do Telegram com message_id. É melhor salvá-lo. Usando message_id, você pode parar a enquete com tg_stop_poll (veja a descrição abaixo) e obter o resultado.
-
Se um usuário adicionar uma enquete em um mensageiro, um callback é enviado para o chat:
poll_added - parte imutável
YOUR QUESTION - texto da pergunta da enquete

Exemplo de callback ao adicionar enquete em um canal

Exemplo de callback ao adicionar enquete em um chat

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.
Ao criar uma enquete pelo bot, o callback não chega.
3. Em um canal, só é possível criar enquetes anônimas
Atenção, recomenda-se enviar apenas enquetes anônimas para o grupo!
- Após criar a enquete, salve seu identificador em uma variável para saber a qual enquete o callback se refere.
Exemplo
O feedback do cliente é fundamental para o nosso crescimento. As enquetes oferecem um método direto para capturar esse feedback e traduzi-lo em conclusões comerciais 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, 'What is your favorite color?', options, 1, '', '', 1, '')
Função para criar uma enquete no Telegram:

A enquete que criamos no Telegram

Como criar um quiz no Telegram
Descrição
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:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** question | pergunta |
| **!** options | um array de opções de resposta |
| **!** explanation | texto exibido quando um usuário seleciona uma resposta errada ou clica no ícone da lâmpada em uma enquete estilo quiz, 0–200 caracteres com no máximo duas quebras de linha após a análise da entidade. |
| **!** correct_option_id | número da resposta correta, numeração a partir de 1 |
| is_anonymous | 1 - enquete anônima , '' - não anônima |
| reply_markup | teclado ou '' - sem teclado |
| parse_mode | formato da explicação: markdown, html, ou '' (string vazia para sem formatação) |
| protect_content | 1 para proteger contra cópia e capturas de tela, '' sem proteção |
| disable_notification | flag para envio com notificação sonora (padrão 0) 1 – desabilitar notificação ao receber, 0 – enviar com notificação |
| token | token do bot; se não fornecido, o atual é usado |
| reply_to_message_id | ID da mensagem citada |
| message_thread_id | ID do tópico (disponível em supergrupos com funcionalidades de fórum ativas) |
**Importante saber!**
Notas
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 função
tg_stop_poll(veja a descrição abaixo). - Recuperar os resultados finais.
2. Callback poll_added
Se um usuário adicionar uma enquete a um canal, o bot recebe um callback:
-
Formato:
poll_added+ Pergunta da enquete - Se adicionado a um chat de grupo: o callback também inclui o ID do Usuário do Telegram da pessoa que adicionou a enquete.
Se criado pelo bot: Nenhum callback
poll_addedé enviado.
3. Restrição de canal
Apenas quizzes anônimos podem ser criados em canais.
4. Callback poll_answer (Votação do usuário)
Quando um usuário vota em um quiz enviado para um chat privado ou grupo, um callback é enviado para o diálogo do bot com aquele cliente:
-
Formato:
poll_answer+ ID da enquete + [Índice da resposta] -
Exemplo:
poll_answer 5325838371359031648 [3] -
Nota: 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 de grupo não anônimas
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 callback poll_answer (como no ponto 4) para seu diálogo 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 entrou em contato com o bot, você não pode enviar a ele uma mensagem direta em resposta ao seu voto até que ele ative o bot primeiro (por exemplo, enviando um comando
/start).
Recomendação: para evitar essa limitação, é altamente recomendado enviar apenas quizzes anônimos para grupos.
7. Acompanhe suas enquetes
Imediatamente após criar um quiz, salve seu ID de enquete único em uma variável. Isso permite identificar a qual enquete específica um callback recebido se refere.
Exemplo
Exemplo de código para copiar.
options = ["white", "red", "blue", "green"]
r = tg_send_quiz_poll(platform_id, "What color is a crocodile?", options, "That is the explanation", 4, '', '', '', '', 1)
Exemplo: criação de quiz.

Como encerrar uma enquete
Descrição
tg_stop_poll(platform_id, message_id)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** message_id | ID da mensagem da enquete/quiz. Pode ser obtido do webhook |
Chamar esta função para encerrar uma enquete/quiz retorna um dicionário contendo os resultados finais.
Como trabalhar com tópicos no Telegram
Importante: o tópico principal do grupo não tem um ID e requer funções separadas para trabalhar com ele.
Como renomear o Tópico Geral do grupo
Descrição
tg_edit_general_forum_topic(platform_id, topic_name)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** topic_name | novo nome do tópico |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usar vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
Exemplo
O Tópico Geral dos grupos pode ser alterado usando a função tg_edit_general_forum_topic(). Ela requer dois parâmetros obrigatórios: o ID do chat e o novo nome para o Tópico do Grupo:

Exemplo de código para copiar
renomear o chat do Tópico Geral/
answer = tg_edit_general_forum_topic(-1001839380031, 'Geral')
Como fechar o Tópico Geral
Descrição
tg_close_general_forum_topic(platform_id)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usa vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
Exemplo de código para copiar
/fechar o chat do Tópico Geral/
answer = tg_close_general_forum_topic(-1001839380031)
Como reabrir um Tópico Geral previamente fechado
Descrição
tg_reopen_general_forum_topic(platform_id)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usa vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
Exemplo de código para copiar
/reabrir o chat do Tópico Geral/
answer = tg_reopen_general_forum_topic(-1001839380031)
Como ocultar o Tópico Geral
Descrição
tg_hide_general_forum_topic(platform_id)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usa vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
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.
Exemplo de código para copiar
/ocultar o chat do Tópico Geral/
answer = tg_hide_general_forum_topic(-1001839380031)
Como exibir o Tópico Geral ou restaurar sua visibilidade
Descrição
tg_unhide_general_forum_topic(platform_id)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do tópico no Telegram * |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usa vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
**Importante! **
Esta função não reabre o Tópico Geral; ela apenas o torna visível.
Exemplo de código para copiar
/exibir o chat do Tópico Geral/
answer = tg_unhide_general_forum_topic(-1001839380031)
Como criar um novo tópico no Telegram
Descrição
tg_create_forum_topic(platform_id, name, icon, icon_color)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** name | nome do novo tópico |
| icon | ID do emoji a ser definido para o tópico. Passado como uma string. Você só pode usar emojis da lista recuperada pela função tg_get_forum_icon. |
| icon_color | cor do emoji da lista: 7322096, 16766590, 13338331, 9367192, 16749490, 16478047. Nem todos os emojis suportam alteração de cor. |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usa vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
A cor definida não pode ser alterada; a cor só pode ser atribuída ao criar o tópico.
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).
Exemplo de código para copiar
Para criar um chat de tópico adicional
answer = tg_create_forum_topic(-1001839380031, 'segundo_topico_bot', None, 7322096)
Para salvar o ID do chat de tópico adicional criado
answer={"ok":true,"result":{"message_thread_id":254,"name":"segundo_topico_bot","icon_color":7322096}}/
idtema1=answer['result']['message_thread_id']
Como editar um tópico. Como renomear e/ou alterar o emoji de um tópico
Descrição
tg_edit_forum_topic(platform_id, message_thread_id, name, icon)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** message_thread_id | ID do chat de tópico adicional |
| name | novo nome do tópico |
| icon | ID do emoji a ser definido para o tópico. Passado como uma string. Você só pode usar emojis da lista recuperada pela função tg_get_forum_icon. |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usa vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
Exemplo de código para copiar
answer = tg_edit_forum_topic(-1001839380031, 254)
Como fechar um tópico selecionado
Descrição
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)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** message_thread_id | ID do chat de tópico adicional |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usa vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
Exemplo de código para copiar
answer = tg_close_forum_topic(-1001839380031, 254)
Como reabrir um tópico previamente fechado
Descrição
tg_reopen_forum_topic(platform_id, message_thread_id)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** message_thread_id | ID do chat de tópico adicional |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usa vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
Exemplo de código para copiar
answer = tg_reopen_forum_topic(-1001839380031, 254)
Como excluir um tópico e todas as suas mensagens
Descrição
tg_delete_forum_topic(platform_id, message_thread_id)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** message_thread_id | ID do chat de tópico adicional |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usa vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
Exemplo de código para copiar
answer = tg_delete_forum_topic(-1001839380031, 254)
Como desafixar todas as mensagens em um tópico
Descrição
tg_unpin_topic_messages(platform_id, message_thread_id)
Parâmetros:
| Parâmetro | Descrição |
|---|---|
| **!** platform_id | ID do chat no Telegram * |
| **!** message_thread_id | ID do chat de tópico adicional |
| bot_name |
parâmetro opcional: nome do bot. Ao trabalhar com tópicos, você pode especificar qual bot deve executar a função. Isso é útil se seu projeto usa vários bots do Telegram. Encontre o nome do bot na seção "Canais", no campo "ID do Grupo". |
Exemplo de código para copiar
answer = tg_unpin_topic_messages(-1001839380031, 254)
Como obter a lista de emojis para um Tópico do Telegram
Descrição
Como obter a lista de emojis
tg_get_forum_icon() – esta função retorna uma lista de emojis disponíveis para uso como ícones de tópico do fórum. O resultado deve ser atribuído a uma variável, pois retorna um dicionário onde cada chave é um emoji e seu valor correspondente é o identificador único do emoji (id).
Parâmetros: nenhum.
O conteúdo da lista de emojis
Para obter a lista de emojis para um chat de Tópico, envie o comando para o chat relevante.
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'}
Exemplo de código para copiar
answer = tg_get_forum_icon()