メッセージとボタン
ボットの返答を作る方法。テキスト、写真、メッセージの下のボタン、質問と回答の保存。
このページの内容
ボットから文章、写真、「選ぶ」ボタンを送りたいときは、メッセージを送信アクションを追加します。返答はブロックという部品を組み合わせて作ります。例えば、商品の写真を送り、続けて説明文とボタンを付けられます。メッセージに付くボタンは「inline ボタン」とも呼ばれます。
同じアクションで質問を送り、回答を待つこともできます。例えば電話番号を尋ね、顧客の情報として保存します。ここではブロック、ボタン、質問の設定を説明します。
メッセージのブロック
ブロックを追加を押し、送りたい内容を選びます。挨拶文、写真、講座の案内ファイルなどを組み合わせられます。
- テキスト:書式と差し込みに対応した文章です。最大 4,096 文字で、ボタンも付けられます。
- 写真:説明文を添えられる画像です。
- ファイル:説明文を添えられる文書です。
- Voice(音声メッセージ):Telegram で音声メッセージとして表示される音声です(
sendVoice)。OGG/OPUS、MP3、M4A、最大 50 MB に対応します。 - GIF:アニメーションまたは無音の MP4 です。最大 50 MB で、
sendAnimationを使います。 - Video note(ビデオノート):正方形の MP4、最大 60 秒です(
sendVideoNote)。説明文は付きません。メディアライブラリのファイルは送信のたびに再アップロードされます。Telegram は、別の方法で取得したfile_idをsendVoice、sendAnimation、sendVideoNoteで受け付けないためです。 - Carousel(カルーセル):写真、説明文、そのカード専用のボタンを組み合わせた 2~10 枚のカードです。Telegram で全写真に利用可能な
file_idがある場合に限り、editMessageMediaを使って 1 件のメッセージを「‹ ›」ボタンで切り替えます。ID はカードに指定するか、メディアライブラリのファイルから取得します。1 枚でも利用可能な ID を取得できない場合は、全カードを個別の写真メッセージとして送ります。VK など、ほかのチャンネルでも個別に送ります。各カードの説明文とボタンは維持されます。 - 遅延:次のブロックまで指定した秒数だけ待ちます。
- AI:指定したプロンプトを使い、モデルに返答を作らせます。
- リアクション:別のリアクションを呼び出します。完了を待つ設定もできます。
音声メッセージ、GIF、ビデオノート、カルーセルも通常のブロックと同様にリアクション内で使え、リアクションのクイック配信にも含められます。一斉送信をご覧ください。
ブロックはドラッグして並べ替えられます。表示順は順番どおりまたはランダムから選べます。ボットのメインメニューはそのまま、新しく設定、非表示のいずれかにできます。
ブロックのオプション
テキストとメディアのブロックでは、ピン留め、通知音なし、転送を禁止、ネタバレ表示、リンクのプレビューなし、指定秒数後に自動削除を設定できます。
Inline ボタン
ブロック内でボタンのテキストと種類を設定します。
- テキスト:ボタンの文字列を利用者の回答として送ります。Telegram と VK では返信用キーボードになり、質問への回答やテキストを条件とするリアクションの開始に使えます。WhatsApp、Instagram、Messenger、Web ウィジェットでは、常設キーボードのない返信ボタンです。
- リンク:URL を開きます。
- Web アプリ:Telegram Mini App を開きます。Mini Appをご覧ください。
- リアクション:押すと別のリアクションを開始します。
- Inline query(Inline クエリ):入力欄に「@bot 検索語」を入れるか、別のチャットを選ばせます(
switch_inline_query/switch_inline_query_current_chat)。Telegram で @BotFather の/setinlineを使って inline モードを有効にした場合だけ使えます。GetMyBot はこのクエリに回答しません(answerInlineQueryは未実装)。ボタンは検索語を準備しますが、検索結果は返しません。 - Prefilled text(入力済みテキスト):
https://t.me/<bot>?text=…を開き、ボットとのチャットの入力欄に文章を用意します。送信はしません(prefill)。 - Payment link(支払いリンク):指定必須の支払い URL を開きます。支払いは請求書を発行アクションで作成します。Telegram のネイティブ請求書ではなく、外部の支払いページへ移動します。
- 通知:押したときに文章を表示します。リアクションは起動せず、ボタンに保存した Carry データも渡しません。Telegram では 200 文字までの短い通知またはポップアップ、VK では 90 文字までの短い表示で、ポップアップはありません。
回答テキストと入力済みテキストの違い
| やりたいこと | ボタンの種類と設定 | 押した結果 |
|---|---|---|
| アンケートで「はい」を選ぶ | テキスト、表示名「はい」。メッセージは回答待ちにする | 「はい」が会話ステップの回答になります |
| 問い合わせ文を用意する | 入力済みテキスト、表示名「書く」、用意する文章「注文したい」 | 入力欄に下書きが表示され、利用者が編集して送信します |
ボタンの表示名と入力欄に用意する文章は別の設定です。入力済みテキストはメッセージを送らず、それだけではリアクションも起動しません。
リアクションを呼び出すボタンの押下は、ボットに独立したイベントとして届きます。技術的には callback と呼びます。Inline クエリと入力済みテキストは Telegram アプリ内で動作し、ボットに押下イベントを渡しません。そのため answerCallbackQuery による応答も、Carry データの受け渡しもできません。
ボタンのアイコンと色
ボタンの前にプレミアム絵文字を表示できます。アイコン欄に、その ID(icon_custom_emoji_id)を正の 64 ビット整数で入力します。例えば 007 は 7 として扱われます。文字、ゼロ、負の数、大きすぎる数は無効になり、ボタンはアイコンなしで保存されます。
Telegram で表示できるのは、必要な権限があるボットだけです。Fragment で追加のユーザー名を持つか、オーナーが Telegram Premium を持ち、個人チャットまたはグループに直接送る場合です。それ以外では Telegram がアイコンを無視し、通常の絵文字への置換も行いません。
スタイルは色の設定です。通常は無色、メインは青、成功は緑、危険は赤です。技術的なフィールド名は style です。
ワンタイム(押下後に無効化)(single_use)は、ボタンに保存したデータを 1 度だけ使える設定です。選択の確定などに使います。押下後にボタンの表示名を変えたり、メッセージを削除したりする設定とは別です。
ボタンの追加設定
チェックボックスで次を設定できます。
- 新しい行から:このボタンを次の行に置きます。
- 全幅に広げる:このボタンを単独の行に置き、次のボタンも新しい行から始めます。
配置例です。角括弧はボタンを表します。
同じ行: [カタログ] [ヘルプ]
改行: [カタログ]
[ヘルプ]
幅いっぱい: [ ヘルプ ]
行配置と色は Telegram と VK で使えます。行配置は再度開いて編集しても保たれます。Telegram のプレミアム絵文字には対応する接続が必要です。「Telegram 内で開く」の切り替えはありません。Bot API に、その挙動をこのフラグで制御する方法はありません。
チャンネルごとの制限
ブロックまたはボタンごとに接続を選べます。すべてのチャンネルを選ぶと、エディターは共通して使える機能だけを提供します。対応していない種類は保存できません。
- Telegram:URL、Mini App、リアクション、通知・ポップアップ、ボタンの行、色、権限がある場合のカスタム絵文字。
- VK:URL、リアクション、短い通知、行、色。VK Mini App と VK Pay は対応する VK 接続を選んだ場合に限ります。
- WhatsApp:同じメッセージ内にほかのボタンを置かない場合、URL ボタンを 1 件使えます。返信ボタンは通常表示で最大 3 件、4~10 件はリストになります。表示名は最大 20 文字。行、色、Mini App、通知は使えません。
- Instagram / Messenger:現在の接続は返信ボタン(quick replies)のみを送れます。表示名は最大 20 文字。URL、Mini App、通知、行、色は使えません。
- Web ウィジェット:URL と返信ボタンを使えます。行、色、通知は使えません。
- メール:支払いリンクを含むリンクを使えます。返信ボタンと通知は使えません。
リストからボタンを作るとき、列数を指定できるのは行配置に対応するチャンネルだけです。ほかのチャンネルでは配置が自動で決まります。ボタン数と表示名の長さも送信時に確認されます。
ボタンを押した後の動作
押下イベントがボットに届くボタンでは、チャンネルが対応していれば、メッセージを置き換える(文章または別のリアクションの内容にする)、メッセージを削除する、ラベルを付ける、パラメータを保存する、といった動作を設定できます。押下後にボタン自体の表示名を変更できるのは Telegram だけです。例えば「予約する」を「選択済み」に変えられます。VK のメッセージ編集機能ではボタンの表示名は変えられません。
Telegram はボタンを押した後、ボットからの answerCallbackQuery を待ちます。通常は GetMyBot が自動で応答し、ボタンの読み込み表示を消します。answerCallbackQueryをスキップ を設定すると、この応答を送りません。
リアクションボタンの**Text on press (notification)には、「講座を選択しました」など短い確認文を書けます(Telegram は最大 200 文字、VK は最大 90 文字)。差し込みも使えます。Telegram では通常、チャットに短時間表示されます。Telegram だけのShow as a popup (alert)**を選ぶと、show_alert を付けた answerCallbackQuery によりウィンドウが開きます。文章が空なら読み込み表示だけを消します。answerCallbackQueryをスキップ が有効な場合、文章もポップアップも送りません。
ボタンに保存するデータ(Carry)
Carry は、そのボタンが何を指すかを記憶します。例えばコートにもワンピースにも同じ「購入」ボタンを付ける場合、前者に product_id=101、後者に product_id=102 を保存します。ワンピースのボタンを押すと、次のリアクションで {{ctx.product_id}} が 102 になります。
エディターではクリック時に送るデータを設定します。キーは値の名前で、値には数値、文章、差し込みを使えます。ボットはメッセージ送信時にデータを保存し、押されたときにリアクションの一時データ(ctx)へ入れます。保存値はボタンごとに別です。
ボタンデータの有効期間(ttl_seconds、TTL)は秒で指定します。3600 は 1 時間、0 は初期値の 30 日です。期限後はデータを使えません。ワンタイム(押下後に無効化)(single_use)なら、最初の押下後に削除されます。保存した価格は商品一覧の変更に合わせて自動更新されません。決済前に商品 ID から最新価格を確認してください。
設定の手順と恒久的なパラメータとの違いは、動的ボタンとパラメータをご覧ください。
動的ボタン
商品や講座のリストがある場合、ボタンを手作業で 1 件ずつ追加する必要はありません。動的ボタンブロックは、各要素からボタンを作ります。リストが入った ctx の場所、1 要素の名前(エイリアス)、1 行のボタン数、表示名のテンプレートを指定します。例えば {{item.name}} で各商品の名前を入れられます。動的ボタンとパラメータもご覧ください。
文章内のプレミアム絵文字
テキストブロックのプレミアム絵文字を使うと、<tg-emoji emoji-id="…">🙂</tg-emoji> を挿入できます。Telegram Premium では専用の絵文字が表示され、ほかの受信者にはタグ内の代替絵文字が表示されます。HTML と Markdown の両形式で使えます。絵文字 ID は最大 32 桁の数値です。getCustomEmojiStickers で調べるか、目的の絵文字を @idstickerbot のようなボットに転送して確認できます。
ボットへのリンクと入力済みテキスト
t.me/<bot>?start=<parameter> は、Telegram で /start <parameter> を実行するリンクです。このリンクで /start を実行せずにパラメータだけ渡すことはできません。目的に応じて次を選んでください。
- 目立たない /start:/start コマンドトリガーに特定の開始リンクのタグを指定したリアクションで、メッセージを送信アクションのブロックを空にします。
/start自体への目立つ返答はありません。タグの値はイベントのコンテキストに入り、同じリアクションの条件やアクションで使えます。 - Prefilled text(入力済みテキスト):
https://t.me/<bot>?text=<text>(入力済みテキストのボタン、または普通のリンクボタン)は、チャットの入力欄に文章を置くだけです。/startは実行されず、利用者が自分で送信します。 - リンクを開いた瞬間に利用者名義で送ることは Bot API ではできません。ボットは利用者の名義で送信できません。近い方法は
?start=のリンクを使い、リアクションからボット名義で返答することです。
回答を待つ(会話のステップ)
テキストブロックで利用者の回答を待つ設定ができます。メッセージが会話の 1 ステップになり、回答までシナリオが一時停止します。複数のステップを続ければ、チャット内のアンケートや入力フォームを作れます。
待ち受ける内容の種類
文章、選択肢(選択ボタン)、写真、動画、ビデオノート、音声、文書、音声メッセージ、位置情報、連絡先、カレンダー、サイコロを指定できます。別の種類が届くと、不適切な回答として扱われます。
文章の検証
文章には、電話番号、メールアドレス、URL、日付、時刻、数式との一致を確認する設定があります。例えば電話番号を待つ場合、自由な文章は受け付けず、エラーメッセージを表示できます。数式による確認には拡張数式を使います。受け付けるときは空文字列、拒否するときはエラー文を返す数式です。
回答の保存
利用者の回答をパラメータに保存できます。後から {{param.key}} のように文章へ差し込んだり、条件で使ったりできます。会話の各ステップで顧客の簡単なプロフィールを作れます。
エラー、リマインダー、期限
- 検証エラー時のメッセージ:回答が条件に合わないときに表示します。
- リマインダー:利用者が答えないときに送ります。
- 待機のタイムアウト:いつ回答待ちを終了するかを指定します。タイムアウト時に別のリアクションを起動し、アンケートを穏やかに終えることもできます。関連ではタイムアウト先が「待機タイムアウト」、回答を受けるリアクションが「期待する回答」として表示されます。
コマンドによる回答待ちの終了
/cancel またはロシア語の文字列 отмена を送ると回答待ちを終了し、「Отменено.」と返信します。キャンセル用のリアクションを設定していれば、代わりにそのリアクションを開始します。ここで認識される単語はロシア語の отмена です。日本語の「キャンセル」が同じ動作になるわけではありません。
ほかのコマンドは、通常の文章と同じように回答として受け取り、検証します。回答を得るまで利用者をそのステップに留めるためです。Bot commands (e.g. /start) end the wait(escape_on_command)を有効にすると、例えばアンケート中の /start のようなコマンドが回答待ちを通知なしで終了し、通常どおり実行されます。
差し込み
差し込みボタンで、送り主の情報({{first_name}}、{{username}}、{{user_id}})、イベントの情報({{text}}、{{chat_id}}、{{datetime}})、パラメータ({{param.key}})を挿入できます。全項目と数式は差し込みと数式をご覧ください。
ボットのメニューボタン
Menu button アクションでは、通常のボットメニュー、コマンドメニュー、または表示名と URL を指定した Mini App ボタンを選べます。適用範囲は現在のチャットか、ボット全体です。例えば、その顧客のチャットだけに専用の Mini App を設定できます。利用できる設定はチャンネルの機能によって異なります。