ダイナミックボタンとパラメータ

インラインボタンは静的なものだけではありません。GetMyBot はデータからキーボードを生成できます。リストの各要素に1つのボタンを割り当て、送信時に確定された独自のパラメータセットを各ボタンに付与できます。これは「カタログを表示 → ユーザーが特定の商品を選択 → その商品を処理する」というシナリオの基盤となります。すべて 「メッセージを送信」 アクションのメッセージブロックで設定します。

リストからのダイナミックボタン

「リストからのダイナミックボタン」 ブロックは ctx の配列をキーボードに展開します。配列の各要素に1つのボタンが対応します。4つの設定項目があります:

  • リスト — コンテキスト内の配列のキー（over）、例: ctx.products。配列は通常「ソースへのリクエスト」、「ウェブリクエスト」、または計算アクションで格納されます。
  • 要素のエイリアス — テンプレート内で要素にアクセスするための名前（as、デフォルトは item）。
  • 1行のボタン数 — 1行に並べるボタン数（columns、デフォルトは 1）。
  • ボタンテンプレート — 通常のボタンですが、テキストとフィールドでエイリアスによる置換をサポートしています: {{item.name}}、{{item.price}} など。

送信時にテンプレートが各要素についてレンダリングされ、リストの要素数と同じ数のボタンが生成されます。カタログ、コレクションレコードのリスト、データからのメニューを構築するのに使います。

例

ctx.products に id、name、price フィールドを持つオブジェクトの配列が格納されているとします。ボタンテンプレートにテキスト {{item.name}} — {{item.price}} 円、Carry には値 {{item.id}} のキー product_id を指定します。すると商品ごとにボタンが生成され、タップ時にボットはどの商品が選択されたかを正確に把握できます。

タップ時のパラメータ（Carry）

「Carry — ボタンタップへのデータスナップショット」 ブロックは、メッセージ送信時に計算・確定された キーと値のペアのセットをボタンに付与します。タップ時にこれらの値は ctx に復元されます。これにより、1つのメッセージで送信された数十個のボタンであっても、各ボタンが固有のパラメータ（per-invocation）を持つことができます。

  • carry キー — タップ時に ctx に復元される値の名前。
  • carry 値 — 送信時に計算されるプレースホルダーを含むテンプレート（{{item.id}}、{{param.order_id}}、{{ctx.x}}）。
  • 使い捨て（single_use）— 最初のタップ後にペイロードが消去されます。
  • ペイロードの有効期限（ttl_seconds）— スナップショットの有効期間（秒）（0 はデフォルト値）。

これが「特定のボタンに紐付いたリンクパラメータ」という重要な機能です。値は共通のユーザー状態ではなくボタンに記憶されるため、並行タップが互いに上書きしません。

ボタンによるパラメータ設定（set_params）

Carry スナップショットに加えて、ボタンはタップ時に購読者のパラメータを直接設定できます。「パラメータ」（set_params）フィールドです。Carry（ctx の一時的な値）と異なり、set_params は実行をまたいで保持される永続パラメータ（{{param.キー}}）に書き込みます。同様のフィールドはメッセージブロックにもあり、その場合はタップ時ではなく送信時にパラメータが設定されます。

ボタンはタップ時にラベルの設定・解除もできます。メッセージブロックと同じフィールドを使用します。

3つのメカニズムの違い

  • Carry — ctx へのスナップショット。タップまで保持され、特定のボタンに紐付きます。TTL と使い捨て機能あり。
  • ボタンの set_params — タップ時に購読者の永続パラメータに書き込みます。
  • ブロックの set_params — メッセージ送信時に永続パラメータに書き込みます。

「商品を選択して処理する」シナリオには、ダイナミックボタン + Carry を使用してください。商品リストをボタンに展開し、各商品の product_id をそれぞれのボタンの Carry に格納します。

次のステップ