Base de conhecimento GetMyBot

Mensagens e botões

Monte a resposta do bot com texto, fotos e botões. Faça perguntas e salve as respostas dos clientes.

Nesta página

Para que o bot envie texto, uma foto e o botão «Escolher», adicione a ação Enviar mensagem. A resposta é montada com partes separadas, chamadas blocos. Você pode enviar primeiro a foto de um produto e depois uma descrição com botões abaixo dela. Esses botões também são chamados botões inline.

Na mesma ação, é possível fazer uma pergunta, esperar a resposta e guardá-la no perfil do cliente. A seguir, veja como configurar blocos, botões e perguntas.

Blocos da mensagem

Clique em Adicionar bloco e escolha o que enviar. Você pode combinar uma saudação em texto, uma foto e um arquivo com a programação de um curso.

  • Texto: texto formatado de até 4.096 caracteres, com substituições e botões.
  • Foto: imagem com legenda.
  • Arquivo: documento com legenda.
  • Mensagem de voz: áudio OGG/OPUS, MP3 ou M4A de até 50 MB, exibido como mensagem de voz no Telegram (sendVoice).
  • GIF: animação ou MP4 sem som, de até 50 MB (sendAnimation).
  • Vídeo circular: MP4 quadrado de até 60 segundos (sendVideoNote). Não tem legenda. A cada envio, o arquivo da biblioteca é carregado novamente: o Telegram não aceita em sendVoice, sendAnimation ou sendVideoNote um file_id obtido de outra forma.
  • Carrossel: de 2 a 10 cartões, cada um com foto, legenda e botões próprios. No Telegram, a pessoa pode navegar entre eles com «‹ ›» em uma única mensagem, atualizada com editMessageMedia, se houver um file_id adequado para todas as fotos. Esse ID pode estar no cartão ou ser obtido para um arquivo da biblioteca. Se faltar o ID de qualquer foto, todos os cartões serão enviados como fotos separadas. O mesmo acontece em outros canais, como o VK. Cada cartão mantém sua legenda e seus botões.
  • Atraso: espera alguns segundos antes de enviar o próximo bloco.
  • IA: resposta criada por um modelo a partir da instrução configurada.
  • Reação: inicia outra reação e pode esperar sua conclusão.

Mensagens de voz, GIFs, vídeos circulares e carrosséis funcionam nas reações como os demais blocos e também entram no envio rápido de uma reação. Veja Envios.

Você pode arrastar os blocos para mudar a ordem. Em Ordem dos blocos, escolha Em ordem ou Aleatória para variar as respostas. O menu principal do bot pode continuar como está, ser alterado ou ser ocultado.

Opções do bloco

Os blocos de texto e mídia oferecem opções para fixar, enviar sem som, impedir encaminhamento, ocultar como spoiler, não mostrar prévia de links e apagar automaticamente após alguns segundos.

Botões abaixo da mensagem

Em cada bloco, configure o texto e o tipo dos botões:

  • Texto: envia o texto do botão como uma resposta da pessoa. No Telegram e no VK, aparece como teclado de resposta; o clique pode responder a uma pergunta ou iniciar uma reação pelo texto. No WhatsApp, Instagram, Messenger e widget do site, aparece como botão de resposta sem teclado permanente.
  • Link: abre um endereço de site.
  • Aplicativo web: abre uma Mini App no Telegram. Veja Mini App.
  • Chamar reação: inicia outra reação ao clicar.
  • Consulta inline: coloca «@bot consulta» no campo de texto da conversa atual ou permite escolher outra conversa (switch_inline_query / switch_inline_query_current_chat). Só funciona no Telegram após ativar o modo inline no @BotFather com /setinline. O GetMyBot não responde a essas consultas (answerInlineQuery não está implementado): o botão prepara o texto, mas não faz uma busca.
  • Texto preparado: abre https://t.me/<bot>?text=…, com um texto pronto no campo de digitação. A pessoa ainda precisa enviá-lo (prefill).
  • Link de pagamento: abre uma URL de pagamento obrigatória. O pagamento é criado pela ação Criar pagamento. É uma página externa de pagamento, não uma cobrança nativa do Telegram.
  • Notificação: mostra um texto ao clicar, sem iniciar uma reação ou passar dados do botão (Carry). No Telegram, pode ser um aviso curto ou uma janela de até 200 caracteres. No VK, é uma faixa curta de até 90 caracteres, sem janela.

Resposta de texto ou texto preparado

O que você quer fazerTipo e configuraçãoO que acontece ao clicar
Responder «Sim» em um formulárioTexto, com «Sim» no botão; a mensagem deve estar esperando uma respostaA resposta «Sim» é enviada para a etapa do diálogo.
Preparar uma perguntaTexto preparado, com «Escrever» no botão e «Quero fazer um pedido» como texto preparadoO texto aparece no campo de digitação. A pessoa pode editá-lo e enviá-lo.

O texto visível no botão e o texto preparado são campos diferentes. O texto preparado não envia uma mensagem nem inicia uma reação sozinho.

O botão Chamar reação envia o clique ao bot como um evento chamado callback. Consulta inline e Texto preparado agem dentro do aplicativo Telegram e não enviam esse evento. Por isso, não admitem answerCallbackQuery nem os dados Carry.

Ícone e cor do botão

Você pode mostrar um emoji premium antes do texto do botão. Informe o ID no campo icon_custom_emoji_id, um número inteiro positivo de até 64 bits. Por exemplo, 007 é interpretado como 7. Letras, zero, números negativos ou grandes demais são descartados; o botão será salvo sem ícone.

O Telegram mostra esse ícone apenas para bots com as permissões necessárias: um nome adicional obtido no Fragment ou Telegram Premium do proprietário em envios diretos a uma pessoa ou grupo. Nos demais casos, o Telegram simplesmente ignora o ícone, sem trocá-lo por um emoji comum.

O campo style define a cor: Padrão, sem cor; Principal, azul; Sucesso, verde; ou Perigo, vermelho.

Uso único (single_use) permite usar os dados guardados no botão apenas uma vez, por exemplo, para confirmar uma escolha. A mudança do texto do botão e a exclusão da mensagem são opções separadas, descritas no comportamento ao clicar.

Outras opções dos botões

No editor, você pode ativar:

  • Em nova linha: começa uma nova linha de botões.
  • Ocupar toda a largura: deixa o botão sozinho na linha; o seguinte também começa em uma linha nova.

Exemplo de disposição; os colchetes representam botões:

Uma linha:        [Catálogo] [Ajuda]

Nova linha:       [Catálogo]
                  [Ajuda]

Toda a largura:   [         Ajuda         ]

Linhas e cores estão disponíveis no Telegram e no VK. A posição dos botões é mantida ao abrir e editar a mensagem novamente. Emojis premium só aparecem no Telegram quando o bot é compatível. Não existe uma opção «Abrir dentro do Telegram»: a Bot API não oferece esse controle por uma opção do botão.

Limites de cada canal

Escolha o canal para o bloco ou para um botão específico. Se escolher Todos os canais, o editor só oferece recursos comuns a todos. Não é possível salvar um tipo de botão que o canal selecionado não admite.

  • Telegram: links, Mini App, reação, notificação ou janela, linhas, cores e emoji personalizado quando o bot tem permissão.
  • VK: links, reação, aviso curto, linhas e cores. VK Mini App e VK Pay só aparecem com uma conexão VK compatível.
  • WhatsApp: um único botão de link, sem outros botões na mesma mensagem. Até 3 botões de resposta comuns; de 4 a 10, eles aparecem em uma lista. O texto pode ter até 20 caracteres. Não há linhas configuráveis, cores, Mini App nem notificações.
  • Instagram / Messenger: o adaptador atual envia apenas botões de resposta rápida, com até 20 caracteres. Não admite links, Mini App, notificações, linhas ou cores.
  • Widget do site: links e botões de resposta, sem linhas, cores ou notificações.
  • Email: links, inclusive de pagamento; não há botões de resposta ou notificações.

Para botões gerados de uma lista, você só pode escolher o número de colunas em canais que admitem linhas. Nos outros, o canal determina a posição. Os limites de quantidade de botões e tamanho dos textos são conferidos ao enviar.

O que acontece ao clicar

Para botões cujo clique chega ao bot, você pode substituir a mensagem por outro texto ou pelo conteúdo de outra reação, apagar a mensagem, adicionar uma etiqueta ou guardar um parâmetro, desde que o canal ofereça a opção. Só o Telegram pode trocar o texto do próprio botão depois do clique, como mudar «Inscrever-se» para «Selecionado». O fato de o VK permitir editar mensagens não inclui essa troca de texto do botão.

O Telegram espera uma confirmação do clique, chamada answerCallbackQuery. Normalmente, o GetMyBot a envia sozinho e remove o indicador de carregamento. A opção Ignorar answerCallbackQuery desativa essa confirmação.

No campo Texto ao clicar de um botão de reação, você pode escrever uma confirmação curta, como «Aula escolhida». O Telegram aceita até 200 caracteres e o VK, até 90; substituições funcionam. Normalmente o Telegram mostra o texto por pouco tempo sobre a conversa. Mostrar como janela só funciona no Telegram e usa answerCallbackQuery com show_alert. Se o texto estiver vazio, o bot apenas remove o indicador de carregamento. Com Ignorar answerCallbackQuery ativado, nem o texto nem a janela são enviados.

Dados guardados no botão (Carry)

Carry ajuda o botão a lembrar a qual item pertence. Imagine que um casaco e um vestido tenham o mesmo botão «Comprar». Guarde product_id=101 no botão do casaco e product_id=102 no do vestido. Ao clicar no vestido, a reação seguinte receberá {{ctx.product_id}} com o valor 102.

No editor, a opção se chama Dados ao clicar. A chave é o nome do dado; o valor pode ser número, texto ou substituição. O bot guarda o valor quando envia a mensagem e o coloca nos dados temporários (ctx) quando a pessoa clica. Cada botão tem valores próprios.

A validade (ttl_seconds ou TTL) é medida em segundos: 3600 equivale a uma hora; 0 usa o prazo padrão de 30 dias. Depois que ele termina, os dados deixam de estar disponíveis. Uso único (single_use) apaga os dados após o primeiro clique. Se o preço mudar no catálogo, um valor já guardado no botão não muda: antes de cobrar, consulte o preço atual pelo ID do produto.

Veja a configuração passo a passo e a diferença para parâmetros permanentes em Botões dinâmicos e dados.

Botões gerados de uma lista

Se seus produtos ou aulas já estão em uma lista, não crie os botões um a um. O bloco Botões dinâmicos de uma lista cria um botão para cada item. Escolha a lista em ctx, um nome para cada item, a quantidade de botões por linha e um modelo. {{item.name}}, por exemplo, insere o nome de um produto. Veja Botões dinâmicos e dados.

Emojis premium no texto

No bloco de texto, o botão de formatação Emoji premium insere <tg-emoji emoji-id="…">🙂</tg-emoji>. Quem tem Telegram Premium verá o emoji personalizado; os demais verão o emoji comum dentro da tag. Funciona tanto em HTML quanto em Markdown. O ID pode ter até 32 dígitos; você pode obtê-lo com getCustomEmojiStickers ou encaminhar a mensagem com o emoji para um bot como @idstickerbot.

Um link t.me/<bot>?start=<valor> executa /start <valor> no Telegram. Não é possível abrir uma conversa com esse valor sem executar /start por meio desse link. Escolha a alternativa conforme o objetivo:

  • /start sem resposta visível: na reação ao gatilho Comando /start com o Identificador do link de início desejado, deixe Enviar mensagem sem blocos. Não haverá uma resposta visível ao /start, mas o valor do link estará no evento e poderá ser usado pelas condições e ações da mesma reação.
  • Texto preparado: o link https://t.me/<bot>?text=<texto>, em um botão desse tipo ou em um botão de link, abre a conversa com o texto no campo de digitação. Nada é enviado e /start não é executado; a pessoa decide quando enviar.
  • Mensagem automática em nome da pessoa: a Bot API não permite que o bot a envie. A alternativa é um link ?start= e uma reação que responde com a mensagem desejada em nome do próprio bot.

Um bloco de texto pode esperar a resposta da pessoa. Nesse caso, a mensagem vira uma etapa do diálogo e o fluxo fica pausado até chegar a resposta. Várias etapas seguidas formam um questionário dentro da conversa.

Tipo de conteúdo esperado

O bot pode esperar texto, escolha entre opções, foto, vídeo, vídeo circular, áudio, arquivo, mensagem de voz, localização, contato, calendário ou dado. Se chegar outro tipo, a etapa considera a resposta inadequada.

Conferir o texto da resposta

Você pode exigir um telefone, email, link, data, horário ou correspondência com uma fórmula. Se o bot espera um telefone, por exemplo, um texto livre é recusado e uma mensagem de erro é mostrada. A validação por fórmula usa a fórmula avançada: retorna texto vazio quando a resposta é aceita e o texto do erro quando é recusada.

Guardar a resposta

Você pode salvar a resposta em um parâmetro. Depois, ela fica disponível como {{param.chave}} nas substituições e pode ser usada em condições. Assim, o diálogo preenche aos poucos o perfil do cliente.

Erros, lembrete e prazo

  • Mensagem de erro: o que mostrar quando a resposta não passar pela validação.
  • Lembrete: o que enviar se a pessoa demorar a responder.
  • Cancelar a espera após um prazo: define por quanto tempo o bot espera. Quando o prazo acaba, você pode iniciar outra reação para encerrar o questionário com cuidado. Ela aparece nas conexões entre reações como «Tempo de espera esgotado»; a reação a uma resposta aparece como «Resposta esperada».

Sair da etapa com um comando

/cancel ou a palavra russa отмена cancelam a espera e respondem Отменено., ou iniciam a reação de cancelamento, se houver uma. Os demais comandos são tratados como respostas por padrão e passam pela mesma validação. Assim, a etapa pode manter a pessoa no diálogo até que responda. Se você ativar Comandos do bot, como /start, interrompem a espera (escape_on_command), qualquer comando, como /start, encerrará a espera sem aviso e funcionará normalmente.

Substituições

O botão Substituições insere dados da pessoa ({{first_name}}, {{username}}, {{user_id}}), do evento ({{text}}, {{chat_id}}, {{datetime}}) e dos parâmetros ({{param.chave}}). Veja a lista completa em Substituições e fórmulas.

Botão do menu do bot

A ação Botão do menu escolhe o menu normal do bot, uma lista de comandos ou um botão de Mini App com texto e URL. Você pode aplicá-lo à conversa atual ou à configuração geral do bot. Assim, pode oferecer uma Mini App personalizada apenas ao cliente atual. A disponibilidade depende do canal.

Próximos passos