Telegram インラインボタンの制限を完全解説：キーボード制限を回避して効率的なメニューを設計する方法

Telegram Bot を開発または運用しているなら、インラインキーボード（Inline Keyboard）に必ず遭遇したことがあるでしょう。これは Bot とユーザーの対話の中核となる入口です。ボタンをクリックして注文照会、言語切り替え、チケット提出など、ほぼすべての効率的なメニューがこれに依存しています。

しかし、多くの開発者はリリース後に、丹念に設計したメニューが Telegram クライアント上で「欠けた状態」になることに気づきます。ボタンが消える、クリックしても反応がない、多言語翻訳後にレイアウトが崩れるなどです。これらの問題の根本原因は、多くの場合、Telegram インラインボタンの制限を十分に理解していないことにあります。

この記事では、Telegram Bot API におけるインラインキーボード関連の5つの主要な制限パラメータをひとつずつ解説し、実際の運用シナリオから得た4つの回避策を紹介します。最後に、TG-Staff のようなビジュアルツールを使って開発段階でこれらの制限を事前に回避し、本番トラブルを防ぐ方法をご紹介します。

なぜ Telegram インラインボタンの制限が Bot のメニュー設計に影響するのか

まず実際のシナリオを見てみましょう。あなたの Bot が越境 EC の顧客向けに多言語カスタマーサポートを提供しているとします。メニューには「注文を見る」「サポートに連絡」「言語切り替え」「よくある質問」の4つのメインボタンがあります。中国語版は完璧に見えますが、ドイツ語版に切り替えるとボタンのテキストが長くなり、1行2つのボタンが1行1つになり、ユーザーはすべての選択肢を見るためにさらに1画面スクロールしなければなりません。

これだけではありません。もしコード内でうっかり1行に9つのボタンを割り当てたり、callback_data に64バイトを超える文字列を書いたりすると、Telegram は超過部分を無視します。ユーザーが見るメニューは不完全で、一部のボタンをクリックしても何も反応がなく、サーバーログからは何も見つかりません。

このような問題は開発段階では再現が難しく、開発者はよく使う言語とボタン数のみをテストする傾向があるからです。多言語、多デバイス、多ユーザーの実際の環境に入ると、インラインボタンの制限は「隠れた落とし穴」になります。

これらの制限パラメータを事前に理解し、メニュー設計時に積極的に検証することが、本番トラブルを防ぐ最も効果的な手段です。

Telegram インラインボタンの5つの主要な制限パラメータ（公式ドキュメント解説）

Telegram Bot API ドキュメントでは、インラインキーボードの制限について明確に説明されています。以下は最も重要な5つのパラメータで、それぞれがメニュー設計のボトルネックになり得ます。

数とレイアウトの制限：1行あたり最大8ボタン、キーボード全体で最大100ボタン

これは最も直感的な制限であり、開発者が最も見落としがちなものです。

• 1行あたりのボタン数：≤ 8個。1行に9個のボタンを配置すると、Telegram は9個目以降を無視します。
• 総ボタン数：≤ 100個。インラインキーボード全体（全行合計）は100個を超えてはいけません。
• 行数：API ドキュメントでは行数に明確な制限はありませんが、総ボタン数 ≤ 100 の制約を受けます。例えば、1行に5個のボタンを配置する場合、最大20行まで可能です。1行に8個のボタンを配置する場合、最大12行まで（8×12=96、残りスペースが1行分に満たない）。

実際の開発では、特にモバイル端末では1行あたりのボタン数を ≤ 5個に制限することをお勧めします。Telegram クライアントは画面幅に応じてボタン幅を自動調整するため、1行8個のボタンはデスクトップではなんとか見えますが、スマートフォン画面では非常に狭くなり、正確にタップするのが難しくなります。

コールバックデータ（callback_data）の長さ制限：1～64バイト

これはインラインボタンの「隠れた命綱」です。callback_data はボタンがクリックされた後に Bot に返されるデータで、Telegram はその長さを 1～64バイト に制限しています。

64バイトを超えると、Telegram はエラーメッセージを返さず、ボタンクリックが無反応になります。ユーザーは何が起こったのか分からず、ログにも記録が残らないため、原因を特定できません。

バイト計算の注意点：

• 英字と数字：1文字1バイト
• 中国語文字：1文字3バイト（UTF-8エンコード）
• 絵文字：1文字4バイト

例えば、callback_data = "order_20250315_zh_cn_001" は短く見えても実際の長さは29バイトです。一方、callback_data = "查询订单_2025年3月15日_中文版" は中国語文字が多く、64バイトを簡単に超えてしまいます。

ベストプラクティス：短いコードによるマッピングを使用します。例えば、データベースに短いIDを保存し、callback_data では id=12345 だけを送信し、Bot がIDをもとにデータベースを参照して完全なデータを取得します。TG-Staff の自動翻訳機能を使えば、長いテキストを短い識別子に変換し、長すぎる問題を回避できます。

ボタンテキスト長と複数行サポートの暗黙のルール

Telegram 公式はボタンテキストの長さにハードリミットを設けていませんが、実際の使用では以下の点に注意が必要です。

• テキストが長すぎると、Telegram クライアントが自動的に折り返しますが、折り返し位置は制御できず、ボタンの高さが不揃いになる可能性があります。
• テキストが64文字を超えると、一部のクライアントバージョンで末尾が省略記号で切り詰められます。

ボタンテキストは 20文字以内（英語）または 10中国語文字以内 に抑えることをお勧めします。これにより、ほとんどの画面で完全に表示され、折り返しによるレイアウト崩れを防げます。

多言語シナリオでは、言語ごとにテキストの長さが大きく異なります。例えば、「注文を見る」は中国語で4文字ですが、ドイツ語では「Bestellung anzeigen」と12文字になります。言語ごとにボタンテキストを個別に設計しなければ、ボタン幅が不均一になり、見た目が悪くなる可能性があります。

メニュー設計の落とし穴：制限に起因する4つの一般的な問題と解決策

以下は、Bot を運用するチームが最も陥りやすい4つの問題です。それぞれに実践可能な解決策を添えています。

問題1：メニューボタンが「消える」または「1行増える」

現象：コードで1行に6個のボタンを定義したのに、ユーザーには5個しか見えない。または、総ボタン数が100を超え、最後の数個のボタンが表示されない。

原因：1行あたり ≤ 8個、総ボタン数 ≤ 100個の制限に違反している。Telegram はエラーを出さず、超過部分を静かに無視する。

解決策：

• コード内でハードチェックを行う：キーボード送信前に配列を走査し、各行の数 ≤ 8、総数 ≤ 100 を確認する。
• TG-Staff のビジュアルフローエディターを使用する場合、ボタンをドラッグすると右側パネルに現在のキーボードの総ボタン数と各行の数がリアルタイム表示される。制限を超えると、エディターが自動的に警告を表示し、保存を禁止する。

問題2：ユーザーがボタンをクリックしても反応がない（callback_data が長すぎる）

現象：ユーザーがボタンをクリックしても、Bot にコールバックが届かず、エラーも返らない。調査の結果、callback_data が64バイトを超えていた。

原因：callback_data の長さが64バイトを超え、Telegram がデータを破棄した。

解決策：

• 短いコードによるマッピングに切り替える。例えば、callback_data = "order_detail_20250315_zh_cn_001" を callback_data = "od_12345" に変更し、サーバー側でIDをもとにデータベースを参照して完全な情報を取得する。
• TG-Staff の自動翻訳機能を利用して、長いテキストを自動的に短い識別子に変換し、手動処理を避ける。

問題3：多言語メニューで翻訳後にボタンがずれる

現象：同じメニューでも、中国語版では整然と見えるが、ドイツ語やロシア語に切り替えるとボタン幅が不均一になり、視覚的に「ボタンが重なる」ような状態になる。

原因：言語ごとにテキスト長が異なるため、Telegram クライアントがボタン幅を自動調整するが、その調整ロジックは制御不能。

解決策：

• 言語ごとにボタンテキストの長さを個別に設計する。中国語ボタンは4～6文字、英語は8～12文字、ドイツ語は10～15文字に抑える。
• アイコンと短いテキストの組み合わせを使用する。例えば、「📦 + Order」のように、「View Order Details」よりもアイコンの方が配置が安定し、短いテキストの方が適応性が高い。
• TG-Staff エディターでは、言語バージョンごとにボタンテキストを個別に設定できるため、グローバル統一テキストによるずれを回避できる。

問題4：動的にボタンを更新する際、新しいキーボードが制限を超える

現象：ユーザーがボタンをクリックした後にキーボードを動的に更新（例えばページネーション）した結果、新しいキーボードのボタン数が100を超え、一部のボタンが表示されない。

原因：動的に生成されたキーボードで制限が再チェックされていない。

解決策：

• 新しいキーボードを生成するたびに、総ボタン数 ≤ 100 かつ各行 ≤ 8 をチェックする。
• データ量が多い場合は、ページネーションを検討する：1ページあたり50ボタン（5行×10列）を表示し、ユーザーが「次のページ」をクリックするとキーボードを更新する。
• TG-Staff のエディターは自動ページネーションをサポートしており、「1ページあたり最大Nボタン」を設定すると、超過時に自動的にページ送りボタンを生成する。

実践ケース：TG-Staff のドラッグ＆ドロップエディターでインラインボタン制限を回避する

多言語カスタマーサポートメニューを設計していると仮定します。以下の機能を含みます：

• 注文確認（3ステータス：未払い、支払い済み、発送済み）
• サポートに連絡
• 言語切り替え（8言語対応）
• よくある質問（5カテゴリ）

制限をかけなければ、このメニューの総ボタン数は3+1+8+5=17個になり、1行あたりのボタン数も8個を超える可能性があります。手動でJSONコードを書くと、チェック漏れが発生しやすくなります。

TG-Staff のドラッグ＆ドロップ式コマンドフローエディターでは、次のように操作できます：

1. 「インラインキーボード」ノードをキャンバスにドラッグします。
2. 右側パネルで、順にボタンを追加します：1行目に「注文を見る」「サポートに連絡」「よくある質問」、2行目に8つの言語切り替えボタンを配置します。
3. エディターは現在のキーボードの総ボタン数（11個）と各行の数（1行目3個、2行目8個）をリアルタイム表示します。もし行が8個を超えると、エディターが赤く表示し、保存を禁止します。
4. さらにボタンを追加する必要がある場合（例えば「未払い」「支払い済み」「発送済み」をサブメニューとして）、新しいキーボードノードを作成し、「ジャンプ」アクションで接続することで、すべてのボタンを1つのキーボードに詰め込まずに済みます。

インラインボタン vs リプライキーボード：どちらの操作方式を選ぶべきか？

多くの開発者がインラインボタンとリプライキーボードを混同しています。両者の核心的な違いは以下の通りです：

比較項目	インラインボタン	リプライキーボード
表示位置	メッセージ下部、メッセージに紐づく	入力フィールド上部、メッセージから独立
ボタン数の制限	≤ 100個（1行あたり≤8個）	明確な上限なし、ただし≤20個推奨
コールバックデータ	callback_data対応（≤64バイト）	非対応、クリックで直接テキスト送信
適用シーン	多段階選択、データ検索、ページネーション	テキスト入力誘導、クイック返信
ユーザー体験	入力フィールドを占有せず、過去メッセージを保持可能	入力フィールドを隠すため、短い返信に最適

判断基準：

• ユーザーが複数の選択肢から選ぶ必要がある場合（例：注文ステータスの選択、言語の切り替え）は、インラインボタンを使用します。
• ユーザーが短いテキストを入力するだけの場合（例：「はい」「いいえ」の返信、キーワード入力）は、リプライキーボードを使用します。
• メニューに100個以上のボタンがある場合（例：商品リスト）は、インラインボタンのページネーションを検討するか、入力誘導＋キーワードマッチングに切り替えます。

よくあるFAQ：インラインボタンの制限に関する4つの高頻度質問

Q1：ボタンを動的に更新する場合、制限は再計算されますか？ A：はい。editMessageReplyMarkup や editMessageText でキーボードを更新するたびに、Telegramは新しいキーボードのボタン数、行数、callback_dataの長さを再検証します。新しいキーボードが制限を超える場合、更新は失敗しエラーが返ります。

Q2：制限はクライアントのバージョンによって変わりますか？ A：変わりません。これらの制限はTelegram Bot APIのハードな仕様であり、すべてのクライアントバージョン（iOS、Android、デスクトップ版）で同じ制限が適用されます。ただし、クライアントによって表示効果が若干異なる場合があります（例：ボタンの幅、改行動作）。

Q3：有料Botは上限が高くなりますか？ A：いいえ。Telegram Bot APIはすべてのBotを平等に扱い、有料かどうか、サードパーティプラットフォーム（例：TG-Staff）を使用しているかどうかに関わらず、制限は完全に同じです。

Q4：callback_dataに日本語を使用できますか？ A：可能ですが、バイト長に注意してください。日本語の文字は3バイト、絵文字は4バイトを占めます。短いコードでマッピングし、日本語テキストを直接渡さないことを推奨します。

まとめと次のアクション

Telegram のインラインボタン制限は一見単純ですが、実際の開発ではしばしば見落とされがちです。次の3つのコアな数字を覚えておいてください：1行あたり ≤ 8ボタン、キーボード全体 ≤ 100ボタン、callback_data ≤ 64バイト。

既存のBotメニューに制限超過のリスクがないかすぐに確認したい場合は、次の手順を実行してください：

1. Botを開き、すべてのメニューページのスクリーンショットを撮ります。
2. 行ごとにボタン数をカウントし、各行 ≤ 8個、総ボタン数 ≤ 100個であることを確認します。
3. すべてのcallback_dataの長さを確認します（特に中国語や絵文字のバイト数に注意）。
4. 問題が見つかった場合は、TG-Staffのドラッグ＆ドロップエディタを使用してメニューを迅速に再構築します。これはUIレベルでインラインボタンの制限をリアルタイムに検証できる数少ないツールの1つです。

次のアクション：

• TG-Staffの3日間無料トライアルに登録：👉 https://app.tg-staff.com/
• ドラッグ＆ドロップエディタを使用してインラインキーボードメニューを再設計し、ボタン数とcallback_dataの長さをリアルタイムで検証
• 公式ドキュメントの「インラインキーボードのベストプラクティス」の章を参照：https://docs.tg-staff.com/
• 質問がある場合は、カスタマーサポートBotにお問い合わせください：@tgstaff_robot