Botões dinâmicos e parâmetros

Botões inline não precisam ser estáticos. GetMyBot pode construir um teclado a partir de dados — um botão para cada elemento de lista — e anexar a cada botão seu próprio conjunto de parâmetros, fixados no momento do envio. Esta é a base de cenários do tipo "exibe catálogo → usuário escolhe um item específico → processamos exatamente esse". Tudo é configurado no bloco de mensagem da ação "Enviar mensagem".

Botões dinâmicos a partir de lista

O bloco "Botões dinâmicos a partir de lista" expande um array de ctx em um teclado: um botão para cada elemento do array. Quatro coisas são configuradas:

  • Lista — chave do array no contexto (over), por exemplo ctx.products. O array normalmente é colocado lá pelas ações "Consulta à fonte", "Requisição web" ou por computação.
  • Alias do elemento — nome pelo qual o elemento é acessível no template (as, padrão: item).
  • Botões por linha — quantos botões colocar em cada linha (columns, padrão: 1).
  • Template do botão — um botão comum, mas cujo texto e campos suportam substituições pelo alias: {{item.name}}, {{item.price}} etc.

No envio, o template é renderizado para cada elemento, criando tantos botões quantos forem os elementos na lista. Assim são construídos catálogos, listas de registros de coleção e menus a partir de dados.

Exemplo

Em ctx.products há um array de objetos com campos id, name, price. No template do botão, especifique o texto {{item.name}} — {{item.price}}, e em Carry — a chave product_id com valor {{item.id}}. Você obterá um botão por produto, e ao clicar o bot saberá exatamente qual produto foi escolhido.

Parâmetros no clique (Carry)

O bloco "Carry — snapshot de dados no clique do botão" anexa ao botão um conjunto de pares chave → valor, calculados e fixados no momento do envio da mensagem. Ao clicar, esses valores são restaurados em ctx — por isso cada botão carrega seus próprios parâmetros (por invocação), mesmo que haja dezenas de botões enviados em uma única mensagem.

  • chave carry — nome pelo qual o valor retornará em ctx ao clicar.
  • valor carry — template com substituições ({{item.id}}, {{param.order_id}}, {{ctx.x}}), calculado no momento do envio.
  • Uso único (single_use) — o payload é consumido após o primeiro clique.
  • Tempo de vida do payload (ttl_seconds) — prazo de validade do snapshot em segundos (0 — valor padrão).

Esta é a funcionalidade essencial "parâmetros do link vinculados a um botão específico": o valor é memorizado no botão, não no estado geral do usuário, então cliques paralelos não se sobrescrevem.

Definição de parâmetros por botão (set_params)

Além do snapshot Carry, o botão pode definir diretamente parâmetros do assinante ao clicar — campo "Parâmetros" (set_params). Ao contrário do Carry (valores temporários em ctx), set_params escreve nos parâmetros permanentes do usuário ({{param.chave}}), que persistem entre execuções. O mesmo campo existe no bloco de mensagem — nesse caso os parâmetros são definidos no envio, não no clique.

O botão ao clicar também pode adicionar e remover marcações — com os mesmos campos do bloco de mensagem.

Diferença entre os três mecanismos

  • Carry — snapshot em ctx, dura até o clique, vinculado a um botão específico, com TTL e uso único.
  • set_params no botão — escreve parâmetros permanentes do assinante ao clicar.
  • set_params no bloco — escreve parâmetros permanentes no envio da mensagem.

Para o cenário "escolheu o produto — processamos esse produto", use botões dinâmicos + Carry: a lista de produtos é expandida em botões, e o product_id de cada produto vai para o Carry exatamente daquele botão.

Próximos passos