Mensagens e botões

A ação "Enviar mensagem" monta a resposta do bot a partir de blocos e adiciona botões inline, menu principal e etapas de diálogo. É a ação mais completa do construtor — aqui também são configuradas as substituições e os parâmetros de referência dos botões.

Blocos da mensagem

Uma mensagem é uma sequência de blocos (botão Adicionar bloco):

  • Texto — texto formatado (até 4096 caracteres) com substituições e botões.
  • Foto — imagem com legenda.
  • Arquivo — documento com legenda.
  • Atraso — pausa em segundos antes do próximo bloco.
  • IA — resposta gerada por um modelo a partir de um prompt.
  • Reação — chama outra reação (opcionalmente aguardando sua conclusão).

Os blocos podem ser reordenados por arrastar. O modo de exibição dos blocos pode ser "Em ordem" ou "Aleatório" (para respostas variadas). O menu principal do bot pode ser mantido sem alterações, definido como novo ou ocultado.

Opções do bloco

Blocos de texto e mídia possuem flags: fixar, sem som, proteção contra encaminhamento, spoiler, sem prévia de links, auto-exclusão em N segundos.

Botões inline

No bloco você configura os botões (Texto do botão + Tipo):

  • Texto (callback) — botão com processamento do clique no lado do bot.
  • Link — abre uma URL.
  • Web App — abre um Telegram Mini App. Veja Mini App.
  • Chamar reação — o clique dispara outra reação.
  • Receber pagamento e Notificação — marcados como "em breve".

O estilo do botão — padrão, azul (Primary), verde (Success) ou vermelho (Danger). O flag "De uso único" desativa o botão após o primeiro clique.

Comportamento ao clicar

Para botões callback, você configura o que acontece ao clicar: substituir o texto do botão, substituir a mensagem (por texto ou pelo conteúdo de uma reação vinculada), excluir a mensagem, ignorar answerCallbackQuery. O clique também pode definir etiquetas e configurar parâmetros.

Parâmetros no botão (Carry)

O bloco "Carry — snapshot de dados no clique do botão" vincula ao botão um conjunto de valores fixados no momento do envio. Ao clicar, esses valores entram no contexto — assim cada botão carrega seus próprios parâmetros (por invocação), mesmo que haja muitos botões. Define-se o tempo de vida do payload em segundos. Esta é a base dos cenários "escolha o produto → confirme exatamente este".

Botões dinâmicos

O bloco "Botões dinâmicos a partir de lista" expande um array do ctx em botões — um por elemento. Configurações: chave da lista no ctx, alias do elemento, número de botões por linha e template do botão (suporta {{alias.campo}}). Assim se constroem catálogos, listas de registros e menus com dados de coleções. Saiba mais em Botões dinâmicos e parâmetros.

Um bloco de texto pode aguardar a resposta do usuário — isso transforma a mensagem em uma etapa de diálogo e coloca o cenário em pausa até a resposta. Várias etapas seguidas formam um questionário ou assistente diretamente no chat.

Tipo de conteúdo esperado

O bot pode aguardar um tipo específico de resposta: texto, escolha entre opções (botões de escolha), foto, vídeo, nota em vídeo, áudio, documento, mensagem de voz, localização, contato, calendário ou dado. Se o usuário enviar um tipo diferente, a etapa considera a resposta inadequada.

Validação do texto

Para respostas de texto, é possível ativar a validação de formato: telefone, e-mail, link, data, hora ou correspondência a uma fórmula (expressão regular). Uma resposta que não passe na validação é rejeitada e o bot exibe uma mensagem de erro.

Salvar a resposta

A resposta do usuário pode ser salva em um parâmetro — depois disso fica disponível nas substituições como {{param.chave}} e nas condições. Assim as etapas de diálogo constroem um mini-perfil do cliente.

Erros, lembrete e timeout

  • Mensagem ao falhar na validação — o que exibir se a resposta não passou na validação.
  • Lembrete — o que enviar se o usuário ficar em silêncio.
  • Cancelar aguardo por timeout — depois de quanto tempo parar de aguardar; ao atingir o timeout, é possível disparar uma reação (por exemplo, encerrar o questionário suavemente). Essa reação aparece nas conexões como "Timeout de aguardo", e a reação à resposta propriamente dita aparece como "Resposta esperada".

Substituições

O botão "Substituições" insere variáveis: dados do remetente ({{first_name}}, {{username}}, {{user_id}}), do evento ({{text}}, {{chat_id}}, {{datetime}}) e parâmetros ({{param.chave}}). Lista completa e fórmulas em Substituições e fórmulas.

Próximos passos