동적 버튼과 매개변수

인라인 버튼은 정적인 것만 있지 않습니다. GetMyBot은 데이터에서 키보드를 만들 수 있습니다 — 목록의 각 요소마다 버튼 하나 — 그리고 각 버튼에 전송 시 고정된 자체 매개변수 세트를 첨부할 수 있습니다. 이것이 '카탈로그 보기 → 사용자가 특정 상품 선택 → 정확히 그 상품 주문' 시나리오의 기초입니다. 모두 '메시지 전송' 액션의 메시지 블록에서 설정됩니다.

목록에서 동적 버튼

'목록에서 동적 버튼' 블록은 ctx의 배열을 키보드로 펼칩니다: 배열의 각 요소마다 버튼 하나. 네 가지를 설정합니다:

  • 목록 — 컨텍스트의 배열 키 (over), 예: ctx.products. 배열은 보통 '소스에 요청', '웹 요청' 또는 계산 액션이 그 위치에 저장합니다.
  • 요소 별칭 — 템플릿에서 요소에 접근하는 이름 (as, 기본값: item).
  • 행당 버튼 수 — 한 줄에 배치할 버튼 수 (columns, 기본값: 1).
  • 버튼 템플릿 — 일반 버튼이지만 텍스트와 필드에서 별칭으로 치환을 지원합니다: {{item.name}}, {{item.price}} 등.

전송 시 템플릿이 각 요소마다 렌더링되어 목록의 요소 수만큼 버튼이 생성됩니다. 이렇게 카탈로그, 컬렉션 레코드 목록, 데이터 기반 메뉴가 만들어집니다.

예시

ctx.products에 id, name, price 필드가 있는 객체 배열이 있습니다. 버튼 템플릿에 {{item.name}} — {{item.price}} ₽ 텍스트를 지정하고, Carry에 {{item.id}} 값의 product_id 키를 추가합니다. 상품마다 버튼이 생성되며 클릭 시 봇이 정확히 어떤 상품이 선택되었는지 알 수 있습니다.

클릭 시 매개변수 (Carry)

'Carry — 버튼 클릭에 데이터 스냅샷' 블록은 버튼에 키 → 값 쌍 세트를 첨부합니다. 이 값은 메시지 전송 시 계산되어 고정됩니다. 클릭 시 이 값들이 ctx에 복원됩니다 — 따라서 각 버튼이 자체 매개변수(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.키}})에 씁니다. 유사한 필드가 메시지 블록에도 있습니다 — 그 경우 클릭 시가 아닌 전송 시 매개변수가 설정됩니다.

버튼은 클릭 시 레이블을 추가하거나 제거할 수도 있습니다 — 메시지 블록과 동일한 필드를 사용합니다.

세 메커니즘의 차이

  • Carry — ctx의 스냅샷, 클릭까지 유지, 특정 버튼에 연결, TTL 및 일회용 옵션.
  • 버튼의 set_params — 클릭 시 구독자의 영구 매개변수 저장.
  • 블록의 set_params — 메시지 전송 시 영구 매개변수 저장.

'상품 선택 → 주문' 시나리오에는 동적 버튼 + Carry를 사용하세요: 상품 목록이 버튼으로 펼쳐지고, 각 상품의 product_id가 해당 버튼의 Carry에 저장됩니다.

다음 단계