Complete Guide to Telegram Inline Button Limits: How to Avoid Keyboard Restrictions and Design Efficient Menus

If you’re developing or operating a Telegram Bot, you’ve definitely encountered inline keyboards. They are the core entry point for bot-user interaction: clicking a button triggers order queries, language switching, ticket submission… almost every efficient menu relies on them.

But many developers don’t realize until after launch that their carefully designed menus are “missing pieces” on Telegram clients—buttons disappearing, clicks unresponsive, layout breaking after multilingual translation. The root cause is often a lack of understanding of Telegram’s inline button limits.

This article will break down the 5 core limit parameters related to inline keyboards in the Telegram Bot API, and then provide 4 practical solutions derived from real-world operational scenarios. Finally, you’ll see how using a visual tool like TG-Staff can help you avoid these restrictions during development, preventing online incidents.

Why Telegram Inline Button Limits Affect Your Bot Menu Design

Consider a real scenario: Your bot provides multilingual customer service for cross-border e-commerce clients. The menu has four main buttons: “View Order”, “Contact Support”, “Switch Language”, and “FAQ”. The Chinese version looks perfect, but when switched to German, the button text becomes longer, turning a 2-button row into a 1-button row, requiring users to scroll an extra screen to see all options.

This isn’t the worst case. If you accidentally assign 9 buttons to a row in code, or write a callback_data string exceeding 64 bytes, Telegram will silently ignore the excess—users see an incomplete menu, clicking some buttons does nothing, and you can’t find anything in server logs.

Such issues are hard to reproduce during development because developers often only test with their commonly used language and button count. Once in a real environment with multiple languages, devices, and users, inline button limits become a “hidden pitfall”.

Knowing these limit parameters in advance and actively validating them during menu design is the most effective way to avoid online failures.

The 5 Core Limit Parameters of Telegram Inline Buttons (Official Documentation Interpretation)

The Telegram Bot API documentation clearly specifies limits for inline keyboards. Here are the five most critical parameters, each of which can become a bottleneck in your menu design.

Quantity and Layout Limits: Up to 8 Buttons Per Row, 100 Total Buttons

This is the most intuitive limit and the one developers often overlook.

• Buttons per row: ≤ 8. If you place 9 buttons in a row, Telegram ignores the 9th and subsequent buttons.
• Total buttons: ≤ 100. The entire inline keyboard (all rows combined) cannot exceed 100 buttons.
• Number of rows: The API docs don’t explicitly limit rows, but it’s constrained by the total button count ≤ 100. For example, if you put 5 buttons per row, you can have up to 20 rows; with 8 per row, only 12 rows (8 × 12 = 96, insufficient space for another row).

In practice, it’s recommended to limit buttons per row to ≤ 5, especially on mobile. Telegram clients automatically adjust button width based on screen size: 8 buttons per row may be barely acceptable on desktop, but on mobile screens they become very narrow and hard to tap accurately.

Callback Data Length Limit: 1–64 Bytes

This is the “hidden trap” of inline buttons. callback_data is the data sent back to the bot when a button is clicked. Telegram requires its length to be between 1 and 64 bytes.

When it exceeds 64 bytes, Telegram returns no error, but the button click becomes unresponsive—users don’t know what happened, and you can’t find any logs.

Byte calculation notes:

• English letters and numbers: 1 byte per character
• Chinese characters: 3 bytes per character (UTF-8 encoding)
• Emoji: 4 bytes each

For example, callback_data = "order_20250315_zh_cn_001" doesn’t look long, but its actual length is 29 bytes. Meanwhile, callback_data = "查询订单_2025年3月15日_中文版" with many Chinese characters can easily exceed 64 bytes.

Best practice: Use short code mapping. For instance, store a short ID in the database, and callback_data only passes id=12345, then the bot looks up the database by ID to get full data. TG-Staff’s auto-translation feature can also help convert long text into short identifiers, avoiding length issues.

Button Text Length and Multi-line Support Implicit Rules

Telegram doesn’t have a hard limit on button text length, but in practice:

• When text is too long, Telegram clients automatically wrap it, but the wrapping position is uncontrollable, leading to inconsistent button heights.
• If text exceeds 64 characters, some client versions truncate it (add ellipsis at the end).

It’s recommended to keep button text within 20 characters (English) or 10 Chinese characters. This ensures full display on most screens without layout issues due to wrapping.

In multilingual scenarios, text length varies greatly between languages. For example, “查看订单” is 4 characters in Chinese, but 12 characters in German (“Bestellung anzeigen”). If you don’t design button text per language, you may end up with uneven button widths and poor layout.

Menu Design Pitfalls: 4 Common Problems Caused by Limits and Their Solutions

These 4 problems are the most common traps for bot operation teams. Each problem comes with actionable solutions.

Problem 1: Menu Buttons “Disappear” or an Extra Row Appears

Symptom: You defined 6 buttons in a row in code, but users see only 5; or the total button count exceeds 100, and the last few buttons simply vanish.

Cause: Violation of ≤ 8 per row and ≤ 100 total. Telegram silently ignores the excess.

Solution:

• Validate in code before sending the keyboard: iterate through the array to check each row ≤ 8 and total ≤ 100.
• If using TG-Staff’s visual flow editor, the right panel shows real-time total button count and per-row count while dragging buttons. When limits are exceeded, the editor automatically warns and prevents saving.

Problem 2: User Clicks Button but No Response (Callback Data Too Long)

Symptom: User clicks a button, the bot receives no callback, and no error is returned. Investigation reveals callback_data exceeds 64 bytes.

Cause: callback_data exceeds 64 bytes, and Telegram discards the data.

Solution:

• Use short code mapping. For example, change callback_data = "order_detail_20250315_zh_cn_001" to callback_data = "od_12345", then query the database on the server side with the ID to get full information.
• Leverage TG-Staff’s auto-translation feature to automatically convert long text into short identifiers, avoiding manual handling.

Problem 3: Multilingual Menu Buttons Misaligned After Translation

Symptom: The same menu looks neat in Chinese, but when switched to German or Russian, button widths become inconsistent, even causing a visual “button overlap”.

Cause: Different language text lengths cause Telegram clients to adjust button widths automatically, but the adjustment logic is uncontrollable.

Solution:

• Design button text lengths per language. Keep Chinese text at 4-6 characters, English at 8-12 characters, German at 10-15 characters.
• Use icon + short text combinations. For example, use 📦 + “Order” instead of “View Order Details”. Icons occupy stable space, and short text adapts well.
• In TG-Staff’s editor, you can configure button text independently for each language version, avoiding misalignment from a single global text.

Problem 4: Dynamically Updated Keyboard Exceeds Limits

Symptom: You dynamically update the keyboard after a user clicks a button (e.g., pagination), and the new keyboard’s button count exceeds 100, causing some buttons not to display.

Cause: The dynamically generated keyboard wasn’t re-validated against limits.

Solution:

• Before generating each new keyboard, validate total ≤ 100 and per row ≤ 8.
• If data volume is large, consider pagination: display 50 buttons per page (5 rows × 10 columns), and update the keyboard when the user clicks “Next Page”.
• TG-Staff’s editor supports auto-pagination: you can set “max N buttons per page”, and the editor automatically generates page-turn buttons when exceeded.

Practical Example: Using TG-Staff’s Drag-and-Drop Editor to Avoid Inline Button Limits

Suppose you’re designing a multilingual customer service menu with the following features:

• View Order (3 statuses: Pending Payment, Paid, Shipped)
• Contact Support
• Switch Language (supports 8 languages)
• FAQ (5 categories)

Without limits, the total button count would be 3 + 1 + 8 + 5 = 17, and buttons per row could exceed 8. If you manually write JSON code, it’s easy to miss validation.

In TG-Staff’s drag-and-drop command flow editor, you can:

1. Drag an “Inline Keyboard” node onto the canvas.
2. In the right panel, add buttons sequentially: first row with “View Order”, “Contact Support”, “FAQ”; second row with 8 language switch buttons.
3. The editor displays real-time total button count (11) and per-row counts (first row: 3, second row: 8). If any row exceeds 8, the editor highlights it in red and prevents saving.
4. If you need to add more buttons (e.g., “Pending Payment”, “Paid”, “Shipped” as sub-menus), create a new keyboard node and connect it with a “Jump” action instead of cramming all buttons into one keyboard.

Inline Buttons vs Reply Keyboard: When to Use Which Interaction?

Many developers confuse inline buttons and reply keyboards. The core differences are:

Aspect	Inline Buttons	Reply Keyboard
Display Position	Below the message, attached to it	Above the input field, independent of the message
Button Count Limit	≤ 100 (≤ 8 per row)	No hard limit, but recommend ≤ 20
Callback Data	Supports callback_data (≤ 64 bytes)	Not supported; sends text directly on tap
Use Cases	Multi-step selection, data queries, pagination	Text input guidance, quick replies
User Experience	Does not occupy input field, retains chat history	Obscures input field, suitable for short replies

Decision Criteria:

• If users need to select from multiple options (e.g., choosing order status, switching languages), use inline buttons.
• If users only need to input short text (e.g., replying “yes”/“no”, entering keywords), use reply keyboard.
• If menu content exceeds 100 buttons (e.g., product list), consider paginated inline buttons or switch to input guidance with keyword matching.

Common FAQs: 4 Frequent Questions About Inline Button Limits

Q1: When dynamically updating buttons, are limits recalculated? A: Yes. Each time you update the keyboard via editMessageReplyMarkup or editMessageText, Telegram re-validates the new keyboard’s button count, row count, and callback_data length. If the new keyboard exceeds limits, the update fails and returns an error.

Q2: Do limits vary by client version? A: No. These limits are hard specifications of the Telegram Bot API, and all client versions (iOS, Android, desktop) follow the same limits. However, display may vary slightly (e.g., button width, line wrapping).

Q3: Do paid bots have higher limits? A: No. The Telegram Bot API treats all bots equally, regardless of payment or third-party platforms (e.g., TG-Staff); limits are identical.

Q4: Can callback_data use Chinese characters? A: Yes, but be mindful of byte length. Chinese characters occupy 3 bytes, emoji 4 bytes. It’s recommended to use short codes for mapping rather than passing Chinese text directly.

Summary and Next Steps

Telegram inline button limitations may seem simple, but they are often overlooked in actual development. Remember three core numbers: ≤ 8 buttons per row, ≤ 100 buttons in total keyboard, callback_data ≤ 64 bytes.

If you want to immediately check whether your existing Bot menu exceeds the limits, you can do the following:

1. Open your Bot and take screenshots of all menu pages.
2. Count the number of buttons per row, ensuring ≤ 8 per row and total ≤ 100 buttons.
3. Check the length of all callback_data (especially the byte usage of Chinese characters and emojis).
4. If you find issues, quickly restructure the menu using TG-Staff’s drag-and-drop editor—it is currently one of the few tools that validates inline button limits in real-time at the UI level.

Next Steps:

• Register for a free 3-day trial of TG-Staff: 👉 https://app.tg-staff.com/
• Redesign the inline keyboard menu with the drag-and-drop editor, real-time validation of button count and callback_data length
• Refer to the “Inline Keyboard Best Practices” section in the official documentation: https://docs.tg-staff.com/
• For questions, contact the support Bot: @tgstaff_robot