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
Descrição

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

Descrição

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
Descrição

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 :

  1. is_anonymous — oculta a presença do administrador no chat,
  2. 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
  3. can_post_messages — o administrador pode criar postagens no canal (apenas canais)
  4. can_edit_messages — o administrador pode editar mensagens de outros usuários e fixar mensagens (apenas canais)
  5. can_delete_messages — o administrador pode excluir mensagens de outros usuários
  6. can_manage_video_chats — o administrador pode gerenciar videochats,
  7. can_restrict_members — o administrador pode restringir membros, banir/desbanir no chat,
  8. 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)
  9. can_change_info — o administrador pode alterar o título, 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 (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

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

  2. 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!

  1. 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()