# Botões do Telegram para chatbots

{% hint style="info" %}
Recomendamos que você leia o artigo [Botão](/doc/pt/chatbot/builder/botoes.md#how-to-create-a-button).
{% endhint %}

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

{% hint style="info" %}
**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 personalizado.** Os botões usam o estilo padrão da plataforma.
  {% endhint %}

## Como criar um botão no bloco

Para criar qualquer botão em um chatbot, vá às configurações do bloco e clique em **"Botões"** :

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

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

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

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

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

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

* **Botão de compartilhamento** – permite que os usuários compartilhem conteúdo.
* **Botão de retorno de chamada** – envia uma consulta de callback silenciosa para o seu bot.
* **Telegram WebApp** – abre uma miniaplicação (por exemplo, um widget ou site) dentro do Telegram.
* **Login do Telegram** – autoriza os usuários por meio da conta do Telegram.

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

Também há outros botões disponíveis no Telegram, como pagamento, solicitação de número de telefone ou geolocalização, e envio de link.

### Botão de compartilhamento

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

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

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

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

Insira a URL que você deseja compartilhar no **"Link para compartilhar"** .

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

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

do botão. **"Link para compartilhar"** e **"Texto adicional"** Depois que um contato for selecionado, o conteúdo dos campos será enviado. Use isso para compartilhar links de publicações de canais do Telegram e outros conteúdos.

{% hint style="info" %}
Atenção! Pode não funcionar corretamente em alguns dispositivos iOS.
{% endhint %}

### 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. Essa configuração é feita por meio de **@BotFather**.

**Passos para configurar:**

1. Abra uma conversa com [@BotFather](https://t.me/botfather).
2. Selecione seu bot na lista.
3. Escolha **Configurações do Bot** > **Domínio** e adicione o domínio do seu site.

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

Em seguida, vá para a **Domínio** botão:

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

**Observação:** O botão exibirá **Editar domínio** se já existir um domínio, ou **Definir domínio** se for necessário adicionar um.

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

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

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

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

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

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

Na **Texto** campo, 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 acontecerá.

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

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 esse bot): em particular, você precisará especificar o nome do bot.

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

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

Botão de login do Telegram

### Botão de retorno de chamada

O botão de callback é um botão de retorno em que o cliente vê uma coisa, e no bot recebemos o callback que precisamos para iniciar qualquer bloco do funil.

É bem simples criá-lo: no campo **Botões** clique no botão **Adicionar** Na janela que abrir, digite o texto, especifique o tipo - Botão de Callback (Telegram) e insira o **Texto do callback** que deve ser retornado quando você clicar no botão:

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

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

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

Depois de clicar no botão, você verá o **Callback** configurado no cartão do cliente:

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

{% hint style="info" %}
É importante!

O Telegram não suporta botões de teclado com Callback.
{% endhint %}

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

Se o **tipo de botão "Callback"** é selecionado, o botão será exibido como callback somente se o texto do botão for diferente do texto do callback.
{% endhint %}

### Botão de Aplicativo Web do Telegram

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

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

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 aplicativo web:

* Você pode especificar um link por meio de uma variável:

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

Usar uma variável para um link é muito 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. Faça referência a essa variável (por exemplo, `#{landing_page_url}`) em todos os botões 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.

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

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

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

**Método: use código gerado**

Você pode utilizar o **código de botão pré-gerado** nas 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 o **Botões** seção.
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.

Essa abordagem permite criar teclados complexos visualmente, enquanto a plataforma cuida da implementação técnica subjacente.

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

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

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

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

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

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 dos botões para a função no parâmetro reply\_markup:

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

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

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

## 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 os botões de resposta que permanecerem, insira o seguinte código no **Configurações Avançadas** “Broadcast para clientes dos blocos”

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

Essa configuração vazia de botões instrui o Telegram a ocultar o teclado personalizado.

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

### Botões de menu de teclado no Telegram

{% hint style="warning" %}
Recomendamos usar este recurso apenas para usuários avançados!
{% endhint %}

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

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

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

#### **Variável: `tg_permanent_reply_buttons`**

Definir a variável **`tg_permanent_reply_buttons`** lhe dá **controle manual total** sobre a visibilidade do teclado de resposta (botões abaixo da mensagem). Todo o comportamento de ocultação automática da plataforma é desativado.

**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 criados originalmente enquanto a variável estava ativa. Botões criados sob a regra "permanente" mantêm esse estado e precisam ser recriados para herdar o novo comportamento automático.

## Como criar um menu no Telegram

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

Quem criou o bot do Telegram pode fazer esse menu.

Para isso, escreva para [Botfather](https://t.me/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 **Editar Bot**, e depois **Editar Comandos**.

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

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

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

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

Agora você pode ver e usar o menu na sua conversa do Telegram com o bot.

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

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

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

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

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

Exemplo:

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

## Como combinar dois tipos de botões

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

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

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

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

Aqui está o resultado:

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

{% hint style="success" %}
**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 essa sequência for invertida, os botões de resposta serão removidos quando o próximo bloco de mensagem for enviado.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

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

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

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

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

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