Recomendamos que você leia o artigo Botão.

Você pode usar tanto botões de resposta (botões comuns ou de teclado) quanto botões Inline (botões no texto) no Telegram.

Importante: limitações dos botões

Esteja ciente das seguintes restrições da plataforma ao criar botões:

  • Botões de resposta (teclado): máximo de 12 botões por linha.
  • Botões Inline: máximo de 8 botões por linha.
  • Texto do botão: limitado a 32 caracteres.
  • Cor do botão: não pode ser personalizada. Os botões usam o estilo padrão da plataforma.

Como criar um botão no bloco

Para criar qualquer botão em um chatbot, vá para as configurações do bloco e clique na aba "Botões":

Em seguida, as configurações para adicionar e editar o botão serão abertas. Depois clique em Adicionar:

Uma janela de configurações será aberta, permitindo que você defina o rótulo, a ação e as opções adicionais do botão.

Os seguintes tipos de botão estão disponíveis apenas para o bot do Telegram:

  • Botão Compartilhar – permite que os usuários compartilhem conteúdo.
  • Botão Callback – envia uma consulta de callback silenciosa para o seu bot.
  • Telegram WebApp – abre um mini-aplicativo (por exemplo, um widget ou site) dentro do Telegram.
  • Login do Telegram – autoriza usuários através da conta do Telegram.

Existem também outros botões disponíveis no Telegram, como pagamento, solicitar número de telefone ou geolocalização e enviar um link.

Botão Compartilhar

Ao criar o botão, selecione "Compartilhar (apenas Telegram)" e preencha os campos (campo de texto adicional opcional):

Este botão permite encaminhar as informações selecionando um contato da sua lista.

Insira a URL que deseja compartilhar no campo "Link de compartilhamento" do botão.

Assim que um contato for selecionado, o conteúdo dos campos "Link de compartilhamento" e "Texto adicional" será enviado. Use isso para compartilhar links para postagens de canais do Telegram e outros conteúdos.

Atenção! Pode não funcionar corretamente em alguns dispositivos iOS.

Botão de login do site

Para que o botão de login funcione, seu bot deve primeiro ser autorizado para o domínio de destino. Esta configuração é feita através do @BotFather.

Passos para configurar:

  1. Abra um chat com @BotFather.
  2. Selecione seu bot na lista.
  3. Escolha Bot Settings > Domain e adicione o domínio do seu site.

Em seguida, vá para o botão Domain:

Nota: O botão exibirá Edit domain se um domínio existir, ou Set domain se um precisar ser adicionado.

Você será solicitado a configurar o domínio para o seu bot:

Formato correto do domínio:

Insira seu domínio como mavibot.ai ou como seudominio.com se você tiver um site conectado ao MaviBot.

Próximo passo:

Assim que seu domínio for verificado e configurado, você pode prosseguir para criar o botão de autorização.

No campo Texto, insira o rótulo que aparecerá no botão.

Em seguida, forneça a URL da página no campo Link onde a autorização ocorrerá.

Os campos restantes serão necessários se um bot separado for usado para autorização (você precisa obter permissão para enviar mensagens para este bot): em particular, você precisará especificar o nome do bot.

Se você precisar poder enviar mensagens do bot especificado, marque a caixa "Solicitar permissão ao usuário para enviar mensagens do bot":

Botão de login do Telegram

Botão Callback

O botão Callback é um botão de feedback onde o cliente vê uma coisa, e no bot recebemos o callback necessário para iniciar qualquer bloco do funil.

É bastante simples criá-lo: no campo Botões, clique no botão Adicionar. No formulário que abrir, insira o texto, especifique o tipo - Botão Callback (Telegram) e insira o Texto do Callback que deve retornar ao clicar no botão:

Visualmente, o botão parece um botão inline comum:

Após clicar no botão, você verá o Callback configurado no cartão do cliente:

É importante!

O Telegram não suporta botões de teclado Callback.

Por favor, note!

Se o tipo de botão "Callback" for selecionado, o botão será exibido como um callback apenas se o texto do botão for diferente do texto do callback.

Botão de Aplicativo Web do Telegram

Este botão permite abrir o site como um aplicativo web no Telegram.

Ao adicionar o botão, especifique seu rótulo, selecione o tipo de botão Telegram Web App e forneça o link para o site que será aberto como um aplicativo web:

  • Você pode especificar um link através de uma variável:

Usar uma variável para um link é altamente prático quando a página de destino ou o endereço do site muda com frequência.

Como funciona:

  1. Defina uma variável (por exemplo, landing_page_url) nas configurações do seu projeto.
  2. Referencie esta variável (por exemplo, #{landing_page_url}) em todos os botões do Web App em seus fluxos.

Benefício: em vez de atualizar manualmente a URL em cada bloco de botão individual, você só precisa alterar o valor da variável uma vez nas configurações do projeto, e todos os botões serão atualizados automaticamente.

Alternativa: você pode, claro, ainda especificar uma URL direta e estática diretamente nas configurações do botão.

Como criar botões para funções da API do Telegram

Embora trabalhar diretamente com a API do Bot do Telegram possa ser desafiador, especialmente para iniciantes, o MaviBot oferece uma alternativa muito mais acessível.

Método: usar código gerado

Você pode utilizar o código de botão pré-gerado das configurações avançadas, eliminando a necessidade de escrever chamadas de API manualmente.

Passos:

  1. Navegue até as configurações do seu bloco e abra a seção Botões.
  2. Use a interface para adicionar e configurar todos os botões necessários (texto, links, funções).
  3. O sistema gerará automaticamente o código correto da API do Telegram em segundo plano.

Esta abordagem permite criar teclados complexos visualmente enquanto a plataforma lida com a implementação técnica subjacente.

Clique em "Configurações Avançadas" para visualizar o código da API do Telegram gerado para seus botões.

Teste seus botões, depois copie o código gerado de Configurações Avançadas para uma variável como buttons.

Esta função envia uma mensagem via API do Telegram com os seguintes parâmetros: tg_send_message (platform_id, text,client_message_id, reply_markup, sparse_mode, disable_web_page_preview, protect_content, disable_notification, message_thread_id, entities):

Passe a variável buttons para a função no parâmetro reply_markup:

Seus botões aparecerão no chat com o layout e estilo que você definiu.

Como excluir botões de resposta

Embora os botões de teclado normalmente desapareçam automaticamente, às vezes eles podem permanecer visíveis.

Para limpar à força botões de resposta persistentes, insira o seguinte código no campo Configurações Avançadas:

[{"buttons":[],"one_time":true,"index_in_line":0,"line":0}]

Esta configuração de botão vazio instrui o Telegram a ocultar o teclado personalizado.

Botões de menu do teclado no Telegram

Recomendamos usar este recurso apenas para usuários avançados!

Botões de teclado

Para poder usar os botões de teclado (resposta) como um menu permanente do Telegram, basta atribuir qualquer valor à variável tg_permanent_reply_buttons (a variável é declarada como uma constante do projeto).

Variável: tg_permanent_reply_buttons

Definir a variável tg_permanent_reply_buttons oferece controle manual total sobre a visibilidade do teclado de resposta (botões abaixo da mensagem). Todo o comportamento automático de ocultação pela plataforma é desabilitado.

Escopo: esta configuração se aplica a todos os botões de resposta criados no bot enquanto a variável estiver ativa.

Revertendo para o comportamento automático

Para restaurar a ocultação automática padrão do teclado:

  1. Remova a variável tg_permanent_reply_buttons das configurações do seu projeto.
  2. Recrie quaisquer botões de resposta que foram originalmente feitos enquanto a variável estava ativa. Os botões criados sob a regra "permanente" retêm esse estado e devem ser recriados para herdar o novo comportamento automático.

Como criar um menu no Telegram

Quem criou o bot do Telegram pode fazer esse menu.

Para isso, escreva para Botfather no Telegram.

Digite o comando /mybots, e a lista dos seus bots será aberta. Escolha o que você precisa. Um menu será aberto para você. Aqui você precisa selecionar Edit Bot, e depois Edit Commands.

Insira todos os comandos e suas descrições em uma única mensagem, usando letras minúsculas para os nomes dos comandos. Você receberá uma confirmação quando a lista for atualizada.

Agora você pode ver e usar o menu no seu chat do Telegram com o bot.

Ao clicar no botão do menu, uma lista de comandos que foram previamente registrados no BotFather será aberta:

Em seguida, vá para o Mavibot, abra o projeto ao qual este bot do Telegram está conectado.

Crie os blocos Iniciar ou Gatilho, escreva comandos nas condições, e no campo "Texto da mensagem" — os textos que serão recebidos como resposta.

Exemplo:

Como combinar dois tipos de botões

Crie um bloco com um botão de resposta (teclado), que você precisa visualizar.

Crie o próximo bloco (um temporizador de 0 segundos) com botões inline (botões no texto), que devem ser colocados sem remover os botões de resposta. Por exemplo: [{"type": "inline", "text": "NOME DO BOTÃO", "line": 0, "index_in_line": 0}]

Aqui está o resultado:

Importante: você deve seguir esta ordem ao adicionar botões no mesmo bloco:

  1. Primeiro, adicione todos os botões de Resposta (teclado).
  2. Depois, adicione quaisquer botões Inline.

Se esta sequência for invertida, os botões de resposta serão removidos quando o próximo bloco de mensagem for enviado.